---
orphan: true
---

# Project Status

This documentation targets **OpenRath v2.0.0**, the current Stable release.
The durable Runtime and Agent Server form the current release surface while
the v1 Python façade remains available.

```text
@step / @router
       |
       v
ExecutionPlan -> Run -> Event -> Checkpoint
       |                          |
       +--> SQLite               +--> Interrupt / Effect ledger
       +--> PostgreSQL + Redis + S3-compatible artifacts
                                  |
                                  v
                         tenant-scoped Agent Server
```

## v2.0.0 Capabilities

| Layer | Status | What it provides |
| --- | --- | --- |
| Workflow definition | Implemented | Explicit `@step` / `@router` methods compile into canonical plans and revision identity. |
| Durable execution | Implemented | Runs, Events, Checkpoints, Interrupts, retries, leases/fencing, cancellation, and effect reconciliation are present. |
| Embedded storage | Available | SQLite provides a self-contained local durable store. |
| Service storage | Available | PostgreSQL stores durable state; Redis provides optional signaling; S3-compatible storage holds artifacts. |
| Agent Server | Available | Versioned `/v1` HTTP/SSE resources expose assistants, sessions, runs, interrupts, feedback, memory, and metrics. |
| Authorization | Built in | Explicit action grants and tenant/project-scoped objects protect service resources. |
| Migration | Available | v1 JSONL Sessions can be imported into the v2 history model. |

See the [v2 overview](v2/index.md) and
[operations guide](v2/operations.md) for deployment guidance.

## v1 Compatibility Baseline

The v1.3.0 façade remains supported in v2.0.0. It is a usable multi-agent,
multi-session runtime with first-class memory, internal async execution,
optional LiteLLM routing, dynamic selection, and opt-in static workflow
compilation. The sections below describe that compatibility surface.

```text
Core model          Runtime path          Durability layer        Project quality
Session/Workflow -> async loop + tools -> persistence/config  ->  CI/docs/examples
Backend/Memory      local/OpenSandbox     local JSON/JSONL        Ruff + Actions
```

```{figure} _static/multi-agent-multi-session.png
:alt: Multi-agent multi-session runtime

The runtime treats multi-agent and multi-session flows as first-class
session graph operations.
```

## v1 Compatibility Capabilities

| Layer | Status | What this means |
| --- | --- | --- |
| Session core | Implemented and central | `Session` carries transcript chunks, sandbox placement, lineage, usage, and branch operations. |
| Workflow API | Implemented | Module-tree registration, dynamic `Selector`, static `compile()`, manifest inspection, and offline preflight are available. |
| Tool runtime | Implemented | `FlowToolCall` bridges model-visible schemas to backend side effects. |
| Memory plane | Implemented | Local memory is in the base install; OpenViking is optional; agents expose remember / recall / commit APIs. |
| Local backend | Available | Local command, file, and code payloads are supported and covered by conformance tests. |
| OpenSandbox backend | Integrated | Current image defaults and targeted retries provide stable sandbox lifecycle behavior. |
| LLM providers | Expanded | OpenAI-compatible and Anthropic adapters are core; optional LiteLLM adds broader provider routing; embedding and VLM clients are available. |
| Streaming | Implemented for compatible clients | `run_session_loop(on_event=...)` supports OpenAI-compatible and Anthropic streaming deltas while keeping durable assistant chunks. |
| Async runtime | Implemented internally | Public calls stay synchronous; returned sessions may lazily synchronize transcript and usage fields. |
| Persistence | Implemented | Session JSONL, shared atomic writes, root manifest, credentials sidecar, and dry-run-first GC cover cross-plane foundations. |
| MCP integration | Stdio integration available | Stdio MCP tools can be wrapped as `FlowToolCall`. |
| CI and lint | In place | Ruff, pre-commit, pytest-xdist, timeout/rerun plugins, and GitHub Actions cover lint, tests, shellcheck, OpenSandbox, and OpenViking paths. |
| Documentation | Included in v2.0.0 | API reference and tutorials cover the retained façade's compile, Provider placement, config/credentials, persistence, and current OpenSandbox behavior. |

## Core Building Blocks

These areas are the current foundation of the project:

| Capability | Evidence in repo |
| --- | --- |
| Session state model | `src/rath/session/session.py`, `chunk.py`, `loop.py`, `compress.py` |
| Workflow composition | `src/rath/flow/workflow.py`, `compile.py`, `agent.py`, `agent_param.py`, `selector.py` |
| Backend abstraction | `src/rath/backend/abc.py`, `local.py`, `tool_types.py`, `results.py` |
| Memory abstraction | `src/rath/memory/abc.py`, `op_types.py`, `results.py`, `registry.py` |
| LLM request/response DTOs | `src/rath/llm/chat_request.py`, `chat_response.py` |
| OpenAI-compatible client path | `src/rath/llm/openai/` |
| Core tutorials/examples | `docs/source/tutorial/`, `example/01_hello_agent.py` through `example/12_compile.py` |
| Test coverage shape | `tests/session/`, `tests/backends/`, `tests/llm/`, `tests/flow/`, `tests/memory/`, `tests/concurrency/` |

The repository includes focused test coverage across session behavior,
backends, provider adapters, persistence, MCP, and conformance, providing a
well-tested foundation for application development.

## v1.3 Runtime Additions

The v1.3.0 line adds inspection, placement, and persistence foundations on top of v1.2.2 runtime robustness:

| Area | Runtime change |
| --- | --- |
| Memory plane | `rath.memory` mirrors backend concepts with `MemoryBackend`, `MemoryStore`, `MemoryOp*`, results, registry, local backend, and optional OpenViking adapter. |
| Provider ecosystem | Registry-based dispatch through `chat_client_for(...)`, plus Anthropic and optional LiteLLM support. |
| Embedding and VLM | `EmbeddingProvider`, `VLMProvider`, and OpenAI-compatible thin clients support memory ranking and image description use cases. |
| Config | LLM/MCP/memory/backend schemas, `credentials.json` secret separation, and a central EnvSpec registry. |
| Internal async runtime | `run_session_loop(...)` can return a lazy session while work proceeds on the private runtime. |
| Session persistence | Append-only JSONL writer/loader with WAL partials, crash detection, and resumable pairs. |
| Sandbox persistence | Local workspace and OpenSandbox remote identity registry. |
| Sandbox lifecycle | Refcounted live handles shared by loop outputs, forks, detaches, and merges, with lock-protected acquire/release. |
| Merge primitive | `Session.merge(...)` keeps `self.sandbox`, records merge lineage, and no longer rejects cross-sandbox merges. |
| Streaming loop | `on_event` callback receives `RathLLMStreamDelta` values from OpenAI-compatible and Anthropic streaming clients. |
| MCP tools | Stdio MCP servers can be exposed to the loop as normal `FlowToolCall` tools. |
| LLM resilience | Retry policy, credential fallback, token usage accounting, and budget guardrail. |
| Dynamic routing | `Selector` chooses among workflow descriptions; `EmptyWorkflow` represents no match/completion while `if` and `while` remain ordinary Python. |
| Session ergonomics | `Session.text()` returns final assistant text and `ChunkTable` supports sequence operations. |
| Runtime hardening | Same-path file operations serialize, truncated compression raises, lazy sandbox first-open is locked, and the session registry uses weak references. |
| Static compile | Module-tree traversal builds `ResourceManifest`; preflight validates provider kind/credentials and manages reachable memory-store lifetime. |
| Provider placement | AgentParam, direct Workflow agents, and Sessions support `.to(...)`; session placement is a fallback for raw calls. |
| Persistence foundation | Shared atomic replace, config/backend/memory layout manifest, and dry-run-first cross-plane GC. |
| OpenSandbox stability | Current image/entrypoint, longer create budgets, targeted code-run retries, and safer stdout retry rules. |
| Example ladder | `example/` is now a numbered 01-12 progression ending with key-free workflow compilation. |
| Project operations | Ruff, pre-commit, pytest-xdist, timeout/rerun plugins, and split GitHub Actions matrices. |

```{figure} _static/ci-tooling-pipeline.png
:alt: OpenRath CI and tooling pipeline

The current contributor path is guarded by Ruff, type checks, tests, docs builds,
and GitHub Actions workflows.
```

## Practical Interpretation

For a new user:

- OpenRath is ready to try for local agent workflows, structured session experiments, custom tools, local memory, and provider integration work.
- It is especially useful if you want session state, tool execution, and workflow composition to be explicit Python objects.
- For service deployments, use the operations guide to configure storage,
  credentials, sandbox lifecycle, observability, backup, and recovery.

For a contributor:

- Contributor entry points include runtime execution, persistence, provider
  adapters, sandbox integrations, memory, examples, and documentation.