# Tenchi

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

Tenchi is a contract-first Python framework for typed JSON APIs and AI-facing tools. The full extracted documentation is available at https://tenchi.io/llms-full.txt.

## Start

- [Tenchi](https://tenchi.io): A contract-first, Python-native framework for typed JSON APIs and AI-facing tools that stay coherent as they grow.
- [Quickstart](https://tenchi.io/getting-started): Create a Tenchi application, run its checks, make a contract change, and inspect the generated HTTP and OpenAPI surfaces.
- [Add to an existing project](https://tenchi.io/existing-project): Add Tenchi to an existing Python project and build the first complete contract, use case, ASGI application, test, and OpenAPI baseline.
- [Mental model](https://tenchi.io/concepts): Learn the small Tenchi vocabulary: contracts, routes, use cases, ports, contexts, hooks, policies, and adapters.
- [App architecture](https://tenchi.io/architecture): Understand where Tenchi applications place features, use cases, policies, ports, infrastructure, and server composition.
- [Comparisons](https://tenchi.io/comparisons): Compare Tenchi with FastAPI, Starlette, Litestar, and Django Ninja, including when another framework is the better choice.

## Core app model

- [Contracts](https://tenchi.io/contracts): Declare methods, paths, validated inputs, responses, headers, errors, media types, metadata, and runtime limits.
- [Use cases and ports](https://tenchi.io/application): Keep application behavior in plain async functions and infrastructure behind app-owned typing.Protocol ports.
- [Routes and server](https://tenchi.io/server): Bind contracts to use cases, compose route groups, and create an ASGI application with explicit context wiring.
- [Responses](https://tenchi.io/responses): Model fixed and status-dependent successful responses, typed headers, media types, and Starlette passthrough responses.
- [Errors](https://tenchi.io/errors): Declare stable application errors and understand Tenchi's honest server and client error semantics.
- [Typed client](https://tenchi.io/client): Call Tenchi contracts through an async httpx client with validated inputs, responses, errors, and payload-safe outcome observers.
- [Pagination](https://tenchi.io/pagination): Declare validated limit and offset queries and return typed page envelopes shared by the server, client, and OpenAPI.

## Application design

- [Authentication and authorization](https://tenchi.io/authentication): Authenticate at the HTTP boundary, authorize in use cases, and keep policies pure and reusable.
- [Workers and scripts](https://tenchi.io/execution): Run use cases outside HTTP with the same request validation and context-scoping guarantees.
- [Background jobs](https://tenchi.io/jobs): Declare stable job messages, validate producers and consumers, and dispatch through queue-neutral handlers.
- [Operational tasks](https://tenchi.io/tasks): Declare, discover, and safely run validated backfills, repairs, replays, and maintenance commands.
- [Application tools](https://tenchi.io/tools): Expose existing use cases to AI and machine callers through typed declarations, validated execution, and portable manifests.
- [Serve tools over MCP](https://tenchi.io/tool-mcp): Publish authenticated application tools over MCP with caller-specific discovery, explicit destructive-call approval, and versioned structured results.
- [Testing](https://tenchi.io/testing): Test use cases directly and exercise complete applications through lifespan-aware typed and raw in-process clients.

## Production

- [Production handbook](https://tenchi.io/production): Apply Tenchi's production patterns for configuration, transactions, concurrency, retries, background work, observability, and deployment.
- [Configuration and secrets](https://tenchi.io/configuration): Validate process configuration at startup, keep secrets out of application behavior, and wire settings at the composition root.
- [Databases and transactions](https://tenchi.io/database): Own pools with lifespan, create one unit of work per request, run migrations safely, and prevent lost updates.
- [Retry-safe operations](https://tenchi.io/idempotency): Reserve scoped keys, fingerprint validated input, and replay typed results without coupling application behavior to a database or cache.
- [Rate limiting](https://tenchi.io/rate-limits): Apply authenticated fixed-window quotas with atomic shared storage and deterministic memory-backed tests.
- [Signed webhooks](https://tenchi.io/webhooks): Verify exact request bytes before parsing, attach service identity, and make provider redeliveries idempotent.
- [Retries and background work](https://tenchi.io/reliability): Make commands safe to retry, commit deferred work through a transactional outbox, and classify worker failures.
- [Observability and audit](https://tenchi.io/observability): Export payload-safe outcomes through OpenTelemetry, instrument non-HTTP work, and keep audit records separate.
- [Deployment preflight](https://tenchi.io/preflight): Run read-only, timeout-bounded checks against the environment a release is about to use without exposing dependency details.
- [Deployment](https://tenchi.io/deployment): Prepare a Tenchi ASGI application for production with lifecycle resources, middleware, health checks, and operational safeguards.

## Tooling

- [OpenAPI and compatibility](https://tenchi.io/openapi): Generate OpenAPI 3.1, store canonical snapshots, and classify contract changes against a historical baseline.
- [CLI](https://tenchi.io/cli): Create applications, preview generated slices, map application architecture, protect API and tool snapshots, and run versioned agent-readable checks.
- [Coding agents](https://tenchi.io/agents): Use Tenchi's deterministic maps, mutation previews, structured diagnostics, and complete validation loop from a coding agent.
- [Connect a coding agent over MCP](https://tenchi.io/mcp): Connect an MCP-aware coding agent to Tenchi's application map, previews, diagnostics, compatibility report, and validation loop.

## Reference

- [Module reference](https://tenchi.io/reference): Map Tenchi's public modules to the declarations and runtime helpers each one owns.
- [Stability and releases](https://tenchi.io/stability): Understand Tenchi's pre-1.0 compatibility expectations, release process, and safe upgrade workflow.

## Optional

- [llms-full.txt](https://tenchi.io/llms-full.txt): Full text of every documentation page.
- [GitHub](https://github.com/taylorbryant/tenchi): Source code, changelog, examples, and issue tracker.