mia-code 0.2.0 → 0.3.0

package/references/langchain/python/human-in-the-loop.md

@@ -0,0 +1,326 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Human-in-the-loop
+
+The Human-in-the-Loop (HITL) [middleware](/oss/python/langchain/middleware/built-in#human-in-the-loop) lets you add human oversight to agent tool calls.
+When a model proposes an action that might require review — for example, writing to a file or executing SQL — the middleware can pause execution and wait for a decision.
+
+It does this by checking each tool call against a configurable policy. If intervention is needed, the middleware issues an [interrupt](https://reference.langchain.com/python/langgraph/types/#langgraph.types.interrupt) that halts execution. The graph state is saved using LangGraph's [persistence layer](/oss/python/langgraph/persistence), so execution can pause safely and resume later.
+
+A human decision then determines what happens next: the action can be approved as-is (`approve`), modified before running (`edit`), or rejected with feedback (`reject`).
+
+## Interrupt decision types
+
+The [middleware](/oss/python/langchain/middleware/built-in#human-in-the-loop) defines three built-in ways a human can respond to an interrupt:
+
+| Decision Type | Description                                                               | Example Use Case                                    |
+| ------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
+| ✅ `approve`   | The action is approved as-is and executed without changes.                | Send an email draft exactly as written              |
+| ✏️ `edit`     | The tool call is executed with modifications.                             | Change the recipient before sending an email        |
+| ❌ `reject`    | The tool call is rejected, with an explanation added to the conversation. | Reject an email draft and explain how to rewrite it |
+
+The available decision types for each tool depend on the policy you configure in `interrupt_on`.
+When multiple tool calls are paused at the same time, each action requires a separate decision.
+Decisions must be provided in the same order as the actions appear in the interrupt request.
+
+<Tip>
+  When **editing** tool arguments, make changes conservatively. Significant modifications to the original arguments may cause the model to re-evaluate its approach and potentially execute the tool multiple times or take unexpected actions.
+</Tip>
+
+## Configuring interrupts
+
+To use HITL, add the [middleware](/oss/python/langchain/middleware/built-in#human-in-the-loop) to the agent's `middleware` list when creating the agent.
+
+You configure it with a mapping of tool actions to the decision types that are allowed for each action. The middleware will interrupt execution when a tool call matches an action in the mapping.
+
+```python  theme={null}
+from langchain.agents import create_agent
+from langchain.agents.middleware import HumanInTheLoopMiddleware # [!code highlight]
+from langgraph.checkpoint.memory import InMemorySaver # [!code highlight]
+
+
+agent = create_agent(
+    model="gpt-4.1",
+    tools=[write_file_tool, execute_sql_tool, read_data_tool],
+    middleware=[
+        HumanInTheLoopMiddleware( # [!code highlight]
+            interrupt_on={
+                "write_file": True,  # All decisions (approve, edit, reject) allowed
+                "execute_sql": {"allowed_decisions": ["approve", "reject"]},  # No editing allowed
+                # Safe operation, no approval needed
+                "read_data": False,
+            },
+            # Prefix for interrupt messages - combined with tool name and args to form the full message
+            # e.g., "Tool execution pending approval: execute_sql with query='DELETE FROM...'"
+            # Individual tools can override this by specifying a "description" in their interrupt config
+            description_prefix="Tool execution pending approval",
+        ),
+    ],
+    # Human-in-the-loop requires checkpointing to handle interrupts.
+    # In production, use a persistent checkpointer like AsyncPostgresSaver.
+    checkpointer=InMemorySaver(),  # [!code highlight]
+)
+```
+
+<Info>
+  You must configure a checkpointer to persist the graph state across interrupts.
+  In production, use a persistent checkpointer like [`AsyncPostgresSaver`](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.postgres.aio.AsyncPostgresSaver). For testing or prototyping, use [`InMemorySaver`](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.memory.InMemorySaver).
+
+  When invoking the agent, pass a `config` that includes the **thread ID** to associate execution with a conversation thread.
+  See the [LangGraph interrupts documentation](/oss/python/langgraph/interrupts) for details.
+</Info>
+
+<Accordion title="Configuration options">
+  <ParamField body="interrupt_on" type="dict" required>
+    Mapping of tool names to approval configs. Values can be `True` (interrupt with default config), `False` (auto-approve), or an `InterruptOnConfig` object.
+  </ParamField>
+
+  <ParamField body="description_prefix" type="string" default="Tool execution requires approval">
+    Prefix for action request descriptions
+  </ParamField>
+
+  **`InterruptOnConfig` options:**
+
+  <ParamField body="allowed_decisions" type="list[string]">
+    List of allowed decisions: `'approve'`, `'edit'`, or `'reject'`
+  </ParamField>
+
+  <ParamField body="description" type="string | callable">
+    Static string or callable function for custom description
+  </ParamField>
+</Accordion>
+
+## Responding to interrupts
+
+When you invoke the agent, it runs until it either completes or an interrupt is raised. An interrupt is triggered when a tool call matches the policy you configured in `interrupt_on`. In that case, the invocation result will include an `__interrupt__` field with the actions that require review. You can then present those actions to a reviewer and resume execution once decisions are provided.
+
+```python  theme={null}
+from langgraph.types import Command
+
+# Human-in-the-loop leverages LangGraph's persistence layer.
+# You must provide a thread ID to associate the execution with a conversation thread,
+# so the conversation can be paused and resumed (as is needed for human review).
+config = {"configurable": {"thread_id": "some_id"}} # [!code highlight]
+# Run the graph until the interrupt is hit.
+result = agent.invoke(
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "Delete old records from the database",
+            }
+        ]
+    },
+    config=config # [!code highlight]
+)
+
+# The interrupt contains the full HITL request with action_requests and review_configs
+print(result['__interrupt__'])
+# > [
+# >    Interrupt(
+# >       value={
+# >          'action_requests': [
+# >             {
+# >                'name': 'execute_sql',
+# >                'arguments': {'query': 'DELETE FROM records WHERE created_at < NOW() - INTERVAL \'30 days\';'},
+# >                'description': 'Tool execution pending approval\n\nTool: execute_sql\nArgs: {...}'
+# >             }
+# >          ],
+# >          'review_configs': [
+# >             {
+# >                'action_name': 'execute_sql',
+# >                'allowed_decisions': ['approve', 'reject']
+# >             }
+# >          ]
+# >       }
+# >    )
+# > ]
+
+
+# Resume with approval decision
+agent.invoke(
+    Command( # [!code highlight]
+        resume={"decisions": [{"type": "approve"}]}  # or "reject" [!code highlight]
+    ), # [!code highlight]
+    config=config # Same thread ID to resume the paused conversation
+)
+```
+
+### Decision types
+
+<Tabs>
+  <Tab title="✅ approve">
+    Use `approve` to approve the tool call as-is and execute it without changes.
+
+    ```python  theme={null}
+    agent.invoke(
+        Command(
+            # Decisions are provided as a list, one per action under review.
+            # The order of decisions must match the order of actions
+            # listed in the `__interrupt__` request.
+            resume={
+                "decisions": [
+                    {
+                        "type": "approve",
+                    }
+                ]
+            }
+        ),
+        config=config  # Same thread ID to resume the paused conversation
+    )
+    ```
+  </Tab>
+
+  <Tab title="✏️ edit">
+    Use `edit` to modify the tool call before execution.
+    Provide the edited action with the new tool name and arguments.
+
+    ```python  theme={null}
+    agent.invoke(
+        Command(
+            # Decisions are provided as a list, one per action under review.
+            # The order of decisions must match the order of actions
+            # listed in the `__interrupt__` request.
+            resume={
+                "decisions": [
+                    {
+                        "type": "edit",
+                        # Edited action with tool name and args
+                        "edited_action": {
+                            # Tool name to call.
+                            # Will usually be the same as the original action.
+                            "name": "new_tool_name",
+                            # Arguments to pass to the tool.
+                            "args": {"key1": "new_value", "key2": "original_value"},
+                        }
+                    }
+                ]
+            }
+        ),
+        config=config  # Same thread ID to resume the paused conversation
+    )
+    ```
+
+    <Tip>
+      When **editing** tool arguments, make changes conservatively. Significant modifications to the original arguments may cause the model to re-evaluate its approach and potentially execute the tool multiple times or take unexpected actions.
+    </Tip>
+  </Tab>
+
+  <Tab title="❌ reject">
+    Use `reject` to reject the tool call and provide feedback instead of execution.
+
+    ```python  theme={null}
+    agent.invoke(
+        Command(
+            # Decisions are provided as a list, one per action under review.
+            # The order of decisions must match the order of actions
+            # listed in the `__interrupt__` request.
+            resume={
+                "decisions": [
+                    {
+                        "type": "reject",
+                        # An explanation about why the action was rejected
+                        "message": "No, this is wrong because ..., instead do this ...",
+                    }
+                ]
+            }
+        ),
+        config=config  # Same thread ID to resume the paused conversation
+    )
+    ```
+
+    The `message` is added to the conversation as feedback to help the agent understand why the action was rejected and what it should do instead.
+
+    ***
+
+    ### Multiple decisions
+
+    When multiple actions are under review, provide a decision for each action in the same order as they appear in the interrupt:
+
+    ```python  theme={null}
+    {
+        "decisions": [
+            {"type": "approve"},
+            {
+                "type": "edit",
+                "edited_action": {
+                    "name": "tool_name",
+                    "args": {"param": "new_value"}
+                }
+            },
+            {
+                "type": "reject",
+                "message": "This action is not allowed"
+            }
+        ]
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Streaming with human-in-the-loop
+
+You can use `stream()` instead of `invoke()` to get real-time updates while the agent runs and handles interrupts. Use `stream_mode=['updates', 'messages']` to stream both agent progress and LLM tokens.
+
+```python  theme={null}
+from langgraph.types import Command
+
+config = {"configurable": {"thread_id": "some_id"}}
+
+# Stream agent progress and LLM tokens until interrupt
+for mode, chunk in agent.stream(
+    {"messages": [{"role": "user", "content": "Delete old records from the database"}]},
+    config=config,
+    stream_mode=["updates", "messages"],  # [!code highlight]
+):
+    if mode == "messages":
+        # LLM token
+        token, metadata = chunk
+        if token.content:
+            print(token.content, end="", flush=True)
+    elif mode == "updates":
+        # Check for interrupt
+        if "__interrupt__" in chunk:
+            print(f"\n\nInterrupt: {chunk['__interrupt__']}")
+
+# Resume with streaming after human decision
+for mode, chunk in agent.stream(
+    Command(resume={"decisions": [{"type": "approve"}]}),
+    config=config,
+    stream_mode=["updates", "messages"],
+):
+    if mode == "messages":
+        token, metadata = chunk
+        if token.content:
+            print(token.content, end="", flush=True)
+```
+
+See the [Streaming](/oss/python/langchain/streaming) guide for more details on stream modes.
+
+## Execution lifecycle
+
+The middleware defines an `after_model` hook that runs after the model generates a response but before any tool calls are executed:
+
+1. The agent invokes the model to generate a response.
+2. The middleware inspects the response for tool calls.
+3. If any calls require human input, the middleware builds a `HITLRequest` with `action_requests` and `review_configs` and calls [interrupt](https://reference.langchain.com/python/langgraph/types/#langgraph.types.interrupt).
+4. The agent waits for human decisions.
+5. Based on the `HITLResponse` decisions, the middleware executes approved or edited calls, synthesizes [ToolMessage](https://reference.langchain.com/python/langchain/messages/#langchain.messages.ToolMessage)'s for rejected calls, and resumes execution.
+
+## Custom HITL logic
+
+For more specialized workflows, you can build custom HITL logic directly using the [interrupt](https://reference.langchain.com/python/langgraph/types/#langgraph.types.interrupt) primitive and [middleware](/oss/python/langchain/middleware) abstraction.
+
+Review the [execution lifecycle](#execution-lifecycle) above to understand how to integrate interrupts into the agent's operation.
+
+***
+
+<Callout icon="pen-to-square" iconType="regular">
+  [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/human-in-the-loop.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
+</Callout>
+
+<Tip icon="terminal" iconType="regular">
+  [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
+</Tip>

package/references/langchain/python/long-term-memory.md

@@ -0,0 +1,168 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Long-term memory
+
+## Overview
+
+LangChain agents use [LangGraph persistence](/oss/python/langgraph/persistence#memory-store) to enable long-term memory. This is a more advanced topic and requires knowledge of LangGraph to use.
+
+## Memory storage
+
+LangGraph stores long-term memories as JSON documents in a [store](/oss/python/langgraph/persistence#memory-store).
+
+Each memory is organized under a custom `namespace` (similar to a folder) and a distinct `key` (like a file name). Namespaces often include user or org IDs or other labels that makes it easier to organize information.
+
+This structure enables hierarchical organization of memories. Cross-namespace searching is then supported through content filters.
+
+```python  theme={null}
+from langgraph.store.memory import InMemoryStore
+
+
+def embed(texts: list[str]) -> list[list[float]]:
+    # Replace with an actual embedding function or LangChain embeddings object
+    return [[1.0, 2.0] * len(texts)]
+
+
+# InMemoryStore saves data to an in-memory dictionary. Use a DB-backed store in production use.
+store = InMemoryStore(index={"embed": embed, "dims": 2}) # [!code highlight]
+user_id = "my-user"
+application_context = "chitchat"
+namespace = (user_id, application_context) # [!code highlight]
+store.put( # [!code highlight]
+    namespace,
+    "a-memory",
+    {
+        "rules": [
+            "User likes short, direct language",
+            "User only speaks English & python",
+        ],
+        "my-key": "my-value",
+    },
+)
+# get the "memory" by ID
+item = store.get(namespace, "a-memory") # [!code highlight]
+# search for "memories" within this namespace, filtering on content equivalence, sorted by vector similarity
+items = store.search( # [!code highlight]
+    namespace, filter={"my-key": "my-value"}, query="language preferences"
+)
+```
+
+For more information about the memory store, see the [Persistence](/oss/python/langgraph/persistence#memory-store) guide.
+
+## Read long-term memory in tools
+
+```python A tool the agent can use to look up user information theme={null}
+from dataclasses import dataclass
+
+from langchain_core.runnables import RunnableConfig
+from langchain.agents import create_agent
+from langchain.tools import tool, ToolRuntime
+from langgraph.store.memory import InMemoryStore
+
+
+@dataclass
+class Context:
+    user_id: str
+
+# InMemoryStore saves data to an in-memory dictionary. Use a DB-backed store in production.
+store = InMemoryStore() # [!code highlight]
+
+# Write sample data to the store using the put method
+store.put( # [!code highlight]
+    ("users",),  # Namespace to group related data together (users namespace for user data)
+    "user_123",  # Key within the namespace (user ID as key)
+    {
+        "name": "John Smith",
+        "language": "English",
+    }  # Data to store for the given user
+)
+
+@tool
+def get_user_info(runtime: ToolRuntime[Context]) -> str:
+    """Look up user info."""
+    # Access the store - same as that provided to `create_agent`
+    store = runtime.store # [!code highlight]
+    user_id = runtime.context.user_id
+    # Retrieve data from store - returns StoreValue object with value and metadata
+    user_info = store.get(("users",), user_id) # [!code highlight]
+    return str(user_info.value) if user_info else "Unknown user"
+
+agent = create_agent(
+    model="claude-sonnet-4-5-20250929",
+    tools=[get_user_info],
+    # Pass store to agent - enables agent to access store when running tools
+    store=store, # [!code highlight]
+    context_schema=Context
+)
+
+# Run the agent
+agent.invoke(
+    {"messages": [{"role": "user", "content": "look up user information"}]},
+    context=Context(user_id="user_123") # [!code highlight]
+)
+```
+
+<a id="write-long-term" />
+
+## Write long-term memory from tools
+
+```python Example of a tool that updates user information theme={null}
+from dataclasses import dataclass
+from typing_extensions import TypedDict
+
+from langchain.agents import create_agent
+from langchain.tools import tool, ToolRuntime
+from langgraph.store.memory import InMemoryStore
+
+
+# InMemoryStore saves data to an in-memory dictionary. Use a DB-backed store in production.
+store = InMemoryStore() # [!code highlight]
+
+@dataclass
+class Context:
+    user_id: str
+
+# TypedDict defines the structure of user information for the LLM
+class UserInfo(TypedDict):
+    name: str
+
+# Tool that allows agent to update user information (useful for chat applications)
+@tool
+def save_user_info(user_info: UserInfo, runtime: ToolRuntime[Context]) -> str:
+    """Save user info."""
+    # Access the store - same as that provided to `create_agent`
+    store = runtime.store # [!code highlight]
+    user_id = runtime.context.user_id # [!code highlight]
+    # Store data in the store (namespace, key, data)
+    store.put(("users",), user_id, user_info) # [!code highlight]
+    return "Successfully saved user info."
+
+agent = create_agent(
+    model="claude-sonnet-4-5-20250929",
+    tools=[save_user_info],
+    store=store, # [!code highlight]
+    context_schema=Context
+)
+
+# Run the agent
+agent.invoke(
+    {"messages": [{"role": "user", "content": "My name is John Smith"}]},
+    # user_id passed in context to identify whose information is being updated
+    context=Context(user_id="user_123") # [!code highlight]
+)
+
+# You can access the store directly to get the value
+store.get(("users",), "user_123").value
+```
+
+***
+
+<Callout icon="pen-to-square" iconType="regular">
+  [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/long-term-memory.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
+</Callout>
+
+<Tip icon="terminal" iconType="regular">
+  [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
+</Tip>