10xgraph-api 0.7.0__py3-none-any.whl

tenxgraph_api/cli/templates/skills/10xgraph/references/architecture.md

@@ -0,0 +1,91 @@
+# Architecture
+
+Use this when deciding where a change belongs or explaining how 10xGraph packages interact. Check https://10xgraph.com/ first for public package names.
+
+---
+
+## Published packages
+
+| Public package | Registry | Install | Source |
+|---|---|---|---|
+| `10xgraph` | PyPI | `pip install 10xgraph` | `tenxgraph/` in 10xGraph/10xGraph |
+| `10xgraph-api` | PyPI | `pip install 10xgraph-api` | `10xgraph-api/tenxgraph_api` |
+| `@10xscale/agentflow-client` | npm | `npm install @10xscale/agentflow-client` | `agentflow-client/src` |
+
+---
+
+## Layer responsibilities
+
+### `10xgraph` — core Python library
+
+| Sub-package | Key exports |
+|---|---|
+| `tenxgraph.core` | `StateGraph`, `Agent`, `ToolNode`, `AgentState`, `Message`, `StreamChunk` |
+| `tenxgraph.prebuilt.agent` | `ReactAgent`, `PlanActReflectAgent`, `StructuredOutputAgent`, `SupervisorTeamAgent`, `SwarmAgent`, `RAGAgent`, `AudioAgent` (realtime voice) |
+| `tenxgraph.core.realtime` | `LiveInputQueue`, `RealtimeConfig`, `RealtimeEvent` (Gemini Live audio-to-audio) |
+| `tenxgraph.prebuilt.tools` | `fetch_url`, `safe_calculator`, `file_read`, `file_write`, `file_search`, `google_web_search`, `vertex_ai_search`, `memory_tool`, `create_handoff_tool` |
+| `tenxgraph.storage.checkpointer` | `InMemoryCheckpointer`, `PgCheckpointer` |
+| `tenxgraph.storage.store` | `QdrantStore`, `Mem0Store` |
+| `tenxgraph.storage.media` | `InMemoryMediaStore`, `LocalFileMediaStore`, `CloudMediaStore` |
+| `tenxgraph.runtime` | Publisher adapters (SSE, A2A, Kafka, RabbitMQ, Redis Pub/Sub) |
+| `tenxgraph.utils` | `ResponseGranularity`, `CallbackManager`, `tool` decorator |
+| `tenxgraph.qa` | Testing helpers and evaluation tools |
+
+### `10xgraph-api` — API and CLI
+
+Owns `10xgraph api`, `10xgraph play`, `10xgraph init`, `10xgraph 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 10xGraph 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 `10xgraph.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/10xGraph/10xGraph/tree/main/tenxgraph/core/graph
+- State/message models: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/core/state
+- Checkpointers: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/storage/checkpointer
+- Memory stores: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/storage/store
+- Media stores: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/storage/media
+- API routers: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers
+- TS client: https://github.com/10xHub/agentflow-client/blob/main/src/client.ts
+- Concepts: https://10xgraph.com/concepts/architecture

tenxgraph_api/cli/templates/skills/10xgraph/references/auth-and-authorization.md

@@ -0,0 +1,149 @@
+# Auth and Authorization
+
+Use this when changing HTTP authentication, authorization, permission checks, scopes, storage
+isolation, or client auth examples.
+
+Two independent layers:
+
+- Authentication (`BaseAuth`): who is the caller? Produces a `user` dict.
+- Authorization (`AuthorizationBackend`): what may they do, and whose data can they touch?
+
+## Authentication Modes
+
+Default:
+
+- `auth: null`
+- No authentication. Local development / trusted gateways only.
+
+JWT:
+
+- `auth: "jwt"`
+- Requires `JWT_SECRET_KEY` and `JWT_ALGORITHM`. Token must carry `user_id` and `exp`.
+- Requests use `Authorization: Bearer <token>`. Decoded payload becomes the `user` context.
+
+Custom:
+
+```json
+{ "auth": { "method": "custom", "path": "graph.auth:MyAuthBackend" } }
+```
+
+Custom backends subclass `BaseAuth`. `authenticate` is **synchronous** (called without `await`)
+and takes three args:
+
+```python
+def authenticate(self, request, response, credential) -> dict | None: ...
+```
+
+- `request` may be a `Request` or a `WebSocket` (both are `HTTPConnection`) — read
+  `request.headers`, do not assume Request-only APIs.
+- `credential` is the parsed bearer token (`HTTPAuthorizationCredentials | None`). For
+  API-key/cookie schemes, ignore it and read headers directly.
+- Return a dict with at least `user_id` (keys flow into `config["user"]`); `{}`/`None` = anonymous;
+  raise `UserAccountError`/`HTTPException` to reject (401 HTTP, 1008 close on WebSocket).
+- Do NOT declare it `async def` — an un-awaited coroutine breaks auth silently.
+- Include `roles` / `scopes` in the returned dict to feed authorization.
+
+## Authorization
+
+Configured via the `authorization` key; separate from `auth`. Values:
+
+- `null` (unset): mode-based default — `"ownership"` in production, `"allow_all"` in development.
+- `"ownership"`: owner-only. A thread is readable/runnable/deletable only by its creator; a
+  foreign `invoke`/`stream` is rejected up front (403). Enforced on every thread-touching step.
+- `"allow_all"` (aliases `"default"`, `"none"`): any authenticated user may do anything.
+- `"module:attr"`: custom `AuthorizationBackend`.
+- `{ "backend": "rbac", ... }`: role-based access control (below).
+
+Ownership is scalable: ownership is immutable, so it is cached (in-process LRU + optional shared
+Redis when `redis`/`REDIS_URL` is set) via `ThreadOwnershipResolver` over
+`BaseCheckpointer.aget_thread_owner`. After the first lookup a check is an in-memory hit, not a
+per-request DB call; the cache is evicted on thread deletion. Ownership needs a persistent
+checkpointer (pg/sqlite/in-memory); with none, requests pass through.
+
+### Custom backend interface
+
+```python
+class MyAuthz(AuthorizationBackend):
+    async def authorize(
+        self, user: dict, resource: str, action: str,
+        resource_id: str | None = None, **context,
+    ) -> bool: ...                     # required; False -> 403
+
+    def isolation_scope(self) -> str:  # optional; "owner" | "none" (default "none")
+        return "owner"
+
+    def scopes_for(self, user: dict) -> list[str] | None:  # optional; None = permissive
+        return user.get("scopes")
+```
+
+Subclass `OwnershipAuthorizationBackend` to inherit cached owner-only checks and override only
+what you need.
+
+### Scopes
+
+Each endpoint requires the scope `"<resource>:<action>"`. `RequirePermission` checks it against
+`authz.scopes_for(user)`; `None` = permissive (default, nothing breaks until scopes are issued).
+
+- `graph`: `invoke`, `stream`, `stop`, `fix`, `setup`, `read`
+- `checkpointer`: `read`, `write`, `delete`
+- `store`: `read`, `write`, `delete`
+- `files`: `upload`, `read`
+- `config`: `read`
+
+### RBAC config (no code)
+
+```json
+{
+  "authorization": {
+    "backend": "rbac",
+    "roles": { "admin": ["*"], "member": ["graph:invoke", "checkpointer:read"] },
+    "default_scopes": ["graph:read"],
+    "isolation": "owner"
+  }
+}
+```
+
+Maps `user["roles"]` to scopes on top of owner isolation. `"*"` -> all scopes. `default_scopes`
+granted to everyone. `isolation`: `"owner"` | `"none"`.
+
+### Data isolation (config["authz"])
+
+API checks decide access; the storage layer (checkpointer, store) enforces isolation from a
+trusted policy. After a successful check, `RequirePermission` stamps
+`user["authz"] = {user_id, scope, scopes}` where `scope` = backend `isolation_scope()`. Services
+copy the trusted `user` into `config["user"]`, so the core library reads `config["user"]["authz"]`
+and scopes rows to the caller (`owner`) or not (`none`). Set server-side only — not client-forgeable.
+
+## Guarantees
+
+- Routes are guarded by construction: `assert_all_routes_protected` refuses to boot if any
+  non-public route lacks `RequirePermission`. Public: `/ping` and dev-only eval endpoints.
+- Return 401 for auth failure, 403 for authorization/scope failure.
+
+## TypeScript Client
+
+```typescript
+const client = new AgentFlowClient({
+  baseUrl: "http://127.0.0.1:8000",
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+## Rules
+
+- No unauthenticated API mode in production unless a trusted gateway handles auth.
+- Keep `authenticate` synchronous; keep authorization out of graph business logic.
+- Sanitize logging for tokens and user payloads.
+- Update the scope catalog and permission tables when adding routes.
+
+## Source Map
+
+- Base auth: tenxgraph_api/src/app/core/auth/base_auth.py
+- JWT auth: tenxgraph_api/src/app/core/auth/jwt_auth.py
+- Auth loader/dependency: tenxgraph_api/src/app/core/auth/auth_backend.py
+- Authorization backends (ownership, RBAC): tenxgraph_api/src/app/core/auth/authorization.py
+- Permission dependency + scope check + authz stamp: tenxgraph_api/src/app/core/auth/permissions.py
+- Ownership cache: tenxgraph_api/src/app/core/auth/ownership_resolver.py
+- Boot-time route guard: tenxgraph_api/src/app/core/auth/route_guard.py
+- Scope catalog + authz contract: tenxgraph/core/authz.py
+- Docs: https://10xgraph.com/

tenxgraph_api/cli/templates/skills/10xgraph/references/callbacks-and-command.md

@@ -0,0 +1,283 @@
+# Callbacks and Command
+
+Use this when adding validation, tracing, invocation hooks, error recovery, or runtime graph jumps.
+
+## CallbackManager
+
+`CallbackManager` registers hooks around AI, tool, MCP, input validation, and skill invocations.
+
+Invocation types:
+
+- `InvocationType.AI`
+- `InvocationType.TOOL`
+- `InvocationType.MCP`
+- `InvocationType.INPUT_VALIDATION`
+- `InvocationType.SKILL`
+
+Hook families:
+
+- `register_before_invoke(invocation_type, callback)`: validate or transform input before invocation.
+- `register_after_invoke(invocation_type, callback)`: inspect or transform output after invocation.
+- `register_on_error(invocation_type, callback)`: log, recover, or return a recovery `Message`.
+- `register_input_validator(validator)`: add a `BaseValidator` that validates incoming messages.
+
+Callbacks can be callable objects or functions and may be sync or async. Error callbacks should return a `Message` recovery value or `None`.
+
+## Validators
+
+Use `BaseValidator` for input validation. Implement:
+
+```python
+async def validate(self, messages: list[Message]) -> bool:
+    ...
+```
+
+Register validators on a `CallbackManager`, then pass it to graph compilation:
+
+```python
+callback_manager = CallbackManager()
+callback_manager.register_input_validator(MyValidator())
+
+app = graph.compile(callback_manager=callback_manager)
+```
+
+Use validators for safety checks, business rules, input policy, and prompt-injection detection.
+
+## Graph Lifecycle Hooks
+
+Graph lifecycle hooks fire at **graph orchestration level** — before/after the entire graph run, on checkpoints, on interrupts, on resume, and after each node transition. They complement the invocation-level hooks above (`before_invoke` / `after_invoke` / `on_error`), which fire inside a single node's AI/Tool/MCP call.
+
+### GraphLifecycleContext
+
+All 7 hooks receive this as their first argument. It provides run-identifying metadata.
+
+```python
+@dataclass
+class GraphLifecycleContext:
+    config: dict[str, Any]       # full config dict passed to invoke/stream
+    timestamp: str               # ISO8601 start time from config["timestamp"]
+    metadata: dict[str, Any] | None = None  # open-ended extra context
+
+    @property
+    def thread_id(self) -> str | None: ...
+
+    @property
+    def run_id(self) -> str | None: ...
+```
+
+### GraphLifecycleHook
+
+Subclass `GraphLifecycleHook` and override only the methods you need. All methods are async and default to no-ops.
+
+```python
+from tenxgraph.utils.callbacks import GraphLifecycleHook, GraphLifecycleContext, CallbackManager
+from tenxgraph.core.state import AgentState
+from tenxgraph.core.state.message import Message
+
+class GraphLifecycleHook(ABC):
+    async def on_graph_start(
+        self, context: GraphLifecycleContext, state: AgentState
+    ) -> AgentState | None: ...
+    # Fires: after state is loaded, before the first node executes.
+    # Return modified AgentState to replace the initial state, or None.
+
+    async def on_graph_end(
+        self, context: GraphLifecycleContext, final_state: AgentState,
+        messages: list[Message], total_steps: int
+    ) -> AgentState | None: ...
+    # Fires: after execution loop completes, before final persistence.
+    # Return modified AgentState or None.
+
+    async def on_graph_error(
+        self, context: GraphLifecycleContext, error: Exception,
+        partial_state: AgentState, messages: list[Message], step: int, node_name: str
+    ) -> tuple[AgentState, str] | None: ...
+    # Fires: when an unhandled exception escapes the graph loop.
+    # Return (AgentState, error_message) to change persisted error snapshot, or None.
+    # Cannot suppress the error — always re-raised after this hook.
+
+    async def on_interrupt(
+        self, context: GraphLifecycleContext, interrupted_node: str,
+        interrupt_type: str,   # "before" | "after" | "stop" | "remote_tool"
+        state: AgentState
+    ) -> AgentState | None: ...
+    # Fires: before interrupt state is persisted (covers before/after/stop/remote_tool types).
+    # Return modified AgentState or None.
+
+    async def on_resume(
+        self, context: GraphLifecycleContext, resumed_node: str,
+        state: AgentState, resume_data: dict[str, Any]
+    ) -> AgentState | None: ...
+    # Fires: when a paused graph is resumed, before clear_interrupt().
+    # resume_data is mutable in-place. Return modified AgentState or None.
+
+    async def on_checkpoint(
+        self, context: GraphLifecycleContext, state: AgentState,
+        messages: list[Message], is_context_trimmed: bool
+    ) -> tuple[AgentState, list[Message]] | AgentState | None: ...
+    # Fires: immediately before state/messages are persisted (every checkpoint, not just final).
+    # Return (AgentState, messages), AgentState, or None.
+
+    async def on_state_update(
+        self, context: GraphLifecycleContext, node_name: str,
+        old_state: AgentState, new_state: AgentState, step: int
+    ) -> AgentState | None: ...
+    # Fires: after each node produces a result and state is merged.
+    # Return modified AgentState or None.
+```
+
+### Registration
+
+```python
+callback_mgr = CallbackManager()
+callback_mgr.register_lifecycle_hook(MyHook())
+
+# Combine with existing invocation-level hooks on the same manager:
+callback_mgr.register_after_invoke(InvocationType.AI, my_ai_callback)
+
+app = graph.compile(callback_manager=callback_mgr)
+```
+
+### Hook Summary
+
+| Hook | Returns | Fires N times | Fire location |
+|---|---|---|---|
+| `on_graph_start` | `AgentState \| None` | 1 per run | After state load, before loop |
+| `on_graph_end` | `AgentState \| None` | 1 per successful run | After `state.complete()`, before final `sync_data()` |
+| `on_graph_error` | `tuple[AgentState, str] \| None` | 1 per failed run | In except block, before error `sync_data()` |
+| `on_interrupt` | `AgentState \| None` | 0–N per run | Before interrupt checkpoint persistence |
+| `on_resume` | `AgentState \| None` | 0–1 per call | Before `clear_interrupt()` |
+| `on_checkpoint` | `(AgentState, list[Message]) \| AgentState \| None` | 1–N per run | Before every durable checkpoint write |
+| `on_state_update` | `AgentState \| None` | N per run (once per node) | After each node result is merged |
+| `on_turn_start` | `AgentState \| None` | N (realtime only) | Start of each model turn |
+| `on_turn_end` | `AgentState \| None` | N (realtime only) | End of each model turn |
+
+### Realtime hooks
+
+The same `GraphLifecycleHook` fires for realtime (audio) graphs, with two methods that fire **only**
+in realtime (no-ops for `invoke` / `stream`):
+
+- `on_graph_start(ctx, state)` / `on_graph_end(ctx, final_state, messages, total_steps)` — once per
+  session (the `LIVE` node *is* the graph); `total_steps` = number of turns.
+- `on_turn_start(ctx, state, turn_index)` / `on_turn_end(ctx, state, turn_index)` — per model turn
+  (1-based; a turn spans one model generation, bounded by `turn_complete` or a barge-in). A turn cut
+  off by session end still gets a balanced `on_turn_end`.
+
+Realtime has no `AI`-invocation callback or input-validator pass (no discrete LLM call); the per-turn
+hooks are the observability stand-in. Tool/MCP `before/after/error` callbacks fire as usual. See
+`realtime.md`.
+
+### Example
+
+```python
+class ObservabilityHook(GraphLifecycleHook):
+    async def on_graph_start(self, ctx, state):
+        self._span = tracer.start_span(f"graph.run.{ctx.thread_id}")
+        return None
+
+    async def on_graph_end(self, ctx, final_state, messages, total_steps):
+        self._span.set_attribute("steps", total_steps)
+        self._span.end()
+
+    async def on_graph_error(self, ctx, error, partial_state, messages, step, node_name):
+        self._span.record_exception(error)
+        self._span.end()
+        alert_oncall(f"Graph failed at node {node_name}: {error}")
+        return None
+
+    async def on_interrupt(self, ctx, interrupted_node, interrupt_type, state):
+        notify_frontend(ctx.thread_id, status="waiting_for_input", node=interrupted_node)
+        return None
+
+    async def on_resume(self, ctx, resumed_node, state, resume_data):
+        notify_frontend(ctx.thread_id, status="resuming", node=resumed_node)
+        return None
+
+    async def on_checkpoint(self, ctx, state, messages, is_context_trimmed):
+        metrics.increment("tenxgraph.checkpoints", tags={"thread": ctx.thread_id})
+        return None
+
+    async def on_state_update(self, ctx, node_name, old_state, new_state, step):
+        diff = compute_diff(old_state, new_state)
+        stream_diff_to_frontend(ctx.thread_id, diff)
+        return None
+
+
+callback_mgr = CallbackManager()
+callback_mgr.register_lifecycle_hook(ObservabilityHook())
+app = graph.compile(callback_manager=callback_mgr)
+```
+
+### Common Use Cases by Hook
+
+- **`on_graph_start`**: inject trace IDs, pre-populate state from external DB, set rate-limit budgets, initialize OpenTelemetry spans.
+- **`on_graph_end`**: send completion notifications (Slack/email), record step/message count metrics, archive transcripts, trigger downstream webhooks.
+- **`on_graph_error`**: alert PagerDuty/Sentry, log structured failure diagnostics, close OTel spans with error status.
+- **`on_interrupt`**: push "waiting for approval" notifications to frontend/mobile, start timeout timers, update task queue status.
+- **`on_resume`**: cancel timeout timers, validate resume payload, record interrupt→resume cycle for audit trail.
+- **`on_checkpoint`**: redact sensitive data before persistence, replicate to secondary store, invalidate caches, compliance audit logging (SOC2/HIPAA).
+- **`on_state_update`**: real-time state diffing for frontend streaming, per-node invariant assertions, security scanning of state content.
+
+---
+
+## Command
+
+`Command` lets a node combine state/message updates with control flow. Use it when the next node depends on runtime logic inside the node and is awkward to express as a static conditional edge.
+
+Fields:
+
+- `update`: state update, `Message`, string, converter, or `None`.
+- `goto`: next node name or `END`.
+- `graph`: optional graph target; `Command.PARENT` is reserved for parent graph navigation patterns.
+- `state`: optional attached state.
+
+Prefer conditional edges for normal routing because they are easier to visualize and test. Use `Command(goto=...)` for dynamic jumps, recovery branches, handoffs, or side-effect-dependent routing.
+
+## Patterns
+
+Callback for tracing:
+
+```python
+from tenxgraph.utils.callbacks import CallbackContext, CallbackManager, InvocationType
+
+async def trace_after(context: CallbackContext, input_data, output_data):
+    print(context.invocation_type, context.node_name)
+    return output_data
+
+callback_manager = CallbackManager()
+callback_manager.register_after_invoke(InvocationType.TOOL, trace_after)
+app = graph.compile(callback_manager=callback_manager)
+```
+
+Command for dynamic routing:
+
+```python
+from tenxgraph.utils import Command, END
+
+def router_node(state, config):
+    if state.context[-1].text() == "stop":
+        return Command(goto=END)
+    return Command(update={"route": "repair"}, goto="REPAIR")
+```
+
+## Rules
+
+- Keep callback side effects bounded; they run inside graph execution paths.
+- Avoid storing per-request mutable state globally inside callbacks.
+- Use `CallbackContext` metadata to distinguish node/function/invocation details.
+- Return transformed data from callbacks only when the downstream invocation expects that shape.
+- Use `Command` sparingly; static and conditional edges remain the default graph structure.
+- Always test command routes for recursion limits and missing destination nodes.
+
+## Source Map
+
+- Callback system (invocation hooks + graph lifecycle hooks): https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/callbacks.py
+- Default validators: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/validators.py
+- Graph compile callback argument: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/state_graph.py
+- Command API: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/command.py
+- Command execution paths: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/compiled_graph.py
+- Lifecycle hook fire points — invoke path: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/utils/invoke_handler.py
+- Lifecycle hook fire points — stream path: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/utils/stream_handler.py
+- Lifecycle hook fire points — interrupt/resume: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/utils/heandler_utils.py
+- Lifecycle hook fire points — checkpoint: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/utils/utils.py
+- Legacy docs: https://github.com/10xHub/Agentflow/blob/main/agentflow-docs/docs-mkdocs-legacy/reference/library/Command.md

tenxgraph_api/cli/templates/skills/10xgraph/references/checkpointing-and-threads.md

@@ -0,0 +1,63 @@
+# Checkpointing and Threads
+
+Use this when adding persistence, thread APIs, message history, interrupts, or multi-worker behavior.
+
+## Concept
+
+A checkpointer persists per-thread `AgentState`, messages, and thread metadata. Without a checkpointer, each `invoke` starts from a fresh state. With a checkpointer, calls with the same `config.thread_id` resume the saved state.
+
+## Config
+
+At minimum, checkpointed calls need:
+
+```python
+config = {"thread_id": "conv-1"}
+```
+
+Use `user_id` for multi-tenant scoping where the backend supports it.
+
+## Backends
+
+- `InMemoryCheckpointer`: development/tests/single-process only. State is lost on restart and not shared across workers.
+- `PgCheckpointer`: production backend using PostgreSQL for durable data and Redis for fast cache. Requires setup before use.
+
+Use production storage for load-balanced API deployments.
+
+## API Surface
+
+Checkpointer methods exist in async and sync forms:
+
+- State: put/get/clear state and state cache.
+- Messages: append/list/get/delete thread messages.
+- Threads: create/get/list/clean thread metadata and content.
+- Generic cache: namespaced key-value cache with optional TTL.
+
+## REST and Client
+
+The API exposes thread state/message/thread operations under `/v1/threads...` routes in the checkpointer router. The TypeScript client wraps these with methods such as:
+
+- `threadState`
+- `updateThreadState`
+- `clearThreadState`
+- `threadDetails`
+- `threads`
+- `threadMessages`
+- `addThreadMessages`
+- `singleMessage`
+- `deleteMessage`
+- `deleteThread`
+
+## Rules
+
+- Always preserve `thread_id` across a conversation.
+- Use `PgCheckpointer` or equivalent durable storage for multi-worker production.
+- Store conversation continuity in the checkpointer, not the memory store.
+- Use `aclean_thread`/delete APIs when removing a thread so state, messages, and metadata stay consistent.
+
+## Source Map
+
+- Base API: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/storage/checkpointer/base_checkpointer.py
+- In-memory backend: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/storage/checkpointer/in_memory_checkpointer.py
+- Postgres backend: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/storage/checkpointer/pg_checkpointer.py
+- API router: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/checkpointer
+- TS endpoints: https://github.com/10xHub/agentflow-client/tree/main/src/endpoints

tenxgraph_api/cli/templates/skills/10xgraph/references/cli-commands.md

@@ -0,0 +1,73 @@
+# CLI Commands
+
+Use this when changing `10xgraph-api` command behavior, generated files, or deployment scaffolding.
+
+## Package
+
+Install:
+
+```bash
+pip install 10xgraph-api
+```
+
+Entry point:
+
+```text
+10xgraph = tenxgraph_api.cli.main:main
+agentflow = tenxgraph_api.cli.main:legacy_main   # deprecated alias, removed in 2.0
+```
+
+## Commands
+
+`10xgraph init`
+
+- Scaffolds `10xgraph.json`, `graph/__init__.py`, and `graph/react.py`, and suggests `10xgraph skills` as a next step.
+- Options include `--path/-p`, `--force/-f`, `--prod`, `--verbose/-v`, and `--quiet/-q`.
+- `--prod` also adds production project files such as `pyproject.toml` and `.pre-commit-config.yaml`.
+
+`10xgraph api`
+
+- Starts the FastAPI server for a compiled graph.
+- Options include `--config/-c`, `--host/-H`, `--port/-p`, `--reload/--no-reload`, `--verbose/-v`, and `--quiet/-q`.
+- Defaults are config `10xgraph.json`, host `127.0.0.1`, port `8000`, reload enabled.
+
+`10xgraph play`
+
+- Starts the API server and opens/prints the hosted playground URL.
+- Accepts the same server options as `api`.
+- Uses host/port to build the playground backend URL.
+
+`10xgraph build`
+
+- Generates Docker deployment files.
+- Options include `--output/-o`, `--force/-f`, `--python-version`, `--port/-p`, `--docker-compose/--no-docker-compose`, `--service-name`, `--verbose/-v`, and `--quiet/-q`.
+
+`10xgraph skills`
+
+- Installs the bundled 10xGraph skill (an Agent Skills spec folder: `SKILL.md` + `references/`) into an agent-specific project directory. Every agent gets the same folder; paths inside it are relative to the skill directory.
+- Prompts for the target agent when `--agent` is omitted:
+  - `1` / `codex`: `.agents/skills/10xgraph`
+  - `2` / `claude`: `.claude/skills/10xgraph`
+  - `3` / `github`: `.github/instructions/10xgraph.instructions.md` and `.github/skills/10xgraph`
+- Options include `--agent/-a`, `--path/-p`, `--force/-f`, `--all`, `--list/-l`, `--verbose/-v`, and `--quiet/-q`.
+- `--validate PATH` (repeatable) checks a skill directory, or a folder of skill directories, against the Agent Skills specification (https://agentskills.io/specification) and exits non-zero on errors. Nothing is installed.
+- Source templates: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/cli/templates/skills
+
+`10xgraph version`
+
+- Prints CLI and library version information.
+
+## Rules
+
+- Use docs package names in user-facing text.
+- Keep command options aligned with https://10xgraph.com/
+- If command defaults change, update docs, templates, and tests together.
+- Generated skill templates live under https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/cli/templates/skills
+
+## Source Map
+
+- CLI main: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/cli/main.py
+- Commands: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/cli/commands
+- CLI config/output/validation: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/cli/core
+- Templates: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/cli/templates
+- Docs: https://10xgraph.com/