OpenRath
A Session-first Python runtime for traceable multi-agent, multi-session workflows.
Per-dimension scores and reasoning
Evidence shows: README describes production-mode permission controls (e.g., tokens carry explicit action grants, tenant/project scoping, policy checks, secret references, trust labels, audit), but lacks implementation details or configuration examples. User confirmation mechanisms (e.g., NEEDS_REVIEW interrupts) are mentioned but not detailed. Data flow transparency: Session and lineage concepts provide traceability, but no actual data flow diagrams or logs are shown. Sensitive data handling: only secret references mentioned, no encryption or masking. Dependency security: dependencies listed in pyproject.toml but no vulnerability scanning or lock file review (uv.lock exists but not examined). External effects: Effect Ledger and idempotency keys mentioned but not implemented. Rollback: checkpoints and resumable queues mentioned but no rollback mechanism. Source attribution: README and LICENSE provide copyright, but publisher unverified. Deductions: most security features are asserted without evidence, and publisher identity unknown.
Evidence shows: API descriptions in README and pyproject.toml are consistent; test_public_surface.py verifies sync public API, indicating good internal consistency. Dependencies are clearly listed, and CI workflows for build and lint are configured, but no dependency availability tests. Failure messages: NEEDS_REVIEW state mentioned but no error handling examples. Deductions: specific failure message formats and error handling strategies not shown.
Evidence shows: README clearly describes multiple use cases (single-agent, multi-agent, multi-session, etc.) with example code and directory, indicating good audience and scenario coverage. Capability boundaries: distinguishes FlowToolCall and BackendTool, and explains pluggable sandbox and memory backends. Trigger precision: Selector and workflow triggers described but not detailed. Environment fit: supports local, OpenSandbox, OpenViking backends, and environment variable configuration. Deductions: trigger precision and some environment configuration details insufficient.
Evidence shows: README structure is clear, with installation, examples, and docs links, good information architecture. Install notes are detailed, including pip and optional dependencies. Naming stability: v2.0.0 mentioned as production version but no naming conventions or API stability statement. Examples and FAQ: 12 examples provided but no FAQ. Known limitations: Agent Server HTTP surface is Beta, but other limitations not listed. License: BSD-3-Clause, compliant. Versioning and changelog: v2.0.0 mentioned but no CHANGELOG. Maintenance responsibility: GitHub links provided but no explicit maintainers. Deductions: missing FAQ, CHANGELOG, and explicit maintainer info.
Evidence shows: README provides multiple examples, output is Session object, easy to use. Marginal value: OpenRath offers unique multi-agent multi-session paradigm, potentially high value. Cost-benefit: README mentions context reuse and token reduction but no benchmarks. Deductions: cost-benefit lacks data support.
Evidence shows: Claims in README (e.g., production features) lack implementation or test evidence. Cross-source corroboration: README cites arXiv paper and docs site but no other independent sources. Fact-inference separation: design philosophy and features are mixed, not clearly separated. Deductions: claims lack traceability and independent verification.
- Publisher identity is unverified; treat with caution.
- Security features (e.g., permission controls, audit) are asserted in README but lack implementation details; further code review needed.
- Dependency security lacks vulnerability scanning or lock file review; consider checking uv.lock and dependency versions.
- Missing FAQ, CHANGELOG, and explicit maintainer info may affect long-term maintenance.
What does this agent do, and when should you use it?
OpenRath is a PyTorch-like Python framework and runtime for multi-agent, multi-session applications built around `Session`. A Session carries ordered chunks, sandbox placement, lineage, token usage, and pending lazy work, while Agent, Workflow, Tool, Memory, and Selector operate on that shared value. Workflows implement `forward(session) -> session`, can be nested, and can fork, merge, compress, or route session branches. Version 2.0.0 adds a production execution layer in which `@step` and `@router` boundaries compile into immutable plans and durable Runs use checkpoints, leases, effects, and interrupts. PostgreSQL is the documented durable source of truth, with optional Redis signaling and S3-compatible artifact storage; the Agent Server HTTP surface is Beta.
An application creates a Session with Session.from_user_message(...) and can bind its execution placement using session.to("local", spec="./"). A flow.Agent applies its prompt, Provider, optional FlowToolCall tools, and optional Memory to the session; model-visible JSON schemas and Python tool behavior live together, and tools execute against the bound Sandbox. A flow.Workflow can invoke agents, child workflows, flow.Compressor, or flow.Selector, then returns a new Session. Sessions can fork(), detach(), merge(...), and export JSONL; memory can be written, recalled, and committed with remember_memory(...), recall_memory(...), and commit_memory(...). In production mode, plans, Runs, Events, Checkpoints, an Effect Ledger, leases, and durable Interrupts support retries, cancellation, deadlines, and resumable execution.
- A Python team coordinating specialist roles on a complex request can use Session lineage to trace which branch, role, tool call, and workspace produced an output.
- An application developer evaluating several solution paths can fork sessions, merge compatible branches, and use
flow.Compressorto reduce the resulting context. - An automation engineer who needs a model to use filesystem, shell, or code tools in a defined workspace can place the Session on the
localor optionalopensandboxbackend. - A product team that wants an agent to retain useful facts between runs can bind
memory="local", recall relevant entries before a run, and commit the transcript afterward. - An operations team running long-lived workflows can use the production profile with PostgreSQL, leases, checkpoints, effect handling, and human approval interrupts.
What are this agent's strengths and limitations?
- Session is a first-class runtime value with structured chunks, placement, lineage, and usage, rather than only an opaque chat history.
- The common
Session -> Sessioninterface lets agents and workflows compose, whileflow.Selectorkeeps runtime routing inside ordinary Python control flow. FlowToolCallcombines the schema exposed to the model with the Python behavior that runs against a Session, and stdio MCP tools can be adapted into that abstraction.- The v2 production model explicitly covers immutable plans, checkpoints, leases, fencing, effect tracking, and durable human interrupts.
- The base local memory backend has no dependencies and supports BM25 recall; the documented Provider variation keeps Session and Workflow code stable across model vendors.
- Most model examples require OpenAI-compatible environment variables or a configured Provider; the supplied material does not document a complete model-free Agent execution path.
- Production deployment adds infrastructure requirements: PostgreSQL is the durable store, while Redis and S3-compatible storage serve operational roles.
- The Agent Server HTTP interface is explicitly Beta, and v1 JSONL imports are historical records rather than resumable active Runs.
- Synchronous steps cannot declare a preemptive timeout; enforcing a deadline requires an async step or an isolated executor.
- The local Sandbox runs filesystem, command, and code tools in the bound host workspace, so adopters must assess that execution boundary.
How do you install or deploy this agent?
Base install:
pip install openrathOptional integrations:
pip install "openrath[opensandbox]"
pip install "openrath[openviking]"Most model examples require OpenAI-compatible credentials:
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-gateway/v1
export OPENAI_DEFAULT_MODEL=your-model-nameA Provider can also be configured in ~/.openrath/config.json; environment variables take precedence. For the production profile, install pip install "openrath[server,postgres]" and run openrath-migrate.
How do you use this agent?
After configuring credentials, start with:
python example/01_hello_agent.pyThe basic flow is to construct a flow.Agent, create Session.from_user_message(...), and invoke agent(session). For composition, subclass flow.Workflow and implement def forward(self, session: Session) -> Session:. The documented production setup is:
runtime = LocalRuntime(store, effect_ledger=ledger, production_mode=True)
server = AgentServer(store, runtime, auth=auth, audit_sink=audit)How does this agent compare with similar options?
OpenRath frames its design through PyTorch analogies: Session maps to Tensor, Sandbox/Backend to Device, Memory to Parameter, Tool to Function, Agent to nn.Linear, and Workflow to nn.Module. It also documents local and OpenSandbox execution backends, plus local and OpenViking memory backends.
FAQ
Is OpenRath limited to OpenAI models?
Provider while Session and Workflow code remains stable.Can I evaluate it without a model API key?
How are ambiguous side effects handled after a failure?
NEEDS_REVIEW instead of being replayed blindly.