curvature 0.2.5

A web framework for code that agents maintain. The right path is free fall.

Curvature

The right path is free fall.

A web framework for code that agents maintain. Live, dynamic web apps in pure Python — single-page feel, pages that update themselves in real time, zero JavaScript app code — and a gate that makes the maintainable path the only path that builds. (Not a static-site generator: state lives on the server, and open pages stay current over a live stream.)

Curvature's design center is the maintainer nobody watches: the coding agent in its forty-third session, at 2 a.m., doing whatever the shape of the code suggests. Frameworks built for humans enforce their discipline through culture. Curvature's discipline is machine-checked — every invariant in SPEC.md names the check that enforces it, and violations are reported by curvature check as anomalies — regions where the geometry failed to steer. The canonical documentation is AGENTS.md; this README is the courtesy translation. The argument for all of it is the MANIFESTO.

The shape of it

from curvature import Element, Props, redirect, respond
from curvature import html as h


class LapProps(Props):
    title: str
    done: bool


def lap(props: LapProps) -> Element:
    return h.li(props.title, class_="lap done" if props.done else "lap", id="lap")

• Components are functions of frozen, closed pydantic props. The UI is just Python: typed by pyright, measured by coverage, tested by pytest without a browser in sight.
• The app works with JavaScript off. Reads render full pages; writes are POST → redirect → GET through real forms. Your test suite drives it with httpx — which executes no JS — so the degraded path is the tested path, permanently.
• Pages keep themselves current. Live (SSE) pushes updates into every open browser — the demo's roadmap redraws when anyone ships a card — with zero app JavaScript.
• curvature.js (the only script, held under a 150-line ratcheted ceiling) boosts working links and GET forms into fragment swaps. Mutating forms stay native, so a lost connection can never turn a POST into the wrong GET. Same route, same render, one header of difference.
• The ratchet only tightens. File ceilings fall, the coverage floor rises, and curvature ratchet is the only hand on the mechanism. The 10,000-line file is never written because week two's gate refuses the sediment while the split is still cheap.

Start from nothing

One prerequisite, one line (uv):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then:

uvx curvature new app pitstop     # no venv, no Python even — uv brings it
cd pitstop
./gate.sh                      # green before you write a line
./run.sh                       # http://127.0.0.1:8000

Only have pip? pip install curvature && python -m curvature new app pitstop — the python -m form dodges PATH entirely; the poured README carries the rest of the old ritual.

Onboarding an agent takes zero steps: the scaffold poured AGENTS.md, the gate, and one example component as the pattern. Point your agent at the directory and ask for a feature — the repo is the prompt.

The demo

PyPI ships the framework; the repo ships Pit Board, the demo:

git clone https://github.com/siliconsociety/Curvature && cd Curvature
uv sync && ./gate.sh
uv run uvicorn demo.app:app --reload --timeout-graceful-shutdown 1   # Pit Board

Then turn JavaScript off and use it again. Links, forms, redirects, and refreshes still work; only enhancement (fragment swaps and live push) disappears. That is the boundary.

Updating an app

Curvature has two ownership classes. The installed package owns the runtime, including curvature.js, Live, response helpers, and the gate. Update that runtime deliberately, review the lockfile, and run the app's gate:

uv lock --upgrade-package curvature
uv sync
./gate.sh

The app owns everything the scaffold or a satellite pour copied into its repository. Package upgrades never overwrite those files. When a release requires an app-source migration, its upgrade note names the files and the owner applies the diff like any other code change. See docs/UPGRADING.md for the complete contract and release-specific notes.

Status

Alpha. The contract, runtime, gate, demo, browser-level boost tests, and a fresh-pour Auth integration suite are real and self-hosting. Production readiness is earned by the gate and deployment checks, not asserted by the version label. The spec is versioned and arguable; argue by issue.

MIT. Built by Robert Sharp, with Claude Fable 5 on its last day on the subscription — read the manifesto and you'll see why that detail belongs in a README.