One template. Every interaction. Checked before deploy.
Chirp is the hypermedia-native Python framework for server-rendered product UIs.
Routes return typed template responses. Chirp reuses one template's named blocks
for pages, htmx fragments, streaming HTML, and live SSE updates. chirp check
catches broken routes, blocks, and targets before users find them.
Build the app on the server without maintaining a parallel SPA, a second set of
partials, or a JavaScript build pipeline. Install as bengal-chirp, import as
chirp. Python 3.14+ required.
Server-rendered applications often split a single interaction across page templates, fragment templates, browser conventions, and test-only assumptions. That makes a small UI change hard to reason about: which template owns the state, which route returns it, and which browser target receives it?
Chirp keeps those declarations together. A route's return type says what the interaction needs; named blocks give that response a precise render target; the compiler checks the wiring. The result is a live ASGI app that stays legible as it gains forms, streaming, and realtime updates.
pip install 'bengal-chirp[ui]'
chirp new myapp && cd myapp
python app.py # http://127.0.0.1:8000
chirp check myapp:app # validate hypermedia wiring[ui] is optional, but recommended for new projects: chirp new emits
chirp-ui layouts. No npm or build step.
For the smallest complete htmx loop, follow
First Fragment App.
from chirp import App, Page, Request
app = App()
@app.route("/search")
async def search(request: Request):
results = await db.search(request.query.get("q", ""))
return Page("search.html", "results", results=results)
# Navigation renders the page; htmx gets the named "results" block.Page names the template and block. Chirp uses the same return model for pages,
fragments, streams, and events. See the full
return-value reference
for every render surface.
Run chirp check in development and CI. It diagnoses missing routes, template
blocks, fragment targets, and incompatible hypermedia declarations. Runtime
transition traces and tests use the same compiled model. The primary output is a
live ASGI application; chirp freeze is an optional static projection for
compatible routes.
Read the hypermedia compiler architecture for the foundation, and the tested Full-Application Journey for database, mutation, validation, boosted navigation, SSE, diagnostics, and optional-export proof.
Chirp includes routing, templates, forms, validation, sessions, auth helpers, streaming HTML, SSE, static files, security middleware, and testing tools. Shapes provides database access, with an optional in-tree PostgreSQL driver.
Use it for server-owned product UIs: dashboards, back-office workflows, customer
portals, collaborative tools, and apps where HTML is the useful unit of work.
JSON routes and explicit Response objects remain available when that is the
right boundary. Background jobs, admin UIs, and email delivery integrate at the
seams; see Non-goals.
The framework's useful constraints are deliberate:
| Need | Chirp approach |
|---|---|
| A full page and a small update | One template with named blocks |
| Slow initial sections | Stream or Suspense |
| Updates after load | EventStream or signals |
| Form errors | Typed validation result re-renders the relevant block |
| Confidence before deploy | chirp check --warnings-as-errors |
| I want to… | Start here |
|---|---|
| Learn the model | Learning path · Get Started |
| Build features | Build Apps |
| Understand returns and blocks | Core concepts |
| Debug contracts and deploy | Quality & Operations |
| Run examples | Examples index |
| Compare stacks or check scope | When to use Chirp · Non-goals |
Start with the tiered examples in order: basics, an app shell, then the capstone.
Most applications need App, @app.route, Template, Page, forms,
ValidationError, and chirp check before they need signals or streaming.
The chirp command can scaffold, run, inspect, and validate an application.
chirp new <name> --shell starts with a persistent app shell; --stream,
--sse, --ai, and --skill add focused examples of those patterns. chirp dev <app>
starts the development server with Chirp DevTools; chirp routes <app> prints
the route table; chirp check <app> --coverage shows contract coverage.
The core package stays small. Add only the extras you use: [forms] for
multipart parsing, [sessions], [auth], and [passkeys] for identity work,
[skill] for signed skill envelopes (cryptography), [ai] for LLM
streaming, [data-pg] for PostgreSQL, [testing] for an httpx transport,
[redis] for Redis-backed sessions and rate limiting, or [markdown] for
Patitas and Rosettes. When chirp-ui is installed, chirp check also verifies
that chirpui-* classes resolve to backing styles.
Chirp apps run on Pounce, an ASGI server with HTTP/2, graceful shutdown, Prometheus metrics, rate limiting, and multi-worker scaling. Validate both layers before deployment:
chirp check myapp:app --warnings-as-errors
pounce check --app myapp:appFollow the production deployment guide for deployment posture and caveats. Framework-owned paths have free-threading coverage under Python 3.14t; application globals and optional integrations need their own synchronization proof.
Synthetic comparisons are available in the committed baseline. They describe only the captured environment. They do not promise production capacity or universal performance. The machine-checked claims ledger governs public positioning.
Chirp supports RFC 10008 QUERY on explicit ASGI routes for controlled
early-adopter use. Use it only when a read-only query is too large or structured
for a practical URI; bookmarkable searches and native HTML forms should stay GET.
The route declares accepted media types while the handler keeps Chirp's normal
typed HTML returns and one-template/named-block render surface.
Keep a GET fallback and verify the exact deployment path. Browser, Pounce,
Uvicorn, and Nginx proof exists, but stable promotion and universal proxy/CDN support are not claimed.
See the HTTP QUERY adoption guide for compatibility evidence and release gates.
Deploy a ready-to-run example on Railway: Forum, Feedback Board, Changelog, Launch Board, or Hookbox.
Chirp is alpha. Its core model is ready to build with; APIs, scaffolds, and the surrounding toolchain can still change. Check the Public API, reference, and changelog before upgrading.
Chirp is the web framework in the Bengal ecosystem: Bengal builds static sites; Purr provides content runtime; chirp-ui is the optional companion UI layer; Pounce serves ASGI; Kida renders templates; Patitas parses Markdown; and Rosettes highlights syntax.
MIT