Python module reference

Find the API for the task you are working on. Import from its submodule, such as tenchi.contracts or tenchi.testing.

The call signatures below list argument names and defaults. Types, return values, and failures are described immediately afterward. Arguments following * must be passed by name.

Declare a contract

Import contract from tenchi.contracts.

contract(
    *,
    method,
    path,
    request=None,
    params=None,
    query=None,
    headers=None,
    response=None,
    response_headers=None,
    request_examples=None,
    response_examples=None,
    status=200,
    errors=(),
    name=None,
    request_media_type="application/json",
    response_media_type="application/json",
    summary=None,
    description=None,
    tags=(),
    public=False,
    webhook=False,
    idempotency_key=False,
    deprecated=False,
    sunset=None,
    max_request_bytes=None,
    responses=(),
    timeout=None,
) -> Contract

Pass Pydantic-compatible types for request, params, query, headers, and response. Use one response for a fixed successful status, or responses for status-dependent results. errors is a sequence of ErrorDef values the operation may expose.

The returned immutable Contract describes the operation; it does not register a handler. Its response types are retained for typed client calls. Invalid declaration options raise ConfigurationError. Schema and binding checks also run when you compose routes, the server, OpenAPI, or a client call. See contract constraints.

Bind and group routes

Import route and route_group from tenchi.routes.

route(
    contract,
    use_case,
    *,
    response_headers=None,
    present=None,
) -> Route

route_group(
    *items,
    prefix="",
    errors=(),
) -> RouteGroup

use_case is an async function accepting context and every input source its contract declares. For a fixed response, its return annotation matches contract.response. response_headers projects the result into the declared header type. present selects a PresentedResponse when the contract declares multiple response definitions.

route() returns a binding and raises RouteBindingError for incompatible signatures or missing presenters and header projectors. route_group() accepts routes, groups, or sequences of routes and returns a flat immutable group. Its prefix is prepended to every path, and its errors are declared across the group. See route composition.

Create an application

Import create_app from tenchi.server.

create_app(
    *,
    routes,
    context_factory,
    lifespan=None,
    hooks=(),
    webhooks=(),
    middleware=(),
    observers=(),
    use_case_observers=(),
    max_request_bytes=1048576,
) -> starlette.applications.Starlette

routes is a RouteGroup. context_factory takes no arguments, or takes the state yielded by lifespan. It may return a context directly, an awaitable, or an async context manager. lifespan, when supplied, is a zero-argument async-context-manager factory.

The default request-body limit is 1 MiB (1048576 bytes); None disables it. A contract can override that limit with max_request_bytes. Hooks, webhook verifiers, middleware, and observers are sequences of their respective server bindings.

The return value is an ASGI application. Invalid composition, including duplicate routes or an incompatible context factory, raises ConfigurationError. Request validation errors become HTTP error responses; expected application errors must be declared on the contract or route group. Configure commit and rollback in your application context.

Call an API

Import Client from tenchi.client and use it as an async context manager.

Client(
    *,
    base_url=None,
    headers=None,
    transport=None,
    http=None,
    errors=(),
    observers=(),
    attempt_observers=(),
) -> Client

await client.call(
    contract,
    *,
    params=None,
    query=None,
    headers=None,
    request=<omitted>,
    retry=None,
) -> the contract's response type

Supply base_url for normal HTTP calls. Use transport for a custom httpx transport, or http to supply an existing httpx.AsyncClient. A supplied client remains caller-owned; do not combine it with base_url, headers, or transport. Incompatible constructor options raise ConfigurationError.

Call arguments correspond to the contract's input types. <omitted> means leave request out when there is no body; passing None supplies a value for validation. A successful call() returns the validated body. Use call_with_response() when you also need status, headers, or the selected response definition.

Invalid input can fail before network I/O. Declared application failures raise AppError; an unexpected response raises UnexpectedResponseError; transport failures retain their httpx exception types. Retries are off unless you pass a RetryPolicy. See client errors and retries.

Test with application lifespan

Import open_client or open_http from tenchi.testing.

open_client(
    app,
    *,
    headers=None,
    errors=(),
    observers=(),
    attempt_observers=(),
    base_url="http://testserver",
) -> async context manager yielding Client

open_http(
    app,
    *,
    headers=None,
    base_url="http://testserver",
) -> async context manager yielding httpx.AsyncClient

Both helpers accept an ASGI application and start and stop its lifespan. Use open_client for contract-driven assertions and open_http to inspect raw HTTP statuses, headers, and envelopes. Default requests use http://testserver; no listening HTTP server is required.

Exceptions from application startup, shutdown, or the body of the context manager propagate to the test. HTTP error responses can be inspected with open_http; open_client applies the same declared-error behavior as Client. See application testing.

Complete export index

Use this index to locate less common declarations, protocols, and exceptions. The guides above explain when to use them.

Core declarations

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

Runtime

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. An EvaluationRunner applies the same lifecycle discipline to typed, budgeted AI quality gates without choosing a model provider or judge.

Optional integrations

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

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

from tenchi import (
    EVALUATION_MANIFEST_VERSION,
    IDEMPOTENCY_CONFLICT,
    IDEMPOTENCY_IN_PROGRESS,
    JOB_MANIFEST_VERSION,
    MAX_EVALUATION_TOKENS,
    RATE_LIMITED,
    TOOL_MANIFEST_VERSION,
    AppError,
    Client,
    ClientAttemptObserver,
    ClientAttemptOutcome,
    ClientObserver,
    ClientOutcome,
    ClientResponse,
    ConfigurationError,
    Contract,
    ErrorDef,
    Evaluation,
    EvaluationBindingError,
    EvaluationBudgetOutcome,
    EvaluationBudgetStatus,
    EvaluationCase,
    EvaluationCaseOutcome,
    EvaluationCaseStatus,
    EvaluationGroup,
    EvaluationKind,
    EvaluationManifest,
    EvaluationManifestEntry,
    EvaluationMeasurement,
    EvaluationMetric,
    EvaluationMetricManifest,
    EvaluationMetricOutcome,
    EvaluationNotFoundError,
    EvaluationOutcome,
    EvaluationReport,
    EvaluationResultError,
    EvaluationRunner,
    ExecutionError,
    ExecutionInputError,
    IdempotencyResultError,
    IdempotencyStore,
    IdempotencyStoreError,
    Job,
    JobBindingError,
    JobDispatcher,
    JobGroup,
    JobHandler,
    JobManifest,
    JobManifestEntry,
    JobMessage,
    JobNotFoundError,
    JobPayloadError,
    JobResultError,
    MemoryIdempotencyStore,
    MemoryRateLimitStore,
    OutcomeObserver,
    Page,
    PageQuery,
    PreflightBindingError,
    PreflightCheck,
    PreflightGroup,
    PreflightOutcome,
    PreflightReport,
    PreflightStatus,
    PresentedResponse,
    RateLimitExceeded,
    RateLimitPermit,
    RateLimitStore,
    RateLimitStoreError,
    RequestInfo,
    RequestOutcome,
    ResponseDef,
    RetryPolicy,
    RetryTimeoutError,
    Route,
    RouteGroup,
    Task,
    TaskBindingError,
    TaskGroup,
    TaskInputError,
    TaskNotFoundError,
    TaskResultError,
    TaskRunner,
    TenchiError,
    Tool,
    ToolBinding,
    ToolBindingError,
    ToolGroup,
    ToolInvocationError,
    ToolNotFoundError,
    ToolResultError,
    ToolRunner,
    UnexpectedResponseError,
    UseCaseObserver,
    UseCaseOutcome,
    Webhook,
    WebhookBindingError,
    WebhookRequest,
    WebhookVerifier,
    __version__,
    contract,
    create_app,
    create_evaluation_runner,
    create_job_dispatcher,
    create_task_runner,
    create_tool_runner,
    execute,
    enforce_rate_limit,
    evaluation,
    evaluation_case,
    evaluation_group,
    evaluation_manifest,
    evaluation_metric,
    evaluation_result,
    fingerprint,
    health_route,
    job,
    job_group,
    job_handler,
    job_manifest,
    job_message,
    openapi_route,
    openapi_schema,
    page,
    preflight_check,
    preflight_group,
    present,
    response,
    retry_policy,
    route,
    route_group,
    run_idempotently,
    run_preflight,
    swagger_ui_route,
    task,
    task_group,
    tool,
    tool_group,
    tool_handler,
    tool_manifest,
    webhook,
)

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