Chassis documentation¶
Rendered at https://andreolli-davide.github.io/chassis/.
Current release: 0.9.1. Install it from PyPI or inspect the GitHub Release.
New here? Start with getting-started.md, then use the guides below for task-oriented detail.
| Document | Read it for |
|---|---|
| getting-started.md | install, the smallest useful app, where to go next |
| why-generations.md | the problem immutable generations solve, and what it costs |
| lifecycle.md | ownership, scopes, plugin lifecycle, generations, safe unload, shutdown |
| scopes.md | composition scopes: hierarchy, inheritance, narrow views, provenance, explain and diff |
| agent-composition.md | AgentSpec, agent revisions, materialization, pinning, retirement, agent diagnostics |
| incremental-composition.md | semantic identity, impact analysis, structural sharing, reachability, reuse diagnostics |
| plugin-author-guide.md | writing, testing, and shipping a plugin |
| langgraph.md | agent definitions, the run context, graph caching, tools, streaming, interrupts |
| recipes.md | behind a web service, per-tenant composition, hot provider swap, budgets, durability |
| troubleshooting.md | symptom → cause → fix, with the exact diagnostics output |
| performance.md | benchmark methodology, the 0.9.0 baseline, capacity, and known scaling limits |
| roadmap.md | ordered 0.5.1–1.0 plan, acceptance criteria, release gates, and finding traceability |
| compatibility.md | surface classes, the API baseline and compatibility check, deprecations, persisted format versions |
| production-readiness.md | the 0.9.0 compatibility and operational review: domains, validation matrix, audit resolutions, limitations |
| observability.md | tracing, snapshots, canonical hashing, redaction, evaluation |
| security.md | trust model, policy, secrets, and what Chassis is not |
| replay.md | record/replay boundaries and their explicit limitations |
| configuration.md | declarative configuration, the catalog, reconciliation, drift |
| planning.md | the machine-readable planning contract and the zero-mutation preview |
| design.md | guarantees, decisions, and deliberate absences |
| migration.md | every compatibility change from 0.1 through the current release and how to migrate |
Examples¶
| Example | Shows |
|---|---|
| examples/production_reference/ | the production reference application: one support-desk system composing configuration, catalog, scopes, AgentSpec, policy, secrets, invoke and streaming, replay, hot replacement with pinned runs, planning, diagnostics, rollback, and graceful shutdown |
| examples/quickstart.py | the smallest useful app: a model capability, one LangGraph agent, generation attribution |
| examples/basic_agent.py | a LangGraph agent: model capability, tools, checkpointer, streaming, tracing, interrupt/resume, snapshot |
| examples/reactive_cascade.py | database → memory → agent extension, removed and restored |
| examples/safe_provider_replacement.py | an active run keeping its generation across a provider swap |
| examples/scoped_composition.py | hierarchical scopes: inheritance, sibling isolation, capability narrowing, provenance, diff, pinned runs |
| examples/agent_composition.py | three versioned agents: materialization, narrowing, revision pinning, incremental reuse, retirement |
All six execute their own assertions, so running them is the verification:
uv run python examples/quickstart.py
uv run python examples/basic_agent.py
uv run python examples/reactive_cascade.py
uv run python examples/safe_provider_replacement.py
uv run python examples/scoped_composition.py
uv run python examples/agent_composition.py
The core proposition¶
Chassis allows agent runtime composition to change over time while active runs retain a coherent environment, dependencies react correctly, resources have explicit ownership, and obsolete components are disposed only when they are no longer reachable.