RouteKitAI 0.1.0__tar.gz → 0.2.0__tar.gz

{routekitai-0.1.0/src/RouteKitAI.egg-info → routekitai-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RouteKitAI
-Version: 0.1.0
+Version: 0.2.0
 Summary: An agent development + orchestration framework
 Author: Mohamed Ghassen Brahim
 License: MIT
@@ -195,50 +195,53 @@ asyncio.run(main())
 
 - **[Architecture Guide](docs/architecture.md)**: Deep dive into RouteKitAI's design
 - **[Security & Governance](docs/security-and-governance.md)**: Security features and best practices
-- **[API Reference](https://RouteKitAI.readthedocs.io)**: Complete API documentation (coming soon)
+- **[Full documentation](https://routekitai.readthedocs.io)**: Architecture, security, and guides (Read the Docs)
 
 ## 🎓 Examples
 
 Check out the [`examples/`](examples/) directory for complete examples:
 
-- **[Basic Agent](examples/hello_RouteKitAI.py)**: Simple agent with tools
-- **[Graph Orchestration](examples/graph_agent.py)**: Multi-agent workflow
-- **[Supervisor Pattern](examples/supervisor_agent.py)**: Supervisor delegating to sub-agents
+- **[Basic Agent](examples/basic.py)** / **[Hello RouteKit](examples/hello_routekit.py)**: Simple agent with tools
+- **[Graph Orchestration](examples/graph_agent.py)** / **[Graph Policy](examples/graph_policy.py)**: Multi-agent workflows
+- **[Supervisor Pattern](examples/supervisor_agent.py)** / **[Supervisor Policy](examples/supervisor_policy.py)**: Supervisor delegating to sub-agents
+- **[ReAct / Plan–Execute / Function Calling](examples/react_policy.py)**, **[Plan–Execute](examples/plan_execute_policy.py)**, **[Function Calling](examples/function_calling_policy.py)**: Policy examples
 - **[Evaluation Harness](examples/eval_regression.py)**: Testing agents with datasets
 
+Run all examples: `./scripts/run_examples.sh` (or `bash scripts/run_examples.sh`).
+
 ## 🛠️ CLI Commands
 
-RouteKitAI provides a CLI for common operations:
+RouteKitAI provides a CLI (`routekitai`) for common operations:
 
 ```bash
 # Run an agent script
-RouteKitAI run agent_script.py
+routekitai run agent_script.py
 
 # View a trace (multiple formats available)
-RouteKitAI trace <trace_id>                    # Table view (default)
-RouteKitAI trace <trace_id> --format timeline  # Timeline visualization
-RouteKitAI trace <trace_id> --format steps     # Step-by-step execution
-RouteKitAI trace <trace_id> --format json      # JSON output
-RouteKitAI trace <trace_id> --format raw       # Raw JSONL
+routekitai trace <trace_id>                    # Table view (default)
+routekitai trace <trace_id> --format timeline  # Timeline visualization
+routekitai trace <trace_id> --format steps     # Step-by-step execution
+routekitai trace <trace_id> --format json     # JSON output
+routekitai trace <trace_id> --format raw      # Raw JSONL
 
 # Analyze trace metrics
-RouteKitAI trace-analyze <trace_id>            # Performance metrics, token usage, costs
+routekitai trace-analyze <trace_id>            # Performance metrics, token usage, costs
 
 # Search traces
-RouteKitAI trace-search "error"                # Search all traces for "error"
-RouteKitAI trace-search "model" --trace-id abc # Search specific trace
-RouteKitAI trace-search "tool" --event-type tool_called  # Filter by event type
+routekitai trace-search "error"                # Search all traces for "error"
+routekitai trace-search "model" --trace-id abc # Search specific trace
+routekitai trace-search "tool" --event-type tool_called  # Filter by event type
 
 # Replay a trace
-RouteKitAI replay <trace_id> --agent my_agent
+routekitai replay <trace_id> --agent my_agent
 
 # Start web UI for trace visualization
-RouteKitAI serve                    # Start on default port 8080
-RouteKitAI serve --port 3000        # Custom port
-RouteKitAI serve --host 0.0.0.0     # Make accessible from network
+routekitai serve                    # Start on default port 8080
+routekitai serve --port 3000        # Custom port
+routekitai serve --host 0.0.0.0     # Make accessible from network
 
 # Run sanity checks
-RouteKitAI test-agent
+routekitai test-agent
 ```
 
 ## 🏗️ Core Primitives
@@ -271,7 +274,7 @@ pip install -e ".[dev]"
 pytest
 
 # Run with coverage
-pytest --cov=RouteKitAI --cov-report=html
+pytest --cov=routekitai --cov-report=html
 
 # Run specific test file
 pytest tests/test_runtime.py
@@ -284,15 +287,15 @@ pytest tests/test_runtime.py
 mypy src/
 
 # Linting
-ruff check src/
+ruff check src/ tests/ examples/
 
 # Format code
-ruff format src/
+ruff format src/ tests/ examples/
 ```
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please read our contributing guidelines (coming soon) and:
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and:
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -316,7 +319,7 @@ RouteKitAI is inspired by the need for testable, observable AI agent frameworks.
 ## 🔗 Links
 
 - **GitHub**: [https://github.com/MedGhassen/RouteKitAI](https://github.com/MedGhassen/RouteKitAI)
-- **Documentation**: [https://RouteKitAI.readthedocs.io](https://RouteKitAI.readthedocs.io) (coming soon)
+- **Documentation**: [https://routekitai.readthedocs.io](https://routekitai.readthedocs.io)
 - **Issues**: [https://github.com/MedGhassen/RouteKitAI/issues](https://github.com/MedGhassen/RouteKitAI/issues)
 
 ---

{routekitai-0.1.0 → routekitai-0.2.0}/README.md

@@ -150,50 +150,53 @@ asyncio.run(main())
 
 - **[Architecture Guide](docs/architecture.md)**: Deep dive into RouteKitAI's design
 - **[Security & Governance](docs/security-and-governance.md)**: Security features and best practices
-- **[API Reference](https://RouteKitAI.readthedocs.io)**: Complete API documentation (coming soon)
+- **[Full documentation](https://routekitai.readthedocs.io)**: Architecture, security, and guides (Read the Docs)
 
 ## 🎓 Examples
 
 Check out the [`examples/`](examples/) directory for complete examples:
 
-- **[Basic Agent](examples/hello_RouteKitAI.py)**: Simple agent with tools
-- **[Graph Orchestration](examples/graph_agent.py)**: Multi-agent workflow
-- **[Supervisor Pattern](examples/supervisor_agent.py)**: Supervisor delegating to sub-agents
+- **[Basic Agent](examples/basic.py)** / **[Hello RouteKit](examples/hello_routekit.py)**: Simple agent with tools
+- **[Graph Orchestration](examples/graph_agent.py)** / **[Graph Policy](examples/graph_policy.py)**: Multi-agent workflows
+- **[Supervisor Pattern](examples/supervisor_agent.py)** / **[Supervisor Policy](examples/supervisor_policy.py)**: Supervisor delegating to sub-agents
+- **[ReAct / Plan–Execute / Function Calling](examples/react_policy.py)**, **[Plan–Execute](examples/plan_execute_policy.py)**, **[Function Calling](examples/function_calling_policy.py)**: Policy examples
 - **[Evaluation Harness](examples/eval_regression.py)**: Testing agents with datasets
 
+Run all examples: `./scripts/run_examples.sh` (or `bash scripts/run_examples.sh`).
+
 ## 🛠️ CLI Commands
 
-RouteKitAI provides a CLI for common operations:
+RouteKitAI provides a CLI (`routekitai`) for common operations:
 
 ```bash
 # Run an agent script
-RouteKitAI run agent_script.py
+routekitai run agent_script.py
 
 # View a trace (multiple formats available)
-RouteKitAI trace <trace_id>                    # Table view (default)
-RouteKitAI trace <trace_id> --format timeline  # Timeline visualization
-RouteKitAI trace <trace_id> --format steps     # Step-by-step execution
-RouteKitAI trace <trace_id> --format json      # JSON output
-RouteKitAI trace <trace_id> --format raw       # Raw JSONL
+routekitai trace <trace_id>                    # Table view (default)
+routekitai trace <trace_id> --format timeline  # Timeline visualization
+routekitai trace <trace_id> --format steps     # Step-by-step execution
+routekitai trace <trace_id> --format json     # JSON output
+routekitai trace <trace_id> --format raw      # Raw JSONL
 
 # Analyze trace metrics
-RouteKitAI trace-analyze <trace_id>            # Performance metrics, token usage, costs
+routekitai trace-analyze <trace_id>            # Performance metrics, token usage, costs
 
 # Search traces
-RouteKitAI trace-search "error"                # Search all traces for "error"
-RouteKitAI trace-search "model" --trace-id abc # Search specific trace
-RouteKitAI trace-search "tool" --event-type tool_called  # Filter by event type
+routekitai trace-search "error"                # Search all traces for "error"
+routekitai trace-search "model" --trace-id abc # Search specific trace
+routekitai trace-search "tool" --event-type tool_called  # Filter by event type
 
 # Replay a trace
-RouteKitAI replay <trace_id> --agent my_agent
+routekitai replay <trace_id> --agent my_agent
 
 # Start web UI for trace visualization
-RouteKitAI serve                    # Start on default port 8080
-RouteKitAI serve --port 3000        # Custom port
-RouteKitAI serve --host 0.0.0.0     # Make accessible from network
+routekitai serve                    # Start on default port 8080
+routekitai serve --port 3000        # Custom port
+routekitai serve --host 0.0.0.0     # Make accessible from network
 
 # Run sanity checks
-RouteKitAI test-agent
+routekitai test-agent
 ```
 
 ## 🏗️ Core Primitives
@@ -226,7 +229,7 @@ pip install -e ".[dev]"
 pytest
 
 # Run with coverage
-pytest --cov=RouteKitAI --cov-report=html
+pytest --cov=routekitai --cov-report=html
 
 # Run specific test file
 pytest tests/test_runtime.py
@@ -239,15 +242,15 @@ pytest tests/test_runtime.py
 mypy src/
 
 # Linting
-ruff check src/
+ruff check src/ tests/ examples/
 
 # Format code
-ruff format src/
+ruff format src/ tests/ examples/
 ```
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please read our contributing guidelines (coming soon) and:
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and:
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -271,7 +274,7 @@ RouteKitAI is inspired by the need for testable, observable AI agent frameworks.
 ## 🔗 Links
 
 - **GitHub**: [https://github.com/MedGhassen/RouteKitAI](https://github.com/MedGhassen/RouteKitAI)
-- **Documentation**: [https://RouteKitAI.readthedocs.io](https://RouteKitAI.readthedocs.io) (coming soon)
+- **Documentation**: [https://routekitai.readthedocs.io](https://routekitai.readthedocs.io)
 - **Issues**: [https://github.com/MedGhassen/RouteKitAI/issues](https://github.com/MedGhassen/RouteKitAI/issues)
 
 ---

routekitai-0.2.0/docs/api-reference.md

@@ -0,0 +1,135 @@
+# API reference
+
+Overview of the main public APIs in RouteKitAI. For full signatures and docstrings, use the in-editor help or the source under `src/routekitai/`.
+
+---
+
+## Core: `routekitai` (top-level)
+
+| Symbol | Description |
+|--------|-------------|
+| **Agent** | Agent with model, tools, optional policy and memory. Use `agent.run(prompt)` or `agent.run_stream(prompt)`. |
+| **RunResult** | Result of a run: `output` (Message), `trace_id`, `messages`, `final_state`. |
+| **Runtime** | Orchestrator: register agents, run with optional policy, replay traces. |
+| **Message** | Single message: `role`, `content`, `tool_calls`, `tool_result`, `metadata`. |
+| **MessageRole** | Enum: SYSTEM, USER, ASSISTANT, TOOL. |
+| **Model** | Abstract LLM interface: `chat(messages, tools=..., stream=...)`. |
+| **ModelResponse** | `content`, `tool_calls`, `usage`, `metadata`. |
+| **StreamEvent** | Streaming event: `type`, `content`, `tool_calls`, `usage`, `metadata`. |
+| **Tool** | Abstract base for tools: `name`, `description`, `input_model`, `output_model`, `run(input)`. |
+| **ToolCall** | Model-requested tool call: `id`, `name`, `arguments`. |
+| **ToolFilter** | Allow/deny list for tools (agent or runtime hooks). |
+| **Usage** | Token/cost info: `prompt_tokens`, `completion_tokens`, `total_tokens`, `cost`. |
+| **RouteKitError**, **ModelError**, **ToolError**, **PolicyError**, **RouteKitRuntimeError** | Error types. |
+
+---
+
+## Core: `routekitai.core`
+
+### Agent and runtime
+
+- **Agent** — Same as top-level. Fields: `name`, `model`, `tools`, `policy`, `memory`, `tool_filter`, `trace_dir`.
+- **RunResult** — Same as top-level.
+- **Runtime** — `agents`, `trace_dir`, `timeout`, `max_concurrency`, `policy_hooks`, etc. Methods: `register_agent()`, `run()`, `replay()`.
+
+### Messages and model
+
+- **Message**, **MessageRole** — As above.
+- **Model**, **ModelResponse**, **StreamEvent**, **ToolCall**, **Usage** — As above.
+
+### Tools
+
+- **Tool** — Base class. Subclass and implement `run(input) -> output`. Optional: `input_model`, `output_model`, `permissions`, `timeout`, `redact_fields`.
+- **ToolPermission** — Enum: NETWORK, FILESYSTEM, DATABASE, NONE.
+- **EchoTool**, **HttpGetTool**, **FileReadTool** — Built-in tools in `routekitai.core.tools`.
+
+### Policies
+
+- **Policy** — Abstract: `plan(state) -> list[Action]`, `reflect(state, observation) -> state`.
+- **Action** — Base for model/tool/parallel/final actions.
+- **ModelAction**, **ToolAction**, **Parallel**, **Final** — Action types.
+- **ReActPolicy** — Reasoning + acting loop (default). Config: `max_iterations`.
+- **FunctionCallingPolicy** — Strict function-calling.
+- **GraphPolicy** — Runs a `Graph`; requires a Runtime with registered agents.
+- **SupervisorPolicy** — Delegates to other agents.
+- **PlanExecutePolicy** — Plan then execute.
+- **PolicyAdapter** — Adapts policy interface for the runtime.
+
+### Hooks (security and governance)
+
+- **PolicyHooks** — Container: `pii_redaction`, `tool_filter`, `approval_gate`.
+- **PIIRedactionHook** — Redact emails, phones, custom patterns.
+- **ToolFilter** — `allowed_tools` / `denied_tools`.
+- **ApprovalGate** — Require approval for certain permissions; `approval_callback(tool_name, tool_args) -> bool`.
+
+---
+
+## Graphs: `routekitai.graphs`
+
+| Symbol | Description |
+|--------|-------------|
+| **Graph** | Workflow: `name`, `nodes`, `edges`, `entry_node`, `exit_node`, `state_schema`, `config`. |
+| **GraphNode** | Node: `id`, `type` (NodeType), `agent_name` / `tool_name` / `subgraph_name` / `condition`, `input_mapping`, `output_mapping`. |
+| **GraphEdge** | Edge: `source`, `target`, optional `condition`. |
+| **NodeType** | Enum: MODEL, TOOL, SUBGRAPH, CONDITION. |
+| **GraphExecutor** | Executes a graph (used internally by GraphPolicy). |
+
+---
+
+## Memory: `routekitai.memory`
+
+| Symbol | Description |
+|--------|-------------|
+| **Memory** | Abstract interface (from `routekitai.core.memory`). |
+| **WorkingMemory** | In-memory context for a single run. |
+| **EpisodicMemory** | SQLite-backed episode storage. |
+| **RetrievalMemory** | TF-IDF or substring search. |
+| **VectorMemory** | Vector similarity search (in `routekitai.memory.vector`). |
+| **KVMemory** | Key-value store (in `routekitai.memory.kv`). |
+
+---
+
+## Evaluations: `routekitai.evals`
+
+| Symbol | Description |
+|--------|-------------|
+| **Dataset** | Evaluation dataset (inputs and expected outputs). |
+| **EvalRunner** | Runs an agent over a dataset and computes metrics. |
+| **ExactMatchMetric**, **ContainsMetric**, **RegexMetric** | Built-in metrics. |
+
+---
+
+## Providers: `routekitai.providers`
+
+| Symbol | Description |
+|--------|-------------|
+| **FakeModel** | Local model with preloaded responses (no API key). |
+| **OpenAIChatModel** | OpenAI chat API. |
+| **AnthropicChatModel** | Anthropic API (if installed). |
+| **AzureOpenAIChatModel** | Azure OpenAI (if installed). |
+
+---
+
+## Observability: `routekitai.observability`
+
+- **Trace**, **TraceEvent** — Trace representation.
+- **JSONLExporter** — Writes traces to `.routekit/traces/<trace_id>.jsonl`.
+- **Analyzer** — Trace analysis (used by CLI `trace-analyze`).
+- **OtelExporter** — OpenTelemetry export (optional).
+
+---
+
+## Sandbox: `routekitai.sandbox`
+
+- **FilesystemSandbox** — Restrict filesystem access.
+- **NetworkSandbox** — Restrict network access.
+- **PermissionManager** — Manages tool permissions (used by runtime).
+
+---
+
+## Version
+
+```python
+import routekitai
+print(routekitai.__version__)
+```

{routekitai-0.1.0 → routekitai-0.2.0}/docs/architecture.md

@@ -237,8 +237,9 @@ RouteKitAI supports multiple memory backends:
 
 - **EpisodicMemory**: SQLite-backed episode storage
 - **RetrievalMemory**: TF-IDF or substring search
-- **VectorMemory**: Vector similarity search (planned)
-- **KVMemory**: Key-value storage (planned)
+- **VectorMemory**: Vector similarity search
+- **KVMemory**: Key-value storage
+- **WorkingMemory**: In-memory context for a single run
 
 Memory is accessed through the `Memory` abstract interface, allowing agents to retain context across runs.
 
@@ -273,16 +274,16 @@ Sandboxing provides isolation for tool execution:
 - Memory backends: Episodic and retrieval memory
 - Security hooks: PII redaction, tool filtering, approval gates
 - CLI tools: Run, trace, replay, test commands
+- Trace analysis: Metrics (`trace-analyze`), search (`trace-search`), timeline/step views, web UI (`serve`)
 
 ### Excluded (Post-MVP)
 
 - Distributed execution: Multi-machine orchestration
 - Streaming traces: Real-time trace streaming/aggregation
-- Trace analysis: Advanced querying, visualization, metrics
-- Production observability: Integration with monitoring systems
+- Production observability: Integration with external monitoring (e.g. OpenTelemetry exporters exist; full integration TBD)
 - Advanced graph features: Dynamic graphs, conditional branching beyond basics
 - Model providers: Built-in integrations (use adapters)
-- UI/dashboards: Trace visualization tools
+- UI/dashboards: Additional trace visualization (basic serve UI included)
 
 ## Design Principles
 
@@ -309,7 +310,7 @@ Performance optimizations can be added later without breaking the core design.
 
 - **Distributed execution**: Scale across multiple machines
 - **Advanced graph features**: Dynamic graphs, parallel node execution
-- **Trace analysis**: Query, visualize, and analyze traces
+- **Trace analysis**: Further tooling and integrations (basic analysis and serve UI included)
 - **Production observability**: Integrate with monitoring systems
 - **Model provider integrations**: Built-in support for major LLM providers
 - **UI/dashboards**: Visual trace inspection and graph editing

routekitai-0.2.0/docs/getting-started.md

@@ -0,0 +1,117 @@
+# Getting Started
+
+This guide gets you from zero to running your first agent and first graph in RouteKitAI.
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install RouteKitAI
+```
+
+For development (CLI, tests, type checking):
+
+```bash
+pip install "RouteKitAI[dev]"
+```
+
+Optional extras:
+
+- **`[ui]`** — Web UI for traces (`routekitai serve`): FastAPI, Uvicorn
+- **`[optional]`** — Vector memory, OpenAI/Anthropic adapters: sentence-transformers, faiss, openai, etc.
+
+```bash
+pip install "RouteKitAI[dev,ui,optional]"
+```
+
+**Requirements:** Python 3.11+, Pydantic 2.x.
+
+## Your first agent
+
+A minimal agent needs a **model** and optionally **tools**. RouteKitAI uses a provider-agnostic `Model` interface, so you can start with a fake model (no API key) and later switch to OpenAI, Anthropic, or your own backend.
+
+```python
+import asyncio
+from routekitai import Agent
+from routekitai.core.tools import EchoTool
+from routekitai.providers.local import FakeModel
+
+async def main():
+    # Local fake model (no API key)
+    model = FakeModel(name="basic")
+    model.add_response("Hello! I used the echo tool.")
+
+    agent = Agent(
+        name="assistant",
+        model=model,
+        tools=[EchoTool()],
+    )
+
+    result = await agent.run("Say hello and echo 'RouteKit works!'")
+    print(result.output.content)
+    print("Trace ID:", result.trace_id)
+
+asyncio.run(main())
+```
+
+- **`agent.run(prompt)`** — Runs the agent and returns a `RunResult` with `output`, `trace_id`, `messages`, and `final_state`.
+- Every run is **traced** by default; traces are written under `.routekit/traces/` unless you set `trace_dir` on the agent.
+
+## Your first graph
+
+Graphs define **explicit workflows** as nodes (model, tool, subgraph, condition) and edges. Use `GraphPolicy` with a `Runtime` and registered agents.
+
+```python
+import asyncio
+from pathlib import Path
+from routekitai import Agent
+from routekitai.core.policies import GraphPolicy
+from routekitai.core.runtime import Runtime
+from routekitai.core.tools import EchoTool
+from routekitai.graphs import Graph, GraphNode, GraphEdge, NodeType
+from routekitai.providers.local import FakeModel
+
+async def main():
+    model = FakeModel(name="m1")
+    model.add_response("Processing...")
+    agent = Agent(name="worker", model=model, tools=[EchoTool()])
+
+    graph = Graph(
+        name="example",
+        entry_node="start",
+        exit_node="end",
+        nodes=[
+            GraphNode(id="start", type=NodeType.MODEL, agent_name="worker",
+                     output_mapping={"output": "result"}),
+            GraphNode(id="end", type=NodeType.MODEL, agent_name="worker",
+                     input_mapping={"result": "input"}, output_mapping={"output": "final"}),
+        ],
+        edges=[
+            GraphEdge(source="start", target="end"),
+        ],
+    )
+
+    runtime = Runtime(trace_dir=Path(".routekit/traces"))
+    runtime.register_agent(agent)
+    policy = GraphPolicy(graph=graph)
+
+    result = await runtime.run("worker", "Hello", policy=policy)
+    print(result.output.content)
+    print("Trace ID:", result.trace_id)
+
+asyncio.run(main())
+```
+
+In practice you’ll often build the graph and policy once, then call `runtime.run(...)` with the appropriate agent and policy. See [Graph workflows](guides/graph-workflows.md) for full details.
+
+## Next steps
+
+- **[Running agents](guides/running-agents.md)** — `run` vs `run_stream`, using `Runtime` directly, trace directory.
+- **[Creating tools](guides/creating-tools.md)** — Define tools with Pydantic input/output, permissions, redaction.
+- **[Graph workflows](guides/graph-workflows.md)** — Nodes, edges, state mapping, `GraphPolicy`, subgraphs.
+- **[Tracing and replay](guides/tracing-and-replay.md)** — Trace IDs, CLI (`trace`, `trace-analyze`, `replay`), replay for tests.
+- **[CLI reference](guides/cli-reference.md)** — All `routekitai` commands and options.
+- **[Providers](guides/providers.md)** — FakeModel, OpenAI, environment variables.
+
+For design and concepts, see [Architecture](architecture.md). For security (PII redaction, tool filtering, approval gates), see [Security & Governance](security-and-governance.md).

routekitai-0.2.0/docs/guides/cli-reference.md

@@ -0,0 +1,134 @@
+# CLI reference
+
+The RouteKitAI CLI is invoked as **`routekitai`**. Install with `pip install RouteKitAI` or `pip install "RouteKitAI[dev]"` for full CLI support.
+
+Default trace directory: **`.routekit/traces`** (overridable per command where noted).
+
+---
+
+## `routekitai run <script>`
+
+Runs a Python script that uses RouteKitAI (e.g. defines agents and calls `agent.run()` or `runtime.run()`).
+
+```bash
+routekitai run path/to/agent_script.py
+```
+
+- The script is executed in a way that allows async entrypoints; typically the script uses `asyncio.run(main())` or similar.
+- Traces from the run are written to the default trace dir (or the dir set by the script’s runtime/agent).
+
+---
+
+## `routekitai trace <trace_id>`
+
+Prints a trace by ID.
+
+```bash
+routekitai trace <trace_id> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--format`, `-f` | Output format: `table` (default), `timeline`, `steps`, `json`, `raw` |
+| `--trace-dir`, `-t` | Trace directory (default: `.routekit/traces`) |
+
+---
+
+## `routekitai trace-analyze <trace_id>`
+
+Prints metrics for a trace: timing, token usage, cost (when available).
+
+```bash
+routekitai trace-analyze <trace_id> [--trace-dir PATH]
+```
+
+---
+
+## `routekitai trace-search [query]`
+
+Searches trace contents.
+
+```bash
+routekitai trace-search "query" [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--trace-id` | Limit search to one trace |
+| `--event-type` | Filter by event type (e.g. `tool_called`, `model_called`) |
+| `--trace-dir` | Trace directory |
+
+---
+
+## `routekitai replay <trace_id>`
+
+Replays a trace with stubbed model and tool responses.
+
+```bash
+routekitai replay <trace_id> --agent <agent_name> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--agent` | Agent name to use for replay (required) |
+| `--trace-dir` | Trace directory |
+
+---
+
+## `routekitai serve`
+
+Starts the web UI for browsing and viewing traces.
+
+```bash
+routekitai serve [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--port`, `-p` | Port (default: 8080) |
+| `--host` | Bind address (e.g. `0.0.0.0` for network access) |
+| `--trace-dir`, `-t` | Trace directory (default: `.routekit/traces`) |
+
+Requires the **`[ui]`** extra: `pip install "RouteKitAI[ui]"`.
+
+---
+
+## `routekitai test-agent`
+
+Runs sanity checks (e.g. that the package and a minimal agent run correctly).
+
+```bash
+routekitai test-agent
+```
+
+Useful in CI or after install to verify the environment.
+
+---
+
+## Environment
+
+- **`ROUTEKIT_TRACE_DIR`** — Used by `serve` (and possibly other commands) as the trace directory when `--trace-dir` is not set. Example: `export ROUTEKIT_TRACE_DIR=/var/traces`.
+
+---
+
+## Examples
+
+```bash
+# Run an agent script
+routekitai run examples/basic.py
+
+# View last run’s trace (use the trace_id printed by the script)
+routekitai trace f98eb1b6-6eec-42df-b42a-021dc704620b --format timeline
+
+# Analyze it
+routekitai trace-analyze f98eb1b6-6eec-42df-b42a-021dc704620b
+
+# Search all traces for "error"
+routekitai trace-search "error"
+
+# Replay
+routekitai replay f98eb1b6-6eec-42df-b42a-021dc704620b --agent assistant
+
+# Start trace UI
+routekitai serve --port 3000
+```