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.

@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 and operations guide 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.

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

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.

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.