Tenchi

A contract-first Python framework for humans and agents.

Build Python backends that you and your agent can understand, change, and verify. Tenchi keeps contracts at the boundary, behavior in plain async functions, and dependency wiring explicit. Its development tools help you inspect a feature, preview a change, and review the resulting evidence.

Choose a path

StartBuild your first appCreate an application, call its API, follow one request through the code, and make a behavior change.LearnUnderstand the modelLearn how contracts, routes, use cases, ports, contexts, and adapters fit together.DevelopMake a reviewable changeInspect, preview, implement, and verify with the same workflow for people and agents.

Start with a running API

shell

uvx tenchi new my_app
cd my_app
uv sync
uv run tenchi dev

Call the generated todos API from another terminal:

shell

curl -i \
  -H 'content-type: application/json' \
  -d '{"title":"Buy milk"}' \
  http://127.0.0.1:8000/todos

The generated application includes a working feature, SQLite persistence, direct use-case tests, HTTP tests, and Swagger UI at http://127.0.0.1:8000/docs. It also includes AGENTS.md, project-local MCP configuration, and a tenchi.toml verification policy for the development workflow.

One small application model

text

validated input -> contract + route -> async use case -> app-owned port -> adapter

A contract declares an HTTP operation and its validated data.
A route binds that contract to a plain async use case.
The use case owns behavior without depending on Starlette or a database implementation.
An application-owned context supplies ports and verified identity.
Adapters implement those ports for SQLite, another database, an external API, or a focused test.

Tenchi checks the route and use-case signature when the application is composed. At runtime, it validates input before the use case and validates the result before the request scope commits.

Read How Tenchi works for the complete mental model or Build a feature to carry a new operation through persistence and tests.

Understand, change, and verify

Step	What you do
Understand	Run `tenchi map --feature <name>` and read the source and tests it identifies
Specify	Declare inputs, outputs, and errors in the contract
Preview	Use `tenchi make ... --dry-run` to review files and wiring steps
Implement	Write the use case and meaningful tests; compose dependencies explicitly
Check	Run `tenchi check` for formatting, lint, types, tests, architecture, and snapshot drift
Review	Compare compatibility before accepting snapshots, then run `tenchi verify --base-ref <historical-ref>` and review its receipt with the diff

verify compares with a committed baseline from before the change. Its receipt reports the configured checks and compatibility evidence. A change plan can also verify generated structure and planned-test execution; neither result establishes business correctness or the quality of test assertions.

Follow the development workflow directly or give it to an agent. Structured CLI results and the agent MCP server expose the same inspection, preview, and verification operations without requiring a particular agent vendor. The CLI reference lists the commands.

Add capabilities when the application needs them

The same use-case model supports more than HTTP, but those capabilities are optional:

Build the core API with declared errors, authentication, pagination, OpenAPI, and a typed Python client.
Prepare for production with explicit transactions, idempotency, retries, observability, preflight, and deployment decisions.
Run behavior outside HTTP from workers, jobs, tasks, scripts, or application tools.
Add AI capabilities when the application needs model calls, machine-facing tools, an application MCP endpoint, or evaluations.

Pre-1.0 software

Minor releases can still change Tenchi's public API. Read stability and releases before adopting it for a long-lived service.