# Runnable Examples

These pages map to the v1.2 `example/01_hello_agent.py` through `example/10_provider_variation.py` ladder. Each script introduces one concept and keeps the public OpenRath surface in focus.

```{figure} ../../_static/example-ladder.svg
:alt: OpenRath v1.2 example ladder

The v1.2 examples move from the smallest agent call to sessions, sandboxes, tools, streaming, compression, memory, and provider variation.
```

## Ladder
| # | Page | Script | Needs key? |
| --- | --- | --- | --- |
| 01 | [Hello Agent](01_hello_agent.md) | `example/01_hello_agent.py` | yes |
| 02 | [Session Lineage](02_session_lineage.md) | `example/02_session_lineage.py` | no |
| 03 | [Sandbox Backend](03_sandbox_backend.md) | `example/03_sandbox_backend.py` | yes |
| 04 | [Built-in Tools](04_tools_builtin.md) | `example/04_tools_builtin.py` | yes |
| 05 | [Custom Tool](05_custom_tool.md) | `example/05_custom_tool.py` | yes |
| 06 | [MCP Tool](06_mcp_tool.md) | `example/06_mcp_tool.py` | no |
| 07 | [Streaming](07_streaming.md) | `example/07_streaming.py` | yes |
| 08 | [Compress](08_compress.md) | `example/08_compress.py` | yes |
| 09 | [Memory](09_memory.md) | `example/09_memory.py` | no for remember/recall |
| 10 | [Provider Variation](10_provider_variation.md) | `example/10_provider_variation.py` | yes |

## Setup
Run examples from the OpenRath repository root:

```bash
python example/02_session_lineage.py
```

Examples that call a real LLM read provider settings from environment variables or `~/.openrath/config.json`:

```bash
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=...
export OPENAI_DEFAULT_MODEL=...
```

The former large demos (`trading_agents`, `engineering_agents`, `research_transformer`) are no longer the main tutorial path. Treat them as migration/reference material if they exist in an older branch.

```{toctree}
---
maxdepth: 2
caption: Runnable Examples
---

01_hello_agent
02_session_lineage
03_sandbox_backend
04_tools_builtin
05_custom_tool
06_mcp_tool
07_streaming
08_compress
09_memory
10_provider_variation
```