10xscale-agentflow-cli 0.3.2.8__tar.gz → 0.3.2.9__tar.gz

{10xscale_agentflow_cli-0.3.2.8 → 10xscale_agentflow_cli-0.3.2.9}/10xscale_agentflow_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 10xscale-agentflow-cli
-Version: 0.3.2.8
+Version: 0.3.2.9
 Summary: CLI and API for 10xscale AgentFlow
 Author-email: 10xscale <contact@10xscale.ai>
 Maintainer-email: Shudipto Trafder <shudiptotrafder@gmail.com>
@@ -47,6 +47,11 @@ Provides-Extra: media
 Requires-Dist: textxtract[docx,html,md,pdf,xml]>=0.2.0; extra == "media"
 Provides-Extra: gcloud
 Requires-Dist: google-cloud-logging; extra == "gcloud"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"
 
 # AgentFlow CLI
 

{10xscale_agentflow_cli-0.3.2.8 → 10xscale_agentflow_cli-0.3.2.9}/10xscale_agentflow_cli.egg-info/SOURCES.txt

@@ -1,8 +1,8 @@
 MANIFEST.in
 README.md
 agentflow.json
+plan.md
 pyproject.toml
-requirements.txt
 10xscale_agentflow_cli.egg-info/PKG-INFO
 10xscale_agentflow_cli.egg-info/SOURCES.txt
 10xscale_agentflow_cli.egg-info/dependency_links.txt
@@ -44,13 +44,8 @@ agentflow_cli/cli/templates/prod/graph/__init__.py
 agentflow_cli/cli/templates/prod/graph/agent.py
 agentflow_cli/cli/templates/prod/graph/state.py
 agentflow_cli/cli/templates/prod/graph/thread_name_generator.py
-agentflow_cli/cli/templates/prod/graph/nodes/__init__.py
-agentflow_cli/cli/templates/prod/graph/nodes/main_node.py
-agentflow_cli/cli/templates/prod/graph/nodes/tool_node.py
 agentflow_cli/cli/templates/prod/graph/tools/__init__.py
 agentflow_cli/cli/templates/prod/graph/tools/weather_tool.py
-agentflow_cli/cli/templates/prod/graph/utils/__init__.py
-agentflow_cli/cli/templates/prod/graph/utils/tool_decision.py
 agentflow_cli/cli/templates/prod/graph/validators/__init__.py
 agentflow_cli/cli/templates/prod/graph/validators/lifecyle.py
 agentflow_cli/cli/templates/prod/graph/validators/manager.py
@@ -60,7 +55,6 @@ agentflow_cli/cli/templates/prod/tests/conftest.py
 agentflow_cli/cli/templates/prod/tests/test_agent_eval.py
 agentflow_cli/cli/templates/prod/tests/test_catalog_tools.py
 agentflow_cli/cli/templates/prod/tests/test_graph_nodes.py
-agentflow_cli/cli/templates/skills/agent-skills/SKILL.md
 agentflow_cli/cli/templates/skills/agent-skills/references/agents-and-tools.md
 agentflow_cli/cli/templates/skills/agent-skills/references/api-client.md
 agentflow_cli/cli/templates/skills/agent-skills/references/api-configuration.md
@@ -93,6 +87,8 @@ agentflow_cli/cli/templates/skills/agent-skills/references/stream-emitter.md
 agentflow_cli/cli/templates/skills/agent-skills/references/streaming.md
 agentflow_cli/cli/templates/skills/agent-skills/references/testing-and-evaluation.md
 agentflow_cli/cli/templates/skills/agent-skills/references/unit-testing.md
+agentflow_cli/cli/templates/skills/claude/SKILL.md
+agentflow_cli/cli/templates/skills/codex/SKILL.md
 agentflow_cli/cli/templates/skills/copilot/agentflow.instructions.md
 agentflow_cli/src/__init__.py
 agentflow_cli/src/app/__init__.py

{10xscale_agentflow_cli-0.3.2.8 → 10xscale_agentflow_cli-0.3.2.9}/10xscale_agentflow_cli.egg-info/requires.txt

@@ -23,6 +23,12 @@ PyJWT
 [media]
 textxtract[docx,html,md,pdf,xml]>=0.2.0
 
+[otel]
+opentelemetry-api>=1.20.0
+opentelemetry-sdk>=1.20.0
+opentelemetry-instrumentation-fastapi>=0.40b0
+opentelemetry-exporter-otlp>=1.20.0
+
 [redis]
 redis>=5.0.7
 

{10xscale_agentflow_cli-0.3.2.8 → 10xscale_agentflow_cli-0.3.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 10xscale-agentflow-cli
-Version: 0.3.2.8
+Version: 0.3.2.9
 Summary: CLI and API for 10xscale AgentFlow
 Author-email: 10xscale <contact@10xscale.ai>
 Maintainer-email: Shudipto Trafder <shudiptotrafder@gmail.com>
@@ -47,6 +47,11 @@ Provides-Extra: media
 Requires-Dist: textxtract[docx,html,md,pdf,xml]>=0.2.0; extra == "media"
 Provides-Extra: gcloud
 Requires-Dist: google-cloud-logging; extra == "gcloud"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"
 
 # AgentFlow CLI
 

{10xscale_agentflow_cli-0.3.2.8 → 10xscale_agentflow_cli-0.3.2.9}/agentflow_cli/cli/commands/init.py

@@ -152,6 +152,9 @@ class InitCommand(BaseCommand):
             return None
         context["auth"] = auth_choice.lower()
 
+        if context["auth"] == "none":
+            return context
+
         rl_choice = questionary.select(
             "Rate limiting?",
             choices=["None", "Memory Based", "Redis Based"],
@@ -169,7 +172,7 @@ class InitCommand(BaseCommand):
             rl_requests = questionary.text(
                 "Max requests per window?",
                 default="100",
-                validate=lambda v: v.isdigit() and int(v) > 0 or "Enter a positive integer",
+                validate=lambda v: (v.isdigit() and int(v) > 0) or "Enter a positive integer",
             ).ask()
             if rl_requests is None:
                 return None
@@ -178,7 +181,7 @@ class InitCommand(BaseCommand):
             rl_window = questionary.text(
                 "Window size (seconds)?",
                 default="60",
-                validate=lambda v: v.isdigit() and int(v) > 0 or "Enter a positive integer",
+                validate=lambda v: (v.isdigit() and int(v) > 0) or "Enter a positive integer",
             ).ask()
             if rl_window is None:
                 return None

{10xscale_agentflow_cli-0.3.2.8 → 10xscale_agentflow_cli-0.3.2.9}/agentflow_cli/cli/commands/skills.py

@@ -55,6 +55,11 @@ _TARGETS: tuple[_AgentTarget, ...] = (
                 source_relpath="agent-skills",
                 manifest=True,
             ),
+            _InstallArtifact(
+                kind="file",
+                install_relpath=".agents/skills/agentflow/SKILL.md",
+                source_relpath="codex/SKILL.md",
+            ),
         ),
     ),
     _AgentTarget(
@@ -66,6 +71,11 @@ _TARGETS: tuple[_AgentTarget, ...] = (
                 source_relpath="agent-skills",
                 manifest=True,
             ),
+            _InstallArtifact(
+                kind="file",
+                install_relpath=".claude/skills/agentflow/SKILL.md",
+                source_relpath="claude/SKILL.md",
+            ),
         ),
     ),
     _AgentTarget(

10xscale_agentflow_cli-0.3.2.9/agentflow_cli/cli/templates/dev/graph/agent.py

@@ -0,0 +1,63 @@
+import logging
+from datetime import datetime
+
+from agentflow.core.state import AgentState, StreamEmitter
+from agentflow.prebuilt.agent import ReactAgent
+from agentflow.storage.checkpointer import InMemoryCheckpointer
+from dotenv import load_dotenv
+
+
+load_dotenv()
+
+checkpointer = InMemoryCheckpointer()
+
+logger = logging.getLogger(__name__)
+
+
+def call_weather_api(location: str) -> str:
+    return f"The weather in {location} is sunny"
+
+
+def get_weather(
+    location: str,
+    tool_call_id: str | None = None,
+    state: AgentState | None = None,
+    emit: StreamEmitter | None = None,
+) -> str:
+    """Get the current weather for a specific location."""
+    if tool_call_id:
+        logger.info(f"Tool call ID: {tool_call_id}")
+    if state and hasattr(state, "context"):
+        logger.info(f"Number of messages in context: {len(state.context)}")  # type: ignore
+
+    if emit:
+        emit.progress(f"Fetching weather for {location}")
+
+    return call_weather_api(location)
+
+
+react_agent = ReactAgent(
+    model="google/gemini-2.5-flash",
+    provider="google",
+    system_prompt=[
+        {
+            "role": "system",
+            "content": """
+                You are a helpful assistant.
+                Your task is to assist the user in finding information and answering questions.
+                Use tools when they help answer the user.
+            """,
+        },
+        {
+            "role": "user",
+            "content": f"Today Date is {datetime.now().strftime('%Y-%m-%d')}",
+        },  # Inject current date into system prompt
+    ],
+    trim_context=True,
+    tools=[get_weather],
+)
+
+
+app = react_agent.compile(
+    checkpointer=checkpointer,
+)

10xscale_agentflow_cli-0.3.2.9/agentflow_cli/cli/templates/prod/graph/agent.py

@@ -0,0 +1,50 @@
+from datetime import datetime
+
+from agentflow.core.state import MessageContextManager
+from agentflow.prebuilt.agent import ReactAgent
+from agentflow.storage.checkpointer import InMemoryCheckpointer
+from dotenv import load_dotenv
+
+from graph.state import WeatherState
+from graph.tools.weather_tool import get_weather
+from graph.validators.manager import callback_manager
+
+
+load_dotenv()
+
+checkpointer = InMemoryCheckpointer()
+
+context_manager = MessageContextManager(
+    max_messages=20,  # last 20 user messages will be kept in context
+    remove_tool_msgs=True,
+)
+
+react_agent = ReactAgent(
+    state=WeatherState(),
+    model="google/gemini-2.5-flash",
+    provider="google",
+    system_prompt=[
+        {
+            "role": "system",
+            "content": """
+                You are a helpful assistant.
+                Your task is to assist the user in finding information and answering questions.
+                User Current Location: {user_location}
+                If missing information, ask the user for clarification.
+                Use tools when they help answer the user.
+            """,
+        },
+        {
+            "role": "user",
+            "content": f"Today Date is {datetime.now().strftime('%Y-%m-%d')}",
+        },
+    ],
+    trim_context=True,
+    tools=[get_weather],
+    context_manager=context_manager,
+)
+
+app = react_agent.compile(
+    checkpointer=checkpointer,
+    callback_manager=callback_manager,
+)

10xscale_agentflow_cli-0.3.2.9/agentflow_cli/cli/templates/skills/agent-skills/references/agents-and-tools.md

@@ -0,0 +1,323 @@
+# Agents and Tools
+
+Use this when adding model behavior, tools, tool routing, provider options, retries, fallbacks, memory, skills, or structured output to an agent.
+
+---
+
+## Agent
+
+`Agent` is a graph node that calls an LLM provider and appends the response to state. It supports OpenAI, Google GenAI, and any OpenAI-compatible API behind a unified interface.
+
+### Constructor reference
+
+```python
+Agent(
+    model: str,                                          # required
+    output_type: str = "text",                           # "text" | "image" | "video" | "audio"
+    system_prompt: list[dict] | None = None,
+    tool_node: str | ToolNode | None = None,
+    extra_messages: list[Message] | None = None,
+    trim_context: bool = False,
+    tools_tags: set[str] | None = None,
+    reasoning_config: dict | bool | None = {"effort": "medium"},
+    skills: SkillConfig | None = None,
+    memory: MemoryConfig | None = None,
+    retry_config: RetryConfig | bool | None = True,
+    fallback_models: list[str | tuple[str, str]] | None = None,
+    multimodal_config: MultimodalConfig | None = None,
+    output_schema: type[BaseModel] | None = None,
+    # extra kwargs forwarded to provider SDK:
+    provider: str | None = None,       # "openai" | "google"; auto-detected if omitted
+    base_url: str | None = None,
+    api_style: str = "chat",           # "chat" | "responses" (OpenAI only)
+    use_vertex_ai: bool = False,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    # ...any other provider kwargs
+)
+```
+
+### Model and provider
+
+Provider is auto-detected from the model name. Three ways to set it:
+
+```python
+agent = Agent(model="gpt-4o")                     # auto → openai
+agent = Agent(model="gemini-2.5-flash")            # auto → google
+agent = Agent(model="openai/gpt-4o")              # prefix syntax
+agent = Agent(model="gpt-4o", provider="openai")  # explicit kwarg
+```
+
+Third-party OpenAI-compatible APIs use `provider="openai"` + `base_url`:
+
+```python
+# Ollama (local)
+Agent(model="llama3.2", provider="openai", base_url="http://localhost:11434/v1")
+
+# DeepSeek
+Agent(model="deepseek-chat", provider="openai", base_url="https://api.deepseek.com/v1")
+
+# OpenRouter
+Agent(model="anthropic/claude-3-5-sonnet", provider="openai", base_url="https://openrouter.ai/api/v1")
+```
+
+### System prompt
+
+Pass a list of message dicts. `{field_name}` placeholders are replaced at runtime with values from `AgentState`:
+
+```python
+class MyState(AgentState):
+    user_name: str = "Guest"
+    language: str = "English"
+
+agent = Agent(
+    model="gpt-4o",
+    system_prompt=[{"role": "system", "content": "Help {user_name}. Reply in {language}."}],
+)
+```
+
+### Reasoning config
+
+Reasoning is **on by default** at medium effort. Applies to both OpenAI and Google models.
+
+```python
+agent = Agent(model="gpt-4o")                                          # on, medium effort
+agent = Agent(model="gpt-4o", reasoning_config={"effort": "high"})
+agent = Agent(model="gpt-4o", reasoning_config=None)                   # off
+agent = Agent(model="o4-mini", reasoning_config={"effort": "low", "summary": "auto"})  # OpenAI
+agent = Agent(model="gemini-2.5-flash", reasoning_config={"thinking_budget": 5000})    # Google exact
+```
+
+Google effort → thinking_budget mapping:
+
+| `effort` | `thinking_budget` |
+|---|---|
+| `"low"` | 512 |
+| `"medium"` (default) | 8192 |
+| `"high"` | 24576 |
+
+### Retry config
+
+Default: 3 retries, 1 s initial delay, 2x back-off, 30 s cap. Retries on HTTP 429, 500, 502, 503, 529.
+
+```python
+from agentflow.core.graph.agent_internal.constants import RetryConfig
+
+agent = Agent(model="gpt-4o", retry_config=False)   # disable
+
+agent = Agent(
+    model="gpt-4o",
+    retry_config=RetryConfig(max_retries=5, initial_delay=2.0, max_delay=60.0, backoff_factor=2.0),
+)
+```
+
+`RetryConfig` fields: `max_retries` (3), `initial_delay` (1.0 s), `max_delay` (30.0 s), `backoff_factor` (2.0).
+
+### Fallback models
+
+When the primary model exhausts all retries, AgentFlow tries each fallback in order:
+
+```python
+agent = Agent(
+    model="gemini-2.5-flash",
+    provider="google",
+    fallback_models=[
+        "gemini-2.0-flash",                 # inherit provider
+        ("gpt-4o-mini", "openai"),          # explicit (model, provider) tuple
+    ],
+)
+```
+
+### Structured output
+
+`output_schema` with a Pydantic model forces JSON output. Requires `output_type="text"` (default).
+
+```python
+from pydantic import BaseModel
+
+class ReviewAnalysis(BaseModel):
+    sentiment: str
+    score: float
+    summary: str
+
+agent = Agent(model="gpt-4o", output_schema=ReviewAnalysis)
+```
+
+### Extra messages
+
+`extra_messages` are injected into every LLM call after the system prompt and before the context window. Use for few-shot examples or static instructions:
+
+```python
+agent = Agent(
+    model="gpt-4o",
+    extra_messages=[
+        Message.text_message("Q: What is 2+2?", role="user"),
+        Message.text_message("A: 4", role="assistant"),
+    ],
+)
+```
+
+### API style (OpenAI)
+
+```python
+agent = Agent(model="gpt-4o",  api_style="chat")       # default — Chat Completions
+agent = Agent(model="o4-mini", api_style="responses")  # Responses API
+```
+
+---
+
+## ToolNode
+
+`ToolNode` registers and executes callable tools. It supports local Python functions, MCP tools, Composio integrations, and dynamically added tools.
+
+```python
+from agentflow.core.graph import ToolNode
+
+tool_node = ToolNode([get_weather, safe_calculator])
+
+# Add a tool after creation
+tool_node.add_tool(search_db)
+```
+
+### Tool authoring rules
+
+- Docstring → model-facing tool description. Required for useful behavior.
+- Type annotations → parameter schema. Required for correct tool calls.
+- Return a plain value for a normal tool result.
+- Return `ToolResult` to update state fields and return a message to the model.
+- Keep model-visible parameters separate from injected parameters.
+
+### Injectable parameters
+
+These are invisible to the model schema — `ToolNode` injects them automatically:
+
+| Parameter | Type | What is injected |
+|---|---|---|
+| `state` | `AgentState \| None` | Current graph state |
+| `tool_call_id` | `str \| None` | ID of this specific tool call |
+| `config` | `dict` | Execution config (`thread_id`, `user_id`, `run_id`, …) |
+
+```python
+def get_weather(
+    location: str,                         # from model
+    state: AgentState | None = None,       # injected, hidden from schema
+    config: dict | None = None,            # injected, hidden from schema
+) -> str:
+    """Get weather for a location."""
+    user = config.get("user_id", "anon") if config else "anon"
+    return f"Sunny in {location} (user: {user})"
+```
+
+### Returning state updates
+
+Use `ToolResult` when a tool needs to update state fields and return a message:
+
+```python
+from agentflow.core.state.tool_result import ToolResult
+
+class MyState(AgentState):
+    selected_city: str = ""
+
+def select_city(city: str) -> ToolResult:
+    """Set the currently selected city."""
+    return ToolResult(message=f"City set to '{city}'.", state={"selected_city": city})
+```
+
+### Filter tools by tag
+
+`tools_tags` on `Agent` exposes only matching tools to the LLM:
+
+```python
+@tool(tags=["safe"])
+def safe_search(query: str) -> str: ...
+
+@tool(tags=["admin"])
+def admin_action(cmd: str) -> str: ...
+
+tool_node = ToolNode([safe_search, admin_action])
+agent = Agent(model="gpt-4o", tool_node=tool_node, tools_tags={"safe"})
+# admin_action is hidden from this agent's model schema
+```
+
+### MCP tools
+
+```bash
+pip install "10xscale-agentflow[mcp]"
+```
+
+```python
+tool_node = ToolNode(
+    [local_fn],
+    client=mcp_client,               # fastmcp Client
+    pass_user_info_to_mcp=True,      # forward config["user"] to MCP context
+)
+```
+
+---
+
+## The `@tool` decorator
+
+Attaches metadata to any function. Does not change injection behavior — enriches the model schema:
+
+```python
+from agentflow.utils import tool
+
+@tool(
+    name="web_search",
+    description="Search the web for up-to-date information.",
+    tags=["search", "web"],
+    provider="custom",
+    capabilities=["network_access"],
+    metadata={"rate_limit": 100},
+)
+async def search_web(query: str, max_results: int = 5) -> list[str]:
+    """Search the web."""
+    ...
+```
+
+Without arguments: function name and docstring are used as defaults.
+
+---
+
+## ReAct loop
+
+Standard routing pattern. The routing function inspects the last message:
+
+```python
+from agentflow.utils import END
+
+def route(state: AgentState) -> str:
+    if not state.context:
+        return END
+    last = state.context[-1]
+    if hasattr(last, "tools_calls") and last.tools_calls and last.role == "assistant":
+        return "TOOL"
+    if last.role == "tool":
+        return "MAIN"
+    return END
+
+graph.add_conditional_edges("MAIN", route, {"TOOL": "TOOL", END: END})
+graph.add_edge("TOOL", "MAIN")
+```
+
+### Passing tool_node by name
+
+Pass a string to share one `ToolNode` across multiple agents:
+
+```python
+agent = Agent(model="gpt-4o", tool_node="TOOL")
+graph.add_node("MAIN", agent)
+graph.add_node("TOOL", tool_node)
+```
+
+---
+
+## Source map
+
+- Agent: https://github.com/10xHub/Agentflow/blob/main/agentflow/agentflow/core/graph/agent.py
+- ToolNode: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/core/graph
+- ToolResult: https://github.com/10xHub/Agentflow/blob/main/agentflow/agentflow/core/state/tool_result.py
+- RetryConfig: https://github.com/10xHub/Agentflow/blob/main/agentflow/agentflow/core/graph/agent_internal/constants.py
+- `@tool` decorator: https://github.com/10xHub/Agentflow/blob/main/agentflow/agentflow/utils/decorators.py
+- Skills: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/core/skills
+- How-to (configure Agent): https://agentflow.10xscale.ai/how-to/python/configure-agent

10xscale_agentflow_cli-0.3.2.9/agentflow_cli/cli/templates/skills/agent-skills/references/architecture.md

@@ -0,0 +1,90 @@
+# Architecture
+
+Use this when deciding where a change belongs or explaining how Agentflow packages interact. Check https://agentflow.10xscale.ai/ first for public package names.
+
+---
+
+## Published packages
+
+| Public package | Registry | Install | Source |
+|---|---|---|---|
+| `10xscale-agentflow` | PyPI | `pip install 10xscale-agentflow` | `agentflow/agentflow` |
+| `10xscale-agentflow-cli` | PyPI | `pip install 10xscale-agentflow-cli` | `agentflow-api/agentflow_cli` |
+| `@10xscale/agentflow-client` | npm | `npm install @10xscale/agentflow-client` | `agentflow-client/src` |
+
+---
+
+## Layer responsibilities
+
+### `10xscale-agentflow` — core Python library
+
+| Sub-package | Key exports |
+|---|---|
+| `agentflow.core` | `StateGraph`, `Agent`, `ToolNode`, `AgentState`, `Message`, `StreamChunk` |
+| `agentflow.prebuilt.agent` | `ReactAgent`, `PlanActReflectAgent`, `StructuredOutputAgent`, `SupervisorTeamAgent`, `SwarmAgent`, `RAGAgent` |
+| `agentflow.prebuilt.tools` | `fetch_url`, `safe_calculator`, `file_read`, `file_write`, `file_search`, `google_web_search`, `vertex_ai_search`, `memory_tool`, `create_handoff_tool` |
+| `agentflow.storage.checkpointer` | `InMemoryCheckpointer`, `PgCheckpointer` |
+| `agentflow.storage.store` | `QdrantStore`, `Mem0Store` |
+| `agentflow.storage.media` | `InMemoryMediaStore`, `LocalFileMediaStore`, `CloudMediaStore` |
+| `agentflow.runtime` | Publisher adapters (SSE, A2A, Kafka, RabbitMQ, Redis Pub/Sub) |
+| `agentflow.utils` | `ResponseGranularity`, `CallbackManager`, `tool` decorator |
+| `agentflow.qa` | Testing helpers and evaluation tools |
+
+### `10xscale-agentflow-cli` — API and CLI
+
+Owns `agentflow api`, `agentflow play`, `agentflow init`, `agentflow build`, REST routers, auth/middleware, config loading, and graph service execution.
+
+### `@10xscale/agentflow-client` — TypeScript HTTP client
+
+Typed methods for invoke, stream, threads, memory store, file uploads, graph metadata, remote tools, and auth helpers. Calls a running Agentflow API server — does not run Python graphs.
+
+---
+
+## Request flow: invoke
+
+1. `@10xscale/agentflow-client` or another HTTP caller sends messages plus `config.thread_id`.
+2. FastAPI receives the request through auth and routers.
+3. `GraphService` invokes against the compiled graph loaded at startup.
+4. The compiled graph loads state from the checkpointer when `thread_id` exists.
+5. Graph nodes run and update `AgentState`.
+6. Checkpointer saves state, messages, and thread metadata.
+7. API returns JSON to the caller.
+
+## Request flow: stream
+
+Identical through authentication and state loading. The difference: the graph sends `StreamChunk` events incrementally via SSE. Each chunk carries `event` (`"message"`, `"state"`, `"error"`, or `"updates"`), and the response is a `StreamingResponse`.
+
+---
+
+## Key design decisions
+
+| Decision | Rationale |
+|---|---|
+| Graph compiled once at startup | Avoids repeated module loading per request |
+| `thread_id` in every request | Allows stateless servers to restore conversation history |
+| Checkpointer is injected, not hardcoded | Graph code does not depend on the storage backend |
+| Auth is middleware, not in the graph | Business logic stays separate from access control |
+| `injectq` for service wiring | Nodes and tools declare dependencies declaratively; the runtime resolves them |
+
+---
+
+## Design rules
+
+- Compile graphs once at startup for API serving.
+- Keep graph code storage-agnostic; wire checkpointer/store/media/dependencies through compile arguments, `InjectQ`, or `agentflow.json`.
+- Treat `thread_id` as the continuity key for conversation state.
+- Treat long-term memory store records as cross-thread knowledge, not thread history.
+- Keep auth and request permissions in API middleware/routers, not inside graph nodes.
+
+---
+
+## Source map
+
+- Core graph: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/core/graph
+- State/message models: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/core/state
+- Checkpointers: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/storage/checkpointer
+- Memory stores: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/storage/store
+- Media stores: https://github.com/10xHub/Agentflow/tree/main/agentflow/agentflow/storage/media
+- API routers: https://github.com/10xHub/agentflow-cli/tree/main/agentflow_cli/src/app/routers
+- TS client: https://github.com/10xHub/agentflow-client/blob/main/src/client.ts
+- Concepts: https://agentflow.10xscale.ai/concepts/architecture