mia-code 0.2.0 → 0.3.0

package/references/langchain/python/retrieval.md

@@ -0,0 +1,320 @@
+> ## 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.
+
+# Retrieval
+
+Large Language Models (LLMs) are powerful, but they have two key limitations:
+
+* **Finite context** — they can’t ingest entire corpora at once.
+* **Static knowledge** — their training data is frozen at a point in time.
+
+Retrieval addresses these problems by fetching relevant external knowledge at query time. This is the foundation of **Retrieval-Augmented Generation (RAG)**: enhancing an LLM’s answers with context-specific information.
+
+## Building a knowledge base
+
+A **knowledge base** is a repository of documents or structured data used during retrieval.
+
+If you need a custom knowledge base, you can use LangChain’s document loaders and vector stores to build one from your own data.
+
+<Note>
+  If you already have a knowledge base (e.g., a SQL database, CRM, or internal documentation system), you do **not** need to rebuild it. You can:
+
+  * Connect it as a **tool** for an agent in Agentic RAG.
+  * Query it and supply the retrieved content as context to the LLM [(2-Step RAG)](#2-step-rag).
+</Note>
+
+See the following tutorial to build a searchable knowledge base and minimal RAG workflow:
+
+<Card title="Tutorial: Semantic search" icon="database" href="/oss/python/langchain/knowledge-base" arrow cta="Learn more">
+  Learn how to create a searchable knowledge base from your own data using LangChain’s document loaders, embeddings, and vector stores.
+  In this tutorial, you’ll build a search engine over a PDF, enabling retrieval of passages relevant to a query. You’ll also implement a minimal RAG workflow on top of this engine to see how external knowledge can be integrated into LLM reasoning.
+</Card>
+
+### From retrieval to RAG
+
+Retrieval allows LLMs to access relevant context at runtime. But most real-world applications go one step further: they **integrate retrieval with generation** to produce grounded, context-aware answers.
+
+This is the core idea behind **Retrieval-Augmented Generation (RAG)**. The retrieval pipeline becomes a foundation for a broader system that combines search with generation.
+
+### Retrieval pipeline
+
+A typical retrieval workflow looks like this:
+
+```mermaid  theme={null}
+flowchart LR
+  S(["Sources<br>(Google Drive, Slack, Notion, etc.)"]) --> L[Document Loaders]
+  L --> A([Documents])
+  A --> B[Split into chunks]
+  B --> C[Turn into embeddings]
+  C --> D[(Vector Store)]
+  Q([User Query]) --> E[Query embedding]
+  E --> D
+  D --> F[Retriever]
+  F --> G[LLM uses retrieved info]
+  G --> H([Answer])
+```
+
+Each component is modular: you can swap loaders, splitters, embeddings, or vector stores without rewriting the app’s logic.
+
+### Building blocks
+
+<Columns cols={2}>
+  <Card title="Document loaders" icon="file-import" href="/oss/python/integrations/document_loaders" arrow cta="Learn more">
+    Ingest data from external sources (Google Drive, Slack, Notion, etc.), returning standardized [`Document`](https://reference.langchain.com/python/langchain_core/documents/#langchain_core.documents.base.Document) objects.
+  </Card>
+
+  <Card title="Text splitters" icon="scissors" href="/oss/python/integrations/splitters" arrow cta="Learn more">
+    Break large docs into smaller chunks that will be retrievable individually and fit within a model's context window.
+  </Card>
+
+  <Card title="Embedding models" icon="diagram-project" href="/oss/python/integrations/text_embedding" arrow cta="Learn more">
+    An embedding model turns text into a vector of numbers so that texts with similar meaning land close together in that vector space.
+  </Card>
+
+  <Card title="Vector stores" icon="database" href="/oss/python/integrations/vectorstores/" arrow cta="Learn more">
+    Specialized databases for storing and searching embeddings.
+  </Card>
+
+  <Card title="Retrievers" icon="binoculars" href="/oss/python/integrations/retrievers/" arrow cta="Learn more">
+    A retriever is an interface that returns documents given an unstructured query.
+  </Card>
+</Columns>
+
+## RAG architectures
+
+RAG can be implemented in multiple ways, depending on your system's needs. We outline each type in the sections below.
+
+| Architecture    | Description                                                                | Control   | Flexibility | Latency    | Example Use Case                                  |
+| --------------- | -------------------------------------------------------------------------- | --------- | ----------- | ---------- | ------------------------------------------------- |
+| **2-Step RAG**  | Retrieval always happens before generation. Simple and predictable         | ✅ High    | ❌ Low       | ⚡ Fast     | FAQs, documentation bots                          |
+| **Agentic RAG** | An LLM-powered agent decides *when* and *how* to retrieve during reasoning | ❌ Low     | ✅ High      | ⏳ Variable | Research assistants with access to multiple tools |
+| **Hybrid**      | Combines characteristics of both approaches with validation steps          | ⚖️ Medium | ⚖️ Medium   | ⏳ Variable | Domain-specific Q\&A with quality validation      |
+
+<Info>
+  **Latency**: Latency is generally more **predictable** in **2-Step RAG**, as the maximum number of LLM calls is known and capped. This predictability assumes that LLM inference time is the dominant factor. However, real-world latency may also be affected by the performance of retrieval steps—such as API response times, network delays, or database queries—which can vary based on the tools and infrastructure in use.
+</Info>
+
+### 2-step RAG
+
+In **2-Step RAG**, the retrieval step is always executed before the generation step. This architecture is straightforward and predictable, making it suitable for many applications where the retrieval of relevant documents is a clear prerequisite for generating an answer.
+
+```mermaid  theme={null}
+graph LR
+    A[User Question] --> B["Retrieve Relevant Documents"]
+    B --> C["Generate Answer"]
+    C --> D[Return Answer to User]
+
+    %% Styling
+    classDef startend fill:#2e7d32,stroke:#1b5e20,stroke-width:2px,color:#fff
+    classDef process fill:#1976d2,stroke:#0d47a1,stroke-width:1.5px,color:#fff
+
+    class A,D startend
+    class B,C process
+```
+
+<Card title="Tutorial: Retrieval-Augmented Generation (RAG)" icon="robot" href="/oss/python/langchain/rag#rag-chains" arrow cta="Learn more">
+  See how to build a Q\&A chatbot that can answer questions grounded in your data using Retrieval-Augmented Generation.
+  This tutorial walks through two approaches:
+
+  * A **RAG agent** that runs searches with a flexible tool—great for general-purpose use.
+  * A **2-step RAG** chain that requires just one LLM call per query—fast and efficient for simpler tasks.
+</Card>
+
+### Agentic RAG
+
+**Agentic Retrieval-Augmented Generation (RAG)** combines the strengths of Retrieval-Augmented Generation with agent-based reasoning. Instead of retrieving documents before answering, an agent (powered by an LLM) reasons step-by-step and decides **when** and **how** to retrieve information during the interaction.
+
+<Tip>
+  The only thing an agent needs to enable RAG behavior is access to one or more **tools** that can fetch external knowledge — such as documentation loaders, web APIs, or database queries.
+</Tip>
+
+```mermaid  theme={null}
+graph LR
+    A[User Input / Question] --> B["Agent (LLM)"]
+    B --> C{Need external info?}
+    C -- Yes --> D["Search using tool(s)"]
+    D --> H{Enough to answer?}
+    H -- No --> B
+    H -- Yes --> I[Generate final answer]
+    C -- No --> I
+    I --> J[Return to user]
+
+    %% Dark-mode friendly styling
+    classDef startend fill:#2e7d32,stroke:#1b5e20,stroke-width:2px,color:#fff
+    classDef decision fill:#f9a825,stroke:#f57f17,stroke-width:2px,color:#000
+    classDef process fill:#1976d2,stroke:#0d47a1,stroke-width:1.5px,color:#fff
+
+    class A,J startend
+    class B,D,I process
+    class C,H decision
+```
+
+```python  theme={null}
+import requests
+from langchain.tools import tool
+from langchain.chat_models import init_chat_model
+from langchain.agents import create_agent
+
+
+@tool
+def fetch_url(url: str) -> str:
+    """Fetch text content from a URL"""
+    response = requests.get(url, timeout=10.0)
+    response.raise_for_status()
+    return response.text
+
+system_prompt = """\
+Use fetch_url when you need to fetch information from a web-page; quote relevant snippets.
+"""
+
+agent = create_agent(
+    model="claude-sonnet-4-5-20250929",
+    tools=[fetch_url], # A tool for retrieval [!code highlight]
+    system_prompt=system_prompt,
+)
+```
+
+<Expandable title="Extended example: Agentic RAG for LangGraph's llms.txt">
+  This example implements an **Agentic RAG system** to assist users in querying LangGraph documentation. The agent begins by loading [llms.txt](https://llmstxt.org/), which lists available documentation URLs, and can then dynamically use a `fetch_documentation` tool to retrieve and process the relevant content based on the user’s question.
+
+  ```python  theme={null}
+  import requests
+  from langchain.agents import create_agent
+  from langchain.messages import HumanMessage
+  from langchain.tools import tool
+  from markdownify import markdownify
+
+
+  ALLOWED_DOMAINS = ["https://langchain-ai.github.io/"]
+  LLMS_TXT = 'https://langchain-ai.github.io/langgraph/llms.txt'
+
+
+  @tool
+  def fetch_documentation(url: str) -> str:  # [!code highlight]
+      """Fetch and convert documentation from a URL"""
+      if not any(url.startswith(domain) for domain in ALLOWED_DOMAINS):
+          return (
+              "Error: URL not allowed. "
+              f"Must start with one of: {', '.join(ALLOWED_DOMAINS)}"
+          )
+      response = requests.get(url, timeout=10.0)
+      response.raise_for_status()
+      return markdownify(response.text)
+
+
+  # We will fetch the content of llms.txt, so this can
+  # be done ahead of time without requiring an LLM request.
+  llms_txt_content = requests.get(LLMS_TXT).text
+
+  # System prompt for the agent
+  system_prompt = f"""
+  You are an expert Python developer and technical assistant.
+  Your primary role is to help users with questions about LangGraph and related tools.
+
+  Instructions:
+
+  1. If a user asks a question you're unsure about — or one that likely involves API usage,
+     behavior, or configuration — you MUST use the `fetch_documentation` tool to consult the relevant docs.
+  2. When citing documentation, summarize clearly and include relevant context from the content.
+  3. Do not use any URLs outside of the allowed domain.
+  4. If a documentation fetch fails, tell the user and proceed with your best expert understanding.
+
+  You can access official documentation from the following approved sources:
+
+  {llms_txt_content}
+
+  You MUST consult the documentation to get up to date documentation
+  before answering a user's question about LangGraph.
+
+  Your answers should be clear, concise, and technically accurate.
+  """
+
+  tools = [fetch_documentation]
+
+  model = init_chat_model("claude-sonnet-4-0", max_tokens=32_000)
+
+  agent = create_agent(
+      model=model,
+      tools=tools,  # [!code highlight]
+      system_prompt=system_prompt,  # [!code highlight]
+      name="Agentic RAG",
+  )
+
+  response = agent.invoke({
+      'messages': [
+          HumanMessage(content=(
+              "Write a short example of a langgraph agent using the "
+              "prebuilt create react agent. the agent should be able "
+              "to look up stock pricing information."
+          ))
+      ]
+  })
+
+  print(response['messages'][-1].content)
+  ```
+</Expandable>
+
+<Card title="Tutorial: Retrieval-Augmented Generation (RAG)" icon="robot" href="/oss/python/langchain/rag" arrow cta="Learn more">
+  See how to build a Q\&A chatbot that can answer questions grounded in your data using Retrieval-Augmented Generation.
+  This tutorial walks through two approaches:
+
+  * A **RAG agent** that runs searches with a flexible tool—great for general-purpose use.
+  * A **2-step RAG** chain that requires just one LLM call per query—fast and efficient for simpler tasks.
+</Card>
+
+### Hybrid RAG
+
+Hybrid RAG combines characteristics of both 2-Step and Agentic RAG. It introduces intermediate steps such as query preprocessing, retrieval validation, and post-generation checks. These systems offer more flexibility than fixed pipelines while maintaining some control over execution.
+
+Typical components include:
+
+* **Query enhancement**: Modify the input question to improve retrieval quality. This can involve rewriting unclear queries, generating multiple variations, or expanding queries with additional context.
+* **Retrieval validation**: Evaluate whether retrieved documents are relevant and sufficient. If not, the system may refine the query and retrieve again.
+* **Answer validation**: Check the generated answer for accuracy, completeness, and alignment with source content. If needed, the system can regenerate or revise the answer.
+
+The architecture often supports multiple iterations between these steps:
+
+```mermaid  theme={null}
+graph LR
+    A[User Question] --> B[Query Enhancement]
+    B --> C[Retrieve Documents]
+    C --> D{Sufficient Info?}
+    D -- No --> E[Refine Query]
+    E --> C
+    D -- Yes --> F[Generate Answer]
+    F --> G{Answer Quality OK?}
+    G -- No --> H{Try Different Approach?}
+    H -- Yes --> E
+    H -- No --> I[Return Best Answer]
+    G -- Yes --> I
+    I --> J[Return to User]
+
+    classDef startend fill:#2e7d32,stroke:#1b5e20,stroke-width:2px,color:#fff
+    classDef decision fill:#f9a825,stroke:#f57f17,stroke-width:2px,color:#000
+    classDef process fill:#1976d2,stroke:#0d47a1,stroke-width:1.5px,color:#fff
+
+    class A,J startend
+    class B,C,E,F,I process
+    class D,G,H decision
+```
+
+This architecture is suitable for:
+
+* Applications with ambiguous or underspecified queries
+* Systems that require validation or quality control steps
+* Workflows involving multiple sources or iterative refinement
+
+<Card title="Tutorial: Agentic RAG with Self-Correction" icon="robot" href="/oss/python/langgraph/agentic-rag" arrow cta="Learn more">
+  An example of **Hybrid RAG** that combines agentic reasoning with retrieval and self-correction.
+</Card>
+
+***
+
+<Callout icon="pen-to-square" iconType="regular">
+  [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/retrieval.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/runtime.md

@@ -0,0 +1,141 @@
+> ## 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.
+
+# Runtime
+
+## Overview
+
+LangChain's [`create_agent`](https://reference.langchain.com/python/langchain/agents/#langchain.agents.create_agent) runs on LangGraph's runtime under the hood.
+
+LangGraph exposes a [`Runtime`](https://reference.langchain.com/python/langgraph/runtime/#langgraph.runtime.Runtime) object with the following information:
+
+1. **Context**: static information like user id, db connections, or other dependencies for an agent invocation
+2. **Store**: a [BaseStore](https://reference.langchain.com/python/langgraph/store/#langgraph.store.base.BaseStore) instance used for [long-term memory](/oss/python/langchain/long-term-memory)
+3. **Stream writer**: an object used for streaming information via the `"custom"` stream mode
+
+<Tip>
+  Runtime context provides **dependency injection** for your tools and middleware. Instead of hardcoding values or using global state, you can inject runtime dependencies (like database connections, user IDs, or configuration) when invoking your agent. This makes your tools more testable, reusable, and flexible.
+</Tip>
+
+You can access the runtime information within [tools](#inside-tools) and [middleware](#inside-middleware).
+
+## Access
+
+When creating an agent with [`create_agent`](https://reference.langchain.com/python/langchain/agents/#langchain.agents.create_agent), you can specify a `context_schema` to define the structure of the `context` stored in the agent [`Runtime`](https://reference.langchain.com/python/langgraph/runtime/#langgraph.runtime.Runtime).
+
+When invoking the agent, pass the `context` argument with the relevant configuration for the run:
+
+```python  theme={null}
+from dataclasses import dataclass
+
+from langchain.agents import create_agent
+
+
+@dataclass
+class Context:
+    user_name: str
+
+agent = create_agent(
+    model="gpt-5-nano",
+    tools=[...],
+    context_schema=Context  # [!code highlight]
+)
+
+agent.invoke(
+    {"messages": [{"role": "user", "content": "What's my name?"}]},
+    context=Context(user_name="John Smith")  # [!code highlight]
+)
+```
+
+### Inside tools
+
+You can access the runtime information inside tools to:
+
+* Access the context
+* Read or write long-term memory
+* Write to the [custom stream](/oss/python/langchain/streaming#custom-updates) (ex, tool progress / updates)
+
+Use the `ToolRuntime` parameter to access the [`Runtime`](https://reference.langchain.com/python/langgraph/runtime/#langgraph.runtime.Runtime) object inside a tool.
+
+```python  theme={null}
+from dataclasses import dataclass
+from langchain.tools import tool, ToolRuntime  # [!code highlight]
+
+@dataclass
+class Context:
+    user_id: str
+
+@tool
+def fetch_user_email_preferences(runtime: ToolRuntime[Context]) -> str:  # [!code highlight]
+    """Fetch the user's email preferences from the store."""
+    user_id = runtime.context.user_id  # [!code highlight]
+
+    preferences: str = "The user prefers you to write a brief and polite email."
+    if runtime.store:  # [!code highlight]
+        if memory := runtime.store.get(("users",), user_id):  # [!code highlight]
+            preferences = memory.value["preferences"]
+
+    return preferences
+```
+
+### Inside middleware
+
+You can access runtime information in middleware to create dynamic prompts, modify messages, or control agent behavior based on user context.
+
+Use the `Runtime` parameter to access the [`Runtime`](https://reference.langchain.com/python/langgraph/runtime/#langgraph.runtime.Runtime) object inside [node-style hooks](/oss/python/langchain/middleware/custom#node-style-hooks).  For [wrap-style hooks](/oss/python/langchain/middleware/custom#wrap-style-hooks), the `Runtime` object is available inside the [`ModelRequest`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.ModelRequest) parameter.
+
+```python  theme={null}
+from dataclasses import dataclass
+
+from langchain.messages import AnyMessage
+from langchain.agents import create_agent, AgentState
+from langchain.agents.middleware import dynamic_prompt, ModelRequest, before_model, after_model
+from langgraph.runtime import Runtime
+
+
+@dataclass
+class Context:
+    user_name: str
+
+# Dynamic prompts
+@dynamic_prompt
+def dynamic_system_prompt(request: ModelRequest) -> str:
+    user_name = request.runtime.context.user_name  # [!code highlight]
+    system_prompt = f"You are a helpful assistant. Address the user as {user_name}."
+    return system_prompt
+
+# Before model hook
+@before_model
+def log_before_model(state: AgentState, runtime: Runtime[Context]) -> dict | None:  # [!code highlight]
+    print(f"Processing request for user: {runtime.context.user_name}")  # [!code highlight]
+    return None
+
+# After model hook
+@after_model
+def log_after_model(state: AgentState, runtime: Runtime[Context]) -> dict | None:  # [!code highlight]
+    print(f"Completed request for user: {runtime.context.user_name}")  # [!code highlight]
+    return None
+
+agent = create_agent(
+    model="gpt-5-nano",
+    tools=[...],
+    middleware=[dynamic_system_prompt, log_before_model, log_after_model],  # [!code highlight]
+    context_schema=Context
+)
+
+agent.invoke(
+    {"messages": [{"role": "user", "content": "What's my name?"}]},
+    context=Context(user_name="John Smith")
+)
+```
+
+***
+
+<Callout icon="pen-to-square" iconType="regular">
+  [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/runtime.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>