Module reference

Tenchi's supported Python modules each own one small responsibility. Import from the module that owns a declaration when you want its full API, or use the selected package-root re-exports for compact application code.

Package-root imports

tenchi re-exports the declarations most applications use:

python

from tenchi import (
    IDEMPOTENCY_CONFLICT,
    IDEMPOTENCY_IN_PROGRESS,
    TOOL_MANIFEST_VERSION,
    AppError,
    Client,
    ClientAttemptObserver,
    ClientAttemptOutcome,
    ClientObserver,
    ClientOutcome,
    ErrorDef,
    IdempotencyResultError,
    IdempotencyStore,
    IdempotencyStoreError,
    Job,
    JobDispatcher,
    JobMessage,
    Page,
    PageQuery,
    PreflightGroup,
    RATE_LIMITED,
    MemoryRateLimitStore,
    RateLimitStore,
    RetryPolicy,
    RetryTimeoutError,
    Tool,
    ToolRunner,
    UseCaseObserver,
    UseCaseOutcome,
    Webhook,
    WebhookRequest,
    contract,
    create_app,
    create_job_dispatcher,
    create_task_runner,
    create_tool_runner,
    execute,
    enforce_rate_limit,
    fingerprint,
    health_route,
    job,
    job_group,
    job_handler,
    job_message,
    openapi_route,
    page,
    preflight_check,
    preflight_group,
    present,
    response,
    retry_policy,
    route,
    route_group,
    run_idempotently,
    swagger_ui_route,
    task,
    task_group,
    tool,
    tool_group,
    tool_handler,
    tool_manifest,
    webhook,
)

Canonical examples use the owning submodule when that makes the responsibility clearer.

Core declarations

Module	Public names
`tenchi.contracts`	`Contract`, `contract()`
`tenchi.routes`	`Route`, `RouteGroup`, `RouteBindingError`, `UseCase`, `route()`, `route_group()`
`tenchi.responses`	`ResponseDef`, `PresentedResponse`, `response()`, `present()`
`tenchi.errors`	`ErrorDef`, `AppError`, `TenchiError`, `ConfigurationError`, `ERROR_SOURCE_HEADER`, `REQUEST_ID_HEADER`, `error_body()`

Contracts describe HTTP. Routes bind contracts to use cases. Response definitions describe successful wire outcomes. Error definitions describe expected application failures.

Runtime

Module	Public names
`tenchi.server`	`create_app()`, `RequestInfo`, `RequestOutcome`, `Hook`, `OutcomeObserver`, `ContextFactory`, `Lifespan`, `DEFAULT_MAX_REQUEST_BYTES`, `ERROR_SOURCE_HEADER`, `REQUEST_ID_HEADER`
`tenchi.execution`	`execute()`, `open_context()`, `ExecutionError`, `UseCaseOutcome`, `UseCaseObserver`
`tenchi.idempotency`	`IdempotencyStore`, `IdempotencyReservation`, `IdempotencyReplay`, `IdempotencyConflict`, `IdempotencyInProgress`, `IdempotencyDecision`, `IdempotencyResultError`, `IdempotencyStoreError`, `MemoryIdempotencyStore`, `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_IN_PROGRESS`, `fingerprint()`, `run_idempotently()`
`tenchi.jobs`	`Job`, `JobMessage`, `JobHandler`, `JobGroup`, `JobDispatcher`, `JobBindingError`, `JobNotFoundError`, `JobResultError`, `job()`, `job_message()`, `job_handler()`, `job_group()`, `create_job_dispatcher()`
`tenchi.preflight`	`PreflightCheck`, `PreflightGroup`, `PreflightOutcome`, `PreflightReport`, `PreflightStatus`, `PreflightBindingError`, `preflight_check()`, `preflight_group()`, `run_preflight()`
`tenchi.rate_limits`	`RateLimitStore`, `RateLimitPermit`, `RateLimitExceeded`, `RateLimitDecision`, `RateLimitStoreError`, `MemoryRateLimitStore`, `RATE_LIMITED`, `enforce_rate_limit()`
`tenchi.tasks`	`Task`, `TaskGroup`, `TaskRunner`, `task()`, `task_group()`, `create_task_runner()`
`tenchi.tools`	`TOOL_MANIFEST_VERSION`, `Tool`, `ToolBinding`, `ToolGroup`, `ToolRunner`, `ToolBindingError`, `ToolNotFoundError`, `ToolResultError`, `ToolInvocationError`, `tool()`, `tool_handler()`, `tool_group()`, `create_tool_runner()`, `tool_manifest()`
`tenchi.webhooks`	`Webhook`, `WebhookRequest`, `WebhookVerifier`, `WebhookBindingError`, `webhook()`
`tenchi.client`	`Client`, `ClientResponse`, `ClientOutcome`, `ClientObserver`, `ClientAttemptOutcome`, `ClientAttemptObserver`, `UnexpectedResponseError`
`tenchi.retries`	`RetryPolicy`, `RetryTimeoutError`, `retry_policy()`
`tenchi.testing`	`open_client()`, `open_http()`, `verify_idempotency_store()`, `verify_rate_limit_store()`, `StoreConformanceError`, `IdempotencyStoreFactory`, `RateLimitStoreFactory`, `ClockAdvance`, `ASGIApp`

create_app() owns HTTP dispatch and lifecycle composition. execute() runs the application boundary without HTTP. A preflight group defines read-only, timeout-bounded observations for a deployment gate. A TaskRunner adds stable discovery, input and result validation, and application lifecycle wiring for operational commands. Client enforces contracts against remote or in-process servers; an explicit RetryPolicy coordinates bounded logical retries. A JobDispatcher validates durable messages and their registered consumer results without owning a queue. A Webhook binds an exact-body verifier to a contract marked webhook=True. A RateLimitStore atomically applies fixed-window application quotas. An application ToolRunner validates machine-facing calls, applies lifecycle and context wiring, and masks undeclared failures. tool_manifest() exposes portable JSON Schemas and safety metadata without choosing an agent transport.

Optional integrations

Module	Public names	Install
`tenchi.mcp`	`TOOL_MCP_PROTOCOL_VERSION`, `McpRequest`, `create_tool_mcp_server()`	`uv add "tenchi[mcp]"`
`tenchi.opentelemetry`	`OpenTelemetryObservers`, `create_opentelemetry_observers()`	`uv add "tenchi[otel]"`

The MCP module exposes an authenticated ToolGroup through the MCP SDK while the application owns identity, visibility, approval policy, and runner wiring. The OpenTelemetry module records through application-configured providers. It does not create an SDK, exporter, background worker, or shutdown lifecycle.

Schema and operations

Module	Public names
`tenchi.openapi`	`openapi_schema()`, `openapi_route()`, `swagger_ui_route()`
`tenchi.compatibility`	`CompatibilityChange`, `CompatibilityReport`, `analyze_openapi_compatibility()`, `analyze_tool_compatibility()`, and their report renderers
`tenchi.pagination`	`Page`, `PageQuery`, `page()`
`tenchi.health`	`HealthCheck`, `HealthReport`, `health_route()`

Use the tenchi CLI for scaffolding, application inspection, architecture diagnostics, project checks, verification receipts, and OpenAPI and application-tool snapshots. Modules such as tenchi.cli, tenchi.doctor, tenchi.scaffold, and tenchi.snapshots implement that command surface; they are not supported application imports.

Exact signatures

Tenchi ships inline type information and is checked with strict Pyright. Use editor completion for overloads and parameter types, or inspect the supported module source on GitHub.

Pre-1.0 releases may change these APIs between minor versions. Follow the safe upgrade workflow before updating an application.