Declare the application once

The route below gets compiled binding, bounded fields, native JSON, replay-safe writes, request IDs, security headers and an OpenAPI operation from the same declarations.

from dataclasses import dataclass
from typing import Annotated

from wreath import Request, Wreath
from wreath.binding import Body, Field
from wreath.policy import HttpPolicy, IdempotencyPolicy
from wreath.policy.request_id import RequestIdPolicy
from wreath.policy.security import SecurityHeadersPolicy


@dataclass
class RunRequest:
    prompt: Annotated[str, Field(min_length=3, max_length=2_000)]
    model: Annotated[str, Field(min_length=2, max_length=80)]


app = Wreath(
    http_policy=HttpPolicy(
        idempotency=IdempotencyPolicy(),
        request_id=RequestIdPolicy(),
        security_headers=SecurityHeadersPolicy(),
    )
)


@app.post("/runs")
async def create_run(
    request: Request,
    command: Annotated[RunRequest, Body()],
) -> dict:
    return {"state": "queued", "model": command.model, "prompt": command.prompt}


app.enable_api_docs(environments=("development",), try_it_out=True)

uv add wreath
uv run wreath dev app:app

uvicorn app:app is valid too. Choose Wreath's native server when you want its full HTTP, TLS, telemetry and flight-recording path.

One lifecycle, fewer seams

HTTP and policy

Routing, binding, middleware, security, CORS, CSRF, sessions, caching, idempotency, rate limits, OpenAPI and response delivery share one compiled application image. Wreath also makes modern HTTP useful at the declaration: QUERY, API Catalog, Link-Template, Content-Digest, Cache-Status, Cache-Groups, Deprecation, Sunset and incremental delivery.

Data and durable work

The owned PostgreSQL driver, migrations, declarative models, prepared queries, transactions, lease/fence primitives, jobs, schedules, event delivery and outbox patterns use the same startup and shutdown boundary. The data guide starts small; the migration workflow covers production changes.

Billing and subscriptions

Hosted checkout, subscriptions, portals, refunds, Stripe Connect and Managed Payments share one provider-neutral control plane. Wreath maps application plans to provider prices, projects verified webhooks into its owned ledger, derives atomic Cedar entitlements, and reconciles remote state without holding a database transaction across network I/O. Direct card capture is deliberately outside the API; deployment-owned compliance decisions remain visible instead of becoming a framework promise. See billing and subscriptions.

ChatOps

One typed command declaration can serve Slack, Microsoft Teams and Discord with no provider SDK dependency. Wreath owns ingress verification, manifests, acknowledgements and bounded delivery, then reuses the application's identity, organization, Cedar, rate-limit, durable-job, stream, notification and agent infrastructure. Existing Entra or Google-backed users can resolve through the same application identity and permission stores; profile fields never silently provision or merge accounts. See the ChatOps runtime.

Identity and operations

Bearer and cookie identity, OAuth BFF sessions, step-up authentication, SAML, SCIM, Cedar authorization, tenant boundaries, privacy work, audit evidence, metrics and forensic capture are first-class surfaces. Unsupported combinations fail when the application compiles, before they become production slow paths.

Build the part that is hard

The guides are backed by complete systems, not disconnected snippets:

• secure product API, live energy depot, and personal device fleet
• automation backplane, governed MCP control room, and enterprise control plane
• time-series laboratory, noon-drop storefront, and offline operations service

The conventional paths remain close at hand: HTTP and OpenAPI, browser applications, CLI tasks, and the production runbook.

Performance you can audit

Wreath skips request-time work by compiling stable facts at startup, crosses the Python/native boundary in batches, and moves byte-heavy work into owned native kernels. It does not treat “rewritten in C” as evidence.

Both charts come from the retained raw samples. The request includes TLS 1.3, policy and sessions, nested typed input, bearer and Cedar authorization, PostgreSQL and HTTP wire calls, temporal, geospatial and vector work, ranked pagination, protobuf, MessagePack, templates and compression. Every response is verified before a sample is accepted.

Instructions use five alternating 30/15-request slopes and an unchanged A/A control. Memory uses five separate fresh-process runs, summing the server and all descendants from /proc/<pid>/smaps_rollup; PSS apportions shared mappings while RSS counts each mapping in every process. The 2 ms process-tree scan can miss a shorter-lived peak. These are instruction and memory accounts, not elapsed-time or throughput claims.

The motion is authored with Anime.js and sampled into standalone SVG animation; the complete final frame is the fallback when a host does not animate SVG. The dependency exists only in tools/readme_charts, never in Wreath or its wheel. The benchmark guide carries the commands, equivalent-work checks, framework-specific limitations, cache counters and native gzip corpus.

Install

pip install wreath
# or
uv add wreath

uv add 'wreath[linux]'  # io_uring reactor and native TLS on Linux
uv add 'wreath[h3]'     # HTTP/3; `http3` is an alias

The base wheel includes Wreath's portable C implementation. Use the framework on any conforming ASGI server, or select the accelerated server components explicitly.

Wreath is pre-1.0. The version, platform and upgrade contract states what each release supports.

Engineering contract

Performance changes keep repeated equivalent measurements and raw evidence. Wire behavior is checked against independent implementations or standards. Unsupported declarations refuse at startup. Native code owns no process-global mutable state. Hot-path complexity and Python/native crossings have executable baselines, and behavior changes ship with focused tests.

uv sync
uv run wreath-check
uv run wreath test

The repository's AGENTS.md is the complete engineering contract.