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

tenxgraph_api/cli/templates/skills/10xgraph/references/state-graph.md

@@ -0,0 +1,232 @@
+# StateGraph and Nodes
+
+Use this when adding workflows, nodes, edges, interrupts, graph compilation, or execution behavior.
+
+---
+
+## Core model
+
+`StateGraph` is the workflow engine. A graph describes a directed set of nodes and edges executed over an `AgentState` subclass. The compiled graph manages state loading, routing, checkpointing, streaming, interrupts, recursion limits, and shutdown automatically.
+
+---
+
+## Creating a StateGraph
+
+### Minimal
+
+```python
+from tenxgraph.core.graph import StateGraph
+
+graph = StateGraph()   # defaults to AgentState
+```
+
+### Custom state class
+
+```python
+from tenxgraph.core.state import AgentState
+
+class OrderState(AgentState):
+    order_id: str = ""
+    total: float = 0.0
+
+graph = StateGraph(OrderState)   # pass class or instance — both work
+```
+
+### Full constructor
+
+```python
+StateGraph(
+    state: StateT | None = None,
+    context_manager: BaseContextManager | None = None,
+    publisher: BasePublisher | None = None,
+    id_generator: BaseIDGenerator = DefaultIDGenerator(),
+    container: InjectQ | None = None,
+)
+```
+
+| Parameter | Description |
+|---|---|
+| `state` | State class or instance. Defaults to `AgentState()` |
+| `context_manager` | Optional cross-node state transformer (trim context, summarise, etc.) |
+| `publisher` | Optional publisher for emitting lifecycle events (Kafka, Redis Pub/Sub, RabbitMQ) |
+| `id_generator` | Strategy for generating message and run IDs |
+| `container` | `InjectQ` container for DI. Defaults to the global singleton |
+
+---
+
+## Adding nodes
+
+A node is any callable that receives `AgentState` (or subclass) and returns a `Message`, `ToolResult`, or state `dict`.
+
+```python
+graph.add_node("MAIN", agent)          # explicit name
+graph.add_node("TOOL", tool_node)
+graph.add_node(process)                # auto-name: "process"
+graph.override_node("MAIN", mock)      # replace existing node — useful in tests
+```
+
+---
+
+## Edges
+
+```python
+graph.add_edge("TOOL", "MAIN")             # static: always TOOL → MAIN
+graph.set_entry_point("MAIN")              # shorthand for add_edge(START, "MAIN")
+```
+
+### Conditional edges
+
+The routing function receives `AgentState` and returns a string key. `path_map` maps that key to a node name:
+
+```python
+from tenxgraph.utils.constants import END
+
+def route(state: AgentState) -> str:
+    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})
+# If path_map is omitted, the function must return the destination node name directly.
+```
+
+Use `Command(goto=...)` for runtime jumps only when static or conditional edges are insufficient. See `callbacks-and-command.md`.
+
+---
+
+## Compiling
+
+```python
+from tenxgraph.utils import CallbackManager
+
+app = graph.compile(
+    checkpointer=checkpointer,       # BaseCheckpointer | None
+    store=store,                     # BaseStore | None
+    media_store=media_store,         # BaseMediaStore | None
+    interrupt_before=["VALIDATOR"],  # pause before these node names
+    interrupt_after=["TOOL"],        # pause after these node names
+    callback_manager=CallbackManager(),
+    shutdown_timeout=30.0,
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `checkpointer` | `BaseCheckpointer \| None` | State persistence. Defaults to `InMemoryCheckpointer` if not provided |
+| `store` | `BaseStore \| None` | Long-term cross-thread memory store |
+| `media_store` | `BaseMediaStore \| None` | Media file storage for multimodal content |
+| `interrupt_before` | `list[str] \| None` | Pause before these node names |
+| `interrupt_after` | `list[str] \| None` | Pause after these node names |
+| `callback_manager` | `CallbackManager` | Hooks for observability and lifecycle events |
+| `shutdown_timeout` | `float` | Seconds to wait for graceful shutdown (default `30.0`) |
+
+`compile()` raises `GraphError` if no entry point is set or if interrupt nodes do not exist.
+
+---
+
+## Invoking
+
+```python
+from tenxgraph.core.state import Message
+from tenxgraph.utils import ResponseGranularity
+
+result = app.invoke(
+    {"messages": [Message.text_message("Hello!")]},
+    config={"thread_id": "t1", "recursion_limit": 25},
+    response_granularity=ResponseGranularity.LOW,
+)
+messages = result["messages"]
+```
+
+`ainvoke()` is the async equivalent. Returns the full state dict.
+
+### Lifecycle / async context manager
+
+`CompiledGraph` supports `async with`; `aclose()` runs on exit even if the body raises, and is
+idempotent (a second call returns `{"status": "already_closed"}`).
+
+```python
+async with await build_and_compile_graph() as graph:
+    await graph.ainvoke(input_data)
+# aclose() runs automatically here
+```
+
+---
+
+## Streaming
+
+```python
+from tenxgraph.core.state.stream_chunks import StreamEvent
+
+for chunk in app.stream(
+    {"messages": [Message.text_message("Hello!")]},
+    config={"thread_id": "t2"},
+):
+    if chunk.event == StreamEvent.MESSAGE and chunk.message:
+        print(chunk.message.text())
+```
+
+`astream()` is the async equivalent. See `streaming.md` for full details on `StreamChunk` fields and `StreamEvent` values.
+
+### Realtime (audio) graphs
+
+A graph rooted at a `LiveAgent` is driven by `arealtime(input_queue, config=None, state=None)` (async
+generator of `RealtimeEvent`s) or the sync `realtime(...)` wrapper, not `invoke` / `stream`. The
+forcing rule is mutual: a graph with a `LiveAgent` must use `arealtime()` (`invoke` / `stream`
+raise), and `arealtime()` requires exactly one `LiveAgent` (ordinary graphs raise). See
+`realtime.md`.
+
+---
+
+## Config keys
+
+Passed in the `config` dict to `invoke` / `stream`:
+
+| Key | Type | Description |
+|---|---|---|
+| `thread_id` | `str` | Conversation thread identifier. Required for checkpointing |
+| `user_id` | `str` | Optional user identifier; injected into tool `config` param |
+| `run_id` | `str` | Optional run identifier; auto-generated if omitted |
+| `recursion_limit` | `int` | Max node executions before stopping (default `25`) |
+
+---
+
+## Interrupts
+
+Compile with `interrupt_before` or `interrupt_after`. When execution reaches an interrupt node, the graph pauses and persists state. Resume by calling `invoke` again with the same `thread_id` and an empty input:
+
+```python
+app = graph.compile(checkpointer=checkpointer, interrupt_before=["VALIDATOR"])
+
+# First call — pauses before VALIDATOR
+app.invoke({"messages": [Message.text_message("Start")]}, config={"thread_id": "t3"})
+
+# Resume after review
+app.invoke({}, config={"thread_id": "t3"})
+```
+
+---
+
+## Execution lifecycle
+
+```
+app.invoke → Load or create AgentState (from checkpointer if thread_id exists)
+           → Run entry node
+           → Evaluate conditional or static edge
+           → Run next node
+           → Check for interrupt → pause and save state (if configured)
+           → Repeat until END
+           → Save final state → Return result dict
+```
+
+---
+
+## Source map
+
+- StateGraph: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/state_graph.py
+- CompiledGraph: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/compiled_graph.py
+- Constants (END, START): https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/constants.py
+- How-to (build a graph): https://10xgraph.com/how-to/python/build-a-graph

tenxgraph_api/cli/templates/skills/10xgraph/references/stream-emitter.md

@@ -0,0 +1,144 @@
+# StreamEmitter
+
+Emit live progress, errors, and status updates from tools during streaming execution.
+
+## Overview
+
+`StreamEmitter` allows tools to send **live progress updates** back to the caller during `app.stream(...)` / `app.astream(...)` execution. Tools can report intermediate steps, retries, and errors in real-time without using an external publisher.
+
+## Key Points
+
+- **Streaming only**: Automatically injected during `app.stream()` / `app.astream()`, not during `invoke()` / `ainvoke()`
+- **Optional parameter**: Declare as `emit: StreamEmitter | None = None` in tool functions
+- **Thread-safe**: Works with both sync and async tools
+- **Built-in**: Uses the same streaming pipeline; no external publisher required
+
+## Common Methods
+
+### `progress(message: str, data: dict | None = None)`
+
+Emit a progress update showing intermediate steps or status changes.
+
+```python
+if emit:
+    emit.progress("Fetching data...", data={"attempt": 1, "max_attempts": 3})
+```
+
+### `error(message: str, data: dict | None = None)`
+
+Emit an error update (informational; doesn't interrupt execution).
+
+```python
+if emit:
+    emit.error("API timeout, using cache", data={"retry_count": 3})
+```
+
+### `message(message: str, data: dict | None = None)`
+
+Emit a plain informational message.
+
+```python
+if emit:
+    emit.message("Processing complete", data={"items_processed": 1000})
+```
+
+### `update(data: dict)`
+
+Emit a generic data update without a message.
+
+```python
+if emit:
+    emit.update({
+        "status": "batch_progress",
+        "processed": 50,
+        "total": 100,
+        "percentage": 50.0,
+    })
+```
+
+## Usage Pattern
+
+```python
+from tenxgraph.core.state.stream_emitter import StreamEmitter
+
+def my_tool(
+    param: str,
+    emit: StreamEmitter | None = None,
+) -> str:
+    """Tool that reports progress during streaming."""
+    if emit:
+        emit.progress("Starting work...")
+
+    # ... do work ...
+
+    if emit:
+        emit.progress("Finalizing...", data={"step": 2})
+
+    return "result"
+```
+
+## When to Use
+
+✅ **Use for:**
+- Long-running operations (API calls, file processing)
+- Retries with multiple attempts
+- Multi-step processes
+- Batch processing with progress tracking
+
+❌ **Don't use for:**
+- Fast operations (<100ms)
+- Non-streaming paths (emit will be None anyway)
+- Critical control flow (always return a result regardless)
+
+## Behavior
+
+| Execution Mode | Emit Parameter | Output |
+|---|---|---|
+| `app.stream()` | `StreamEmitter` | Progress updates in stream |
+| `app.astream()` | `StreamEmitter` | Progress updates in stream |
+| `app.invoke()` | `None` | No progress updates |
+| `app.ainvoke()` | `None` | No progress updates |
+
+## Stream Output
+
+Emitted chunks appear in the stream output with structure:
+
+```python
+{
+    "event": "message" | "error" | "update",
+    "data": {
+        "status": "tool_progress" | "tool_failed" | "tool_message" | ...,
+        "tool_name": "my_tool",
+        "tool_call_id": "call_abc123",
+        "node": "TOOL",
+        "message": "...",
+        "thread_id": "...",
+        "run_id": "...",
+        # ... plus any extra data passed
+    },
+}
+```
+
+## Performance Tips
+
+- Emit at meaningful intervals, not every iteration
+- For batch work: emit every N items, not on every item
+- Avoid thousands of updates per second
+
+```python
+# ❌ Too frequent
+for item in items:
+    if emit:
+        emit.progress(f"Processing {item}")
+
+# ✅ Batched
+for i, item in enumerate(items):
+    if (i + 1) % 100 == 0 and emit:
+        emit.progress(f"Processed {i + 1} of {len(items)}")
+```
+
+## See Also
+
+- [Tools](agents-and-tools.md) — Defining and registering tools
+- [Streaming](streaming.md) — Overview of streaming chunks
+- [Dependency Injection](dependency-injection.md) — How parameters like `emit` are injected

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

@@ -0,0 +1,53 @@
+# Streaming
+
+Use this when working on incremental output, SSE, cancellation, response granularity, or TypeScript async iteration.
+
+## Modes
+
+- `invoke`: run to completion and return a final result dict.
+- `ainvoke`: async invoke.
+- `stream`: sync generator yielding `StreamChunk`.
+- `astream`: async generator yielding `StreamChunk`.
+
+Use streaming for chat UIs and any caller that needs partial output.
+
+## StreamChunk
+
+Important fields:
+
+- `event`: `"message"`, `"state"`, `"error"`, or `"updates"`.
+- `message`: populated for message events.
+- `state`: populated for state events.
+- `data`: populated for errors/updates.
+- `thread_id`, `run_id`, `metadata`, `timestamp`.
+
+## ResponseGranularity
+
+- `LOW`: latest messages only; good default for UI streaming.
+- `PARTIAL`: context, summary, and latest messages.
+- `FULL`: complete state and messages.
+
+Use lower granularity for client performance and privacy unless full state is needed.
+
+## Stop
+
+Use `app.stop()` / `app.astop()` or `POST /v1/graph/stop` to request cancellation for a thread. The graph exits cleanly after node boundaries.
+
+## REST and Client
+
+REST:
+
+- `POST /v1/graph/stream` returns server-sent events.
+- Each SSE data payload is a serialized `StreamChunk`.
+
+TypeScript:
+
+- `AgentFlowClient.stream(messages, options)` returns an async generator.
+- Handle `chunk.event === "message"` for incremental text.
+
+## Source Map
+
+- Stream chunks: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/stream_chunks.py
+- Compiled graph streaming: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/compiled_graph.py
+- Graph API router/service: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/graph
+- TS stream endpoint: https://github.com/10xHub/agentflow-client/blob/main/src/endpoints/stream.ts

tenxgraph_api/cli/templates/skills/10xgraph/references/testing-and-evaluation.md

@@ -0,0 +1,64 @@
+# Testing and Evaluation
+
+Use this when writing tests, mocks, eval datasets, automated quality checks, or trajectory assertions.
+
+## Testing Helpers
+
+Import from `tenxgraph.qa.testing` or `tenxgraph.qa`.
+
+Key helpers:
+
+- `TestAgent`: model-free agent double that returns predefined responses and can simulate tool calls.
+- `QuickTest`: quick single-turn, multi-turn, tool, and custom graph tests.
+- `TestResult`: fluent assertions for output text, tool calls, message counts, and errors.
+- `TestContext`: context manager for creating graphs, agents, stores, and mocks.
+- `MockToolRegistry`: register sync/async mock tools and assert calls.
+- `MockMCPClient`: mock MCP tool listing/calls.
+- `MockComposioAdapter` and `MockLangChainAdapter`: test third-party tool adapter behavior.
+- `InMemoryStore`: deterministic memory store for tests.
+
+Use these instead of real model/provider calls in unit tests.
+
+## Evaluation Framework
+
+Import from `tenxgraph.qa.evaluation` or `tenxgraph.qa`.
+
+Core dataset/results types:
+
+- `EvalCase`, `EvalSet`, `EvalSetBuilder`
+- `ToolCall`, `Invocation`, `TrajectoryStep`, `StepType`
+- `EvalConfig`, `CriterionConfig`, `MatchType`, `Rubric`
+- `EvalReport`, `EvalCaseResult`, `CriterionResult`
+
+Runner and shortcuts:
+
+- `AgentEvaluator`
+- `QuickEval`
+- `run_eval`
+- `create_eval_app`
+- `create_simple_eval_set`
+- `eval_test`
+- `parametrize_eval_cases`
+
+Criteria/reporters:
+
+- Tool, trajectory, node-order, response, exact-match, keyword, ROUGE, rubric, safety, hallucination, factual accuracy, LLM judge, and simulation criteria.
+- Console, JSON, HTML, JUnit XML, and reporter manager outputs.
+
+## Trajectory Collection
+
+Use `TrajectoryCollector` plus `make_trajectory_callback` to record node/tool execution through the callback system. Compile the graph once with the callback manager and reuse it for eval runs.
+
+## Rules
+
+- Keep unit tests model-free with `TestAgent` and mocks.
+- Use evals for behavior quality, trajectory matching, safety, and regression checks.
+- Avoid mixing live providers into fast unit tests; isolate them as integration tests.
+- For trajectory evals, compile once with the collector callback to avoid losing callback state.
+
+## Source Map
+
+- Testing package: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/qa/testing
+- Evaluation package: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/qa/evaluation
+- Public exports: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/qa/__init__.py
+- Docs: https://10xgraph.com/

tenxgraph_api/cli/templates/skills/10xgraph/references/unit-testing.md

@@ -0,0 +1,202 @@
+# Unit Testing
+
+Use this when writing fast, deterministic tests for 10xGraph agent graphs without making real LLM API calls. All helpers live in `tenxgraph.qa.testing`.
+
+## TestAgent
+
+Drop-in replacement for `Agent`. Returns predefined responses from a list, cycling when called more than once. Never calls an LLM.
+
+```python
+from tenxgraph.qa.testing import TestAgent
+
+agent = TestAgent(
+    model="test-model",           # compatibility only; ignored
+    responses=["Response 1", "Response 2"],  # cycles on repeated calls
+    tools=["get_weather"],        # optional; enables simulate_tool_calls
+    simulate_tool_calls=False,    # True → first call returns tool-call message
+)
+```
+
+Swap into an existing graph:
+
+```python
+test_agent = TestAgent(responses=["Mocked"])
+graph.override_node("MAIN", test_agent)
+app = graph.compile()
+```
+
+Build a minimal graph inline:
+
+```python
+from tenxgraph.core.graph import StateGraph
+from tenxgraph.utils.constants import END
+
+graph = StateGraph()
+graph.add_node("MAIN", test_agent)
+graph.set_entry_point("MAIN")
+graph.add_edge("MAIN", END)
+app = graph.compile()
+```
+
+Tool-call simulation — set `simulate_tool_calls=True` (or pass `tools`). First invocation returns a `tools_calls` message; subsequent invocations return responses:
+
+```python
+agent = TestAgent(responses=["Final answer."], tools=["get_weather"])
+# call 1 → tool-call message requesting get_weather
+# call 2 → "Final answer."
+```
+
+Assertion helpers:
+
+```python
+agent.assert_called()            # called at least once
+agent.assert_called_times(2)     # called exactly n times
+agent.assert_not_called()
+agent.get_last_messages()        # message list from last call
+agent.get_last_tools()           # tool specs from last call
+agent.reset()                    # clear call_count and call_history
+```
+
+Attributes: `call_count: int`, `call_history: list[dict]` (each has `messages`, `tools`, `kwargs`).
+
+## QuickTest
+
+One-liner async factory for common test scenarios. All methods are `async` — require `@pytest.mark.asyncio`.
+
+```python
+from tenxgraph.qa.testing import QuickTest
+```
+
+**single_turn** — single user/agent exchange:
+
+```python
+result = await QuickTest.single_turn(
+    agent_response="Paris.",
+    user_message="Capital of France?",
+    config=None,
+)
+```
+
+**multi_turn** — multiple turns with accumulated history:
+
+```python
+result = await QuickTest.multi_turn(
+    conversation=[
+        ("Hello", "Hi there!"),
+        ("What can you do?", "Many things."),
+    ]
+)
+```
+
+**with_tools** — agent that issues tool calls, then responds:
+
+```python
+result = await QuickTest.with_tools(
+    query="Weather in London?",
+    response="It is sunny.",
+    tools=["get_weather"],
+    tool_responses={"get_weather": "22°C"},
+)
+```
+
+Builds a `MAIN → TOOL → MAIN → END` graph internally using `TestAgent(simulate_tool_calls=True)`.
+
+**custom** — bring your own agent and optional graph setup:
+
+```python
+result = await QuickTest.custom(
+    agent=my_test_agent,
+    user_message="Run it",
+    graph_setup=None,   # callable(graph) → graph for extra wiring
+)
+```
+
+## TestResult
+
+Returned by every `QuickTest` method. All assertion methods return `self` for chaining.
+
+```python
+result.assert_contains("Paris")
+result.assert_not_contains("London")
+result.assert_equals("Paris is the capital.")
+result.assert_tool_called("get_weather")
+result.assert_tool_called("get_weather", city="London")  # with specific kwargs
+result.assert_tool_not_called("send_email")
+result.assert_message_count(3)
+result.assert_no_errors()
+```
+
+Attributes: `final_response: str`, `messages: list`, `tool_calls: list[dict]`, `state: dict`, `passed: bool`.
+
+## MockToolRegistry
+
+Registers sync or async mock tools and tracks every invocation. Pass `tools.get_tool_list()` to `ToolNode`.
+
+```python
+from tenxgraph.qa.testing import MockToolRegistry
+from tenxgraph.core.graph import ToolNode
+
+tools = MockToolRegistry()
+tools.register("get_weather", lambda city: f"22°C in {city}")
+tools.register_async("search_web", async_fn)
+
+tool_node = ToolNode(tools.get_tool_list())
+```
+
+Call tracking:
+
+```python
+tools.was_called("get_weather")                    # bool
+tools.call_count("get_weather")                    # int
+tools.get_calls("get_weather")                     # list[dict] with "args" and "kwargs"
+tools.get_last_call("get_weather")                 # dict or None
+
+tools.assert_called("get_weather")
+tools.assert_called_with("get_weather", city="London")
+tools.assert_call_count("get_weather", 2)
+
+tools.reset()    # clear history, keep functions
+tools.clear()    # clear history and functions
+```
+
+## 10xgraph test CLI
+
+Thin pytest wrapper. Reads defaults from `10xgraph.json → "test"` section; CLI flags override config.
+
+```bash
+10xgraph test                     # pytest auto-discovery from project root
+10xgraph test tests/unit          # target path
+10xgraph test --coverage          # adds --cov=. --cov-report=term-missing --cov-report=html:htmlcov
+10xgraph test --coverage --html   # opens htmlcov/index.html after run
+10xgraph test -k "weather"        # keyword filter forwarded to pytest
+10xgraph test -- -m "not integration" --tb=short   # raw pytest flags after --
+```
+
+`10xgraph.json` configuration:
+
+```json
+{
+  "test": {
+    "path": "tests",
+    "coverage": true,
+    "coverage_threshold": 80
+  }
+}
+```
+
+Exit code mirrors pytest: 0 = all pass, 1 = failures or coverage below threshold.
+
+## Rules
+
+- Never use real `Agent` in unit tests; always swap with `TestAgent`.
+- All `QuickTest` methods are async — use `@pytest.mark.asyncio`.
+- Call `agent.reset()` and `tools.reset()` between test cases to prevent state bleed.
+- Mark slow or live-provider tests with `@pytest.mark.integration` so they are excluded from fast CI runs (`10xgraph test -- -m "not integration"`).
+- `TestAgent(tools=[...])` auto-enables `simulate_tool_calls`; pair it with a real `ToolNode(tools.get_tool_list())` to exercise the full routing loop.
+
+## Source Map
+
+- TestAgent: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/qa/testing/test_agent.py
+- QuickTest / TestResult: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/qa/testing/quick_test.py
+- MockToolRegistry: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/qa/testing/mock_tools.py
+- CLI test command: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/cli/commands/test.py