Tenchi

Build typed Python APIs around explicit contracts and plain async functions.

Tenchi validates data at the boundary, keeps behavior independent of HTTP, and leaves infrastructure choices to your application.

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.Look upFind a public APIBrowse Tenchi's Python modules and the focused guides for each capability.

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.

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.

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.
Build with AI when the application needs coding-agent workflows, machine-facing tools, MCP, or evaluations.

You can ignore those guides until the corresponding need appears. They extend the same contracts, use cases, ports, and explicit wiring rather than adding a second architecture.

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.