from chirp import App

app = App()

@app.route("/")
def index():
    return "Hello, World!"

app.run()

For the smallest complete htmx loop (Page, Fragment, forms, tests), follow First Fragment App.

Live: luckycat-production.up.railway.app · Source: examples/chirpui/lucky_cat/

A simulated trading-floor UI built on server-owned signals, SSE, Suspense, and OOB swaps — no client framework. Complete tiers 1–2 first.

pip install 'bengal-chirp[ui]'
# or: uv add 'bengal-chirp[ui]'

When chirp-ui is installed, chirp check verifies that chirpui-* classes resolve to backing styles.

return "Hello"                                   # -> 200, text/html
return {"users": [...]}                          # -> 200, application/json
return Template("page.html", title="Home")        # -> 200, rendered via Kida
return Page("search.html", "results", items=x)   # -> Fragment or Template (auto)
return Fragment("page.html", "results", items=x) # -> 200, rendered block
return Stream("dashboard.html", **async_ctx)     # -> 200, streamed HTML
return Suspense("dashboard.html", stats=...)     # -> shell + OOB swaps
return EventStream(generator())                  # -> SSE stream
return hx_redirect("/dashboard")                 # -> Location + HX-Redirect
return Response(body=b"...", status=201)          # -> explicit control
return Redirect("/login")                        # -> 302

For htmx-driven form posts that should trigger full-page navigation, prefer hx_redirect() so both plain browser and htmx requests follow the redirect correctly.

Picking the wrong one is the most common return-type mistake:

Rule of thumb: initial render that streams → Suspense (or Stream for SEO-heavy sections); updates after the page loads → EventStream for page-local regions, signal() for cross-page chrome. Multi-target mutations → OOB / FormAction.

See the realtime decision tree.

{# templates/search.html #}
{% extends "base.html" %}

{% block content %}
  <input type="search" hx-get="/search" hx-target="#results" name="q">
  {% block results_list %}
    <div id="results">
      {% for item in results %}
        <div class="result">{{ item.title }}</div>
      {% end %}
    </div>
  {% endblock %}
{% endblock %}

@app.route("/search")
async def search(request: Request):
    results = await db.search(request.query.get("q", ""))
    if request.is_fragment:
        return Fragment("search.html", "results_list", results=results)
    return Template("search.html", results=results)

from chirp import Page, ValidationError
from chirp.validation import validate, required, email, max_length

@app.route("/contacts", methods=["POST"])
async def create_contact(request: Request):
    form = await request.form()
    result = validate(form, {
        "name":  [required, max_length(200)],
        "email": [required, email],
    })
    if not result:
        return ValidationError("contacts.html", "form", errors=result.errors, form=form)
    contacts.append(Contact(**result.data))
    return Page("contacts.html", "list", contacts=contacts)

ValidationError returns 422 with the re-rendered form fragment for htmx; non-htmx requests get the full page back.

@app.route("/notifications")
async def notifications(request: Request):
    async def stream():
        async for event in notification_bus.subscribe(request.user):
            yield Fragment("components/notification.html", event=event)
    return EventStream(stream())

Combined with htmx's SSE support, the server renders HTML and the browser swaps it in.

No base class. No inheritance. A middleware is anything that matches the protocol:

async def timing(request: Request, next: Next) -> Response:
    start = time.monotonic()
    response = await next(request)
    elapsed = time.monotonic() - start
    return response.with_header("X-Time", f"{elapsed:.3f}")

app.add_middleware(timing)

Built-in middleware: CORS, StaticFiles, HTMLInject, Sessions, SecurityHeaders, CSRF, Auth, and more. See Request pipeline.

app.check()                        # report and exit non-zero on errors
app.check(warnings_as_errors=True) # strict mode

Every hx-get, hx-post, and action attribute in templates is checked against the route table. Every Fragment and SSE return type is checked against available template blocks.

chirp check myapp:app --warnings-as-errors

See Contracts.

chirp dev myapp:app

Open the app in a browser and press Ctrl+Shift+D for Chirp DevTools — htmx activity, effective hx-* inheritance, render plans, EventStream traces, View Transitions, and Swap Doctor warnings.

window.ChirpHtmxDebug.help()
window.ChirpHtmxDebug.exportRecordsJson()

Synthetic benchmarks comparing Chirp, FastAPI, Flask, Starlette, and Litestar:

uv sync --extra benchmark
uv run poe benchmark

See benchmarks/README.md for caveats and runners.