# Tutorials
These tutorials document the v1-compatible Python façade retained in OpenRath
v2.0.0. They are organized in the order you are likely to use it: build a
`Session`, understand where tools run, try complete Colab projects, then move
into the numbered example ladder.

Each tutorial focuses on code snippets, key-line notes, and observed behavior. Together they cover the common path from basic API usage to Workflow customization.

## Core Learning Path
| Order | Page | What it covers |
| --- | --- | --- |
| 1 | [Session Basics](session_basics.md) | Create user and agent sessions, and understand `fork()`, `detach()`, and Backend placement. |
| 2 | [Local Sandbox Tools](local_sandbox_tools.md) | Open a local Backend directly and see how file, command, and code payloads run around a workspace. |
| 3 | [Session Loop Tool Calls](session_loop_tools.md) | Understand model tool calls, tool dispatch, `tool_result` chunks, and the next completion round. |
| 4 | [Custom FlowToolCall](custom_flow_tool.md) | Define your own tool schema and Python execution logic, then pass it into the Session loop. |
| 5 | End-to-End Colab Examples | Build a literature review, an editable presentation, and an Excel dashboard with durable OpenRath v2.0.0 workflows. |
| 6 | [Runnable Examples](examples/index.md) | Move into the v1-compatible 01-12 learning ladder included in v2.0.0, including memory, dynamic routing, and workflow compile. |

## End-to-End Colab Examples

These three projects come from the public
[`Rath-Team/example`](https://github.com/Rath-Team/example) repository. Each
Notebook uses fixed inputs and support code, runs an OpenRath v2.0.0 durable
workflow, verifies the result, and offers the final artifact for download.

| Example | Durable workflow focus | Final artifact |
| --- | --- | --- |
| [Colab 01: Literature Research](colab_examples/literature_research.md) | Checkpoint recovery, source constraints, and an evaluation gate. | `literature-review.md` |
| [Colab 02: PPT Creation](colab_examples/ppt_creation.md) | A persistent approval interrupt followed by resumable delivery. | `openrath-presentation.pptx` |
| [Colab 03: Excel Visualization](colab_examples/excel_visualization.md) | Data-quality routing, formula audit, and worksheet previews. | `sales-dashboard.xlsx` |

## Example Groups
| Group | Use it for | Entry |
| --- | --- | --- |
| Basics | See the smallest runnable paths through agents and lineage. | [01 Hello Agent](examples/01_hello_agent.md), [02 Session Lineage](examples/02_session_lineage.md) |
| Runtime & Tools | Check where tools execute and how tool calls are represented. | [03 Sandbox Backend](examples/03_sandbox_backend.md), [04 Built-in Tools](examples/04_tools_builtin.md), [05 Custom Tool](examples/05_custom_tool.md) |
| Integrations | Try MCP tools, streaming, compression, memory, and provider variation. | [06 MCP Tool](examples/06_mcp_tool.md), [07 Streaming](examples/07_streaming.md), [08 Compress](examples/08_compress.md), [09 Memory](examples/09_memory.md), [10 Provider Variation](examples/10_provider_variation.md) |
| Orchestration | Route dynamically, then inspect the static resources that can be known before execution. | [11 Dynamic Selector](examples/11_dynamic_selector.md), [12 Workflow Compile](examples/12_compile.md) |

## Choose by Task
| Task | Start with |
| --- | --- |
| Understand OpenRath's state model | [Session Basics](session_basics.md) |
| Check which directory tools run in | [Local Sandbox Tools](local_sandbox_tools.md) |
| See how an agent calls tools across turns | [Session Loop Tool Calls](session_loop_tools.md) |
| Wrap an external API as a model-callable tool | [Custom FlowToolCall](custom_flow_tool.md) |
| Connect OpenSandbox | [03 Sandbox Backend](examples/03_sandbox_backend.md) |
| Try a streaming UI callback | [07 Streaming](examples/07_streaming.md) |
| Use an Anthropic model | [10 Provider Variation](examples/10_provider_variation.md) |
| Wrap an MCP server as tools | [06 MCP Tool](examples/06_mcp_tool.md) |
| Inspect session lineage | [02 Session Lineage](examples/02_session_lineage.md) |
| Try key-free local memory | [09 Memory](examples/09_memory.md) |
| Route dynamically between workflows | [11 Dynamic Selector](examples/11_dynamic_selector.md) |
| Inspect workflow resources before a run | [12 Workflow Compile](examples/12_compile.md) |

## How to Read
Each page uses the same structure:

1. Read the coverage table first to confirm what the page explains.
2. Follow the code steps to understand the API boundary.
3. Compare the key-line notes to see where state changes.
4. Run or rewrite the exercises to turn the example into your own code.
5. If behavior is unexpected, check the troubleshooting table first, then use Developer Notes for source-level details.

```{toctree}
---
maxdepth: 2
caption: Tutorials
---

session_basics
local_sandbox_tools
session_loop_tools
custom_flow_tool
colab_examples/literature_research
colab_examples/ppt_creation
colab_examples/excel_visualization
examples/index
```