Tenchi

A contract-first, Python-native framework for typed JSON APIs and AI-facing tools that stay coherent as they grow.

Tenchi gives the HTTP boundary, application tools, use cases, a typed Python client, OpenAPI, compatibility checks, and structural tooling one shared model. Contracts describe what crosses the wire. Plain async functions own behavior. Protocols and frozen dataclasses keep dependencies explicit.

Start an application

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

The generated application includes a working todos feature, SQLite runtime persistence, a memory test adapter, Swagger UI, strict Pyright configuration, OpenAPI and application-tool snapshots, an agent guide, and CI. The quickstart follows its first development loop.

What makes it different

• The contract is executable. The server validates requests and responses, the client validates both sides of the call, and OpenAPI is derived from the same declaration.
• Application code stays ordinary. Use cases are plain async functions; ports are typing.Protocol; contexts are frozen dataclasses.
• API changes are reviewable. Canonical snapshots and conservative compatibility analysis distinguish additive, breaking, metadata-only, and unknown changes.
• Architecture is explicit. tenchi doctor checks dependency direction without introducing a dependency-injection container or framework base classes.
• Tooling is agent-readable. Versioned maps, mutation previews, structured diagnostics, and one complete check command give coding agents the same evidence used by people and CI.
• HTTP is one entrypoint. Workers and scripts can execute the same use cases with the same request validation and context-scoping guarantees.
• AI tools reuse application behavior. Typed tool declarations add deterministic schemas, declared errors, and safety metadata around ordinary use cases without choosing a model provider or agent loop.
• AI behavior has an explicit gate. Typed evaluation cases, metric thresholds, timeouts, and token or cost budgets turn application-owned model behavior into a payload-safe release decision.

One declaration, several guarantees

from pydantic import BaseModel, Field
from tenchi.contracts import contract


class CreateTodo(BaseModel):
    title: str = Field(min_length=1)


class Todo(BaseModel):
    id: str
    title: str
    completed: bool


create_todo_contract = contract(
    method="POST",
    path="/todos",
    request=CreateTodo,
    response=Todo,
    status=201,
)

That value can be bound to a use case, called through the typed client, served as OpenAPI 3.1, and compared against a previous release.

Read next

• Quickstart creates and changes a complete application.
• Add Tenchi to an existing project builds the first operation without using the application generator.
• Mental model defines the small vocabulary used by the framework.
• Contracts covers the complete HTTP declaration.
• Production handbook covers configuration, transactions, retries, background work, observability, and deployment.
• Signed webhooks verifies provider deliveries before parsing and makes redeliveries safe.
• Rate limiting applies authenticated operation quotas without coupling use cases to Redis, a database, or an API gateway.
• Coding agents defines the inspect, preview, edit, and validate protocol for automated changes.
• Application tools exposes existing use cases to AI and machine callers through a validated, transport-neutral boundary.
• Application MCP publishes those tools with authenticated discovery, explicit approval for destructive calls, and structured results.
• AI evaluations gates application-owned model behavior without choosing a provider, prompt system, judge, or dataset store.
• Comparisons explains where Tenchi fits and where it does not.