OpenRath

Stable release · OpenRath v2.0.0

Durable, explicit multi-agent execution.

OpenRath v2 compiles explicit workflow steps into immutable plans, then persists Runs, Events, Checkpoints, Interrupts, and effect outcomes across worker restarts. The v1 Session and Agent façade remains available in v2.0.0.

Get Started with v2.0.0 Read v2 Overview GitHub

from pathlib import Path
from uuid import uuid4

from rath.context import RunContext
from rath.definition import EffectClass, step
from rath.flow import Workflow
from rath.runtime import LocalRuntime, SQLiteRunStore
from rath.session import Session


class DurableHello(Workflow):
    @step(entry=True, effects=EffectClass.READ_ONLY)
    def finish(self, state, context):
        return {**state, "message": "hello from OpenRath v2"}

    def forward(self, session: Session) -> Session:
        return session


store = SQLiteRunStore(Path("openrath.db"))
runtime = LocalRuntime(store)
run = runtime.submit(
    DurableHello(),
    session_id=uuid4(),
    context=RunContext.local(revision_id=uuid4()),
)
completed = runtime.work_once(worker_id="local-worker")
print(completed.status, completed.state)

The embedded path provides local durable execution with SQLite. Agent Server deployments use PostgreSQL, explicit action grants, governed adapters, a durable audit sink, and optional Redis and S3-compatible services.

Where To Start

Path	Use it for	Entry
v2 quickstart	Install the v2.0.0 release wheel and run one durable workflow with SQLite.	Quickstart
v2 operations	Configure storage, rollout, incident, and recovery boundaries.	Operations
Migration	Bring v1 JSONL Sessions into the v2 history model.	v1 → v2 migration
Installation	Choose the v2.0.0 release asset or the v1-compatible PyPI path.	Installation
Project Status	Review v2.0.0 capability coverage and rollout guidance.	Project Status
v1-compatible tutorials	Learn the Session, Workflow, Tool, Sandbox, and Memory façade retained in v2.0.0.	Tutorials
Release Notes	Review v2.0.0 features, compatibility, and upgrade guidance.	Release Notes
Blog	Read project updates, release announcements, and engineering notes.	Blog
Developer Notes	Understand runtime components, call boundaries, memory, and async behavior.	Developer Notes
API Reference	Look up public modules, function signatures, and integration points.	API Reference

v2 Durable Model

Concept	Role
@step / @router	Declares explicit, compilable execution and routing boundaries.
ExecutionPlan	Canonical graph bound to an immutable revision identity.
Run	Durable execution state with tenant, session, plan, and revision identity.
Event / Checkpoint	Records ordered lifecycle evidence and resumable per-step state.
Lease / fencing token	Prevents a stale worker from committing after ownership changes.
Effect ledger	Reconciles retries and ambiguous external side effects.
AgentServer	Exposes tenant/project-scoped HTTP and SSE resources behind explicit grants.

v1 Compatibility Model

Concept	Role
Session	Carries ordered chunk rows, sandbox placement, and lineage metadata through a run.
Backend	Opens the local or OpenSandbox execution environment attached to a session.
Memory	Persists recalled and committed agent knowledge through local or optional OpenViking stores.
FlowToolCall	Exposes JSON schemas to the model and Python callables to the runtime.
Workflow	Composes agents as modules and can compile a static resource manifest before runtime.
Selector	Chooses the next self-describing workflow while control flow stays in ordinary Python.
AgentParam	Stores the agent system session plus LLM routing options.
Provider	Routes OpenAI-compatible, Anthropic, or optional LiteLLM chat clients and stores request policy.
CompiledWorkflow	Wraps a workflow with an inspectable resource snapshot, offline preflight, and memory-store lifecycle.

OpenRath borrows PyTorch’s compositional vocabulary for agent runtime state: Session as the flowing value, Backend as placement, Memory as persistent state, Tool as callable operation, and Workflow as composition.

The runtime separates agent composition, session state, backend placement, and memory into explicit surfaces.

v1-compatible Example Ladder

Example	Demonstrates
01 Hello Agent	The smallest flow.Agent program.
02 Session Lineage	Fork, detach, session graph, and JSONL export.
09 Memory	Key-free local memory remember / recall / commit.
10 Provider Variation	Swapping OpenAI-compatible and Anthropic providers.
11 Dynamic Selector	Routing among workflows with Selector and EmptyWorkflow.
12 Workflow Compile	Inspecting and validating a static resource manifest without an API call.

PyTorch Mental Model

PyTorch mental model	OpenRath counterpart
Tensor carries data	Session carries agent state
Module composes computation	Workflow / Agent composes behavior
device controls placement	Backend controls execution placement
Parameter persists state	Memory persists agent knowledge
callable module exposes a reusable interface	FlowToolCall exposes tools
ordinary control flow selects a module	Selector chooses a Workflow for Python if / while