# lauren

> A metadata-first, high-performance Python web framework for building production ASGI services. Inspired by Rust's Axum, NestJS, and FastAPI. Every route, DI binding, module boundary, lifecycle hook, WebSocket gateway, and exception handler is declared with decorators and resolved into an immutable execution graph at startup — the request path is pure traversal.

Targets Python 3.11+. Zero runtime magic: what you declare is what you get.

## Core pillars

- **Radix-tree router** with O(depth) lookup, static > param > wildcard priority, per-method dispatch with `Allow` header on 405.
- **Dependency Injection** with `SINGLETON`, `REQUEST`, and `TRANSIENT` scopes, Protocol binding, multi-bindings (`list[T]` injection), circular detection, scope-violation checks, and the four NestJS-style custom-provider recipes (`use_value`, `use_class`, `use_factory`, `use_existing`) plus `Token` and `Inject`.
- **Extractor system** for typed request decomposition (`Path[int]`, `Query[str]`, `Header[str]`, `Cookie[str]`, `Json[Model]`, `Form[Model]`, `Bytes`, `State`, `Depends[T]`, plus user-defined extractors via `ExtractionMarker`). `ExecutionContext` is also injectable without a marker.
- **Module system** with explicit imports/exports and circular-import detection (NestJS-style).
- **Lifecycle hooks** (`@post_construct`, `@pre_destruct`) run in topological order with timeouts.
- **First-class WebSockets** — `@ws_controller(path)`, `@on_connect`, `@on_message("event")`, `@on_disconnect`, `@on_error`, with typed Pydantic-validated frames and `BroadcastGroup` rooms.
- **Server-Sent Events** — `EventStream`, `ServerSentEvent`, `last_event_id`. Per the HTML living standard. Optional keep-alive heartbeats.
- **Typed streaming** — `StreamingResponse[T]` content-negotiates between SSE / NDJSON / JSON Lines.
- **Socket.IO compatibility** — Engine.IO v4 / Socket.IO v5 adapter.
- **ASGI runtime** with `LaurenFactory.create()` seven-phase startup, lifespan protocol, graceful drain.
- **OpenAPI 3.1** generation from Pydantic models; Swagger UI / ReDoc-ready.
- **Middleware (onion)**, **Guards**, **Interceptors**, and **Exception Handlers** — all attachable globally, per-controller, or per-route.
- **Sync handler offload**: synchronous handlers automatically run in an `anyio` thread pool.
- **Background tasks** — fire-and-forget via `BackgroundTasks` extractor; participates in graceful shutdown drain.
- **Auto-serialization**: return dicts, Pydantic models, dataclasses, or `(body, status)` tuples.
- **Strict inheritance**: subclasses must explicitly re-decorate to take on a framework role.
- **28-class error catalog** with stable `code` strings; consistent `{error: {code, message, detail}}` envelope.

## Companion packages

- **lauren-middlewares** — CORS, rate limit, GZip, security headers, request id, trusted hosts, request log, HTTPS redirect, body size limit, timeout.
- **lauren-logging** — Configurable logging module. Three `@classmethod` presets: `LoggingConfig.for_development()`, `LoggingConfig.for_production(backend)`, `LoggingConfig.for_testing()`.
- **lauren-guards** — Authentication and authorization guards: `bearer_token`, `jwt_bearer`, `api_key`, `basic_auth`, `oauth2_introspection`, `session_cookie`, `require_authenticated`, `require_roles`, `require_scopes`, `csrf`, `ip_allowlist`.

## Documentation for LLMs

- Full API reference: https://raw.githubusercontent.com/lauren-framework/lauren-framework/main/lauren/llms-full.txt
- Short overview: https://raw.githubusercontent.com/lauren-framework/lauren-framework/main/llms.txt
- Agent instructions: https://raw.githubusercontent.com/lauren-framework/lauren-framework/main/AGENTS.md
- Skills: https://github.com/lauren-framework/lauren-framework/tree/main/skills/