Public API

Hand-maintained contracts for shipped surfaces on the 0.20 train, plus Autodoc (mkdocstrings) for critical signatures. This is not a complete generated reference of every hedron.__all__ name — use the coverage map and prefer Autodoc / source when an outline page lacks an Errors section.

Accepted RFCs that are not yet importable live in the GitHub maintainer corpus (excluded from Read the Docs). Adopters should start from the golden-path contracts below.

Start here (golden path)

After Install → First app → HTMX → Minimal form, these five contracts match what you just used:

1. Hedron — FastAPI application facade
2. Router — @page / @component / @action
3. Page — navigable HTML documents
4. Interaction — FragmentRegion, InteractionResult
5. CLI — hedron check, routes, new, build

hedron vs hedron_core

Day-to-day apps import from hedron (FastAPI facade, router, responses, testing). Advanced typing and rendering primitives such as NodeLike, RenderMode, and get_registry live in hedron_core. Prefer hedron re-exports when available.

Stability: API levels are defined in STABILITY.md. A minimal stable tier (render/model/interaction/CSRF/router facades and portable adapter helpers) is compatibility-protected on the 0.x train. Everything else is beta or experimental unless listed. Package maturity remains Beta on PyPI — pin versions. Live transports stay experimental; prefer polling. Upgrade notes: upgrade guide.

Contracts vs full reference

API pages are hand-maintained contracts, with mkdocstrings signatures for critical surfaces on Autodoc (live helpers, adapters, and core facades — still a subset of every hedron.__all__ name). For a map of every export to a doc page, see Public API coverage map. Flagship narrative pages (Hedron, Router, Action, Interaction, Page, SSE, Streaming, Field, and peers linked below) aim for constructor / field tables, returns, errors, and examples. Some outline pages (for example Utility components, ColorMode) are shorter summaries — prefer guides + Autodoc when a page lacks an Errors section. Human error index: Error codes.

Shipped in 0.19 (still on the 0.20 train)

These surfaces are implemented on the 0.20.0 train (includes the 0.9 authoring break, 0.10 live interaction, and later capability phases through 0.19).

Application

• Hedron
• Router
• Page
• Responses
• Interaction
• State
• SSE · Streaming · WebSocket channel · Preload

Components

• Component
• Built-ins
• Addressable components
• Action
• Auto
• Utility components
• ColorMode
• Charts
• Content

Data and models

• Models and Props
• Field
• Data
• Data sources

Platform

• Rendering
• Themes
• Cache
• Security types
• Auth
• Explorer
• Accessibility (hedron_core.a11y) — 0.19 train (published as v0.19.0; living train 0.20 Published)
• Plugins
• Testing
• API diagnostics
• CLI
• Jobs
• Prepare lifecycle · Security audit sink · Tracing

Also: Configuration · Diagnostics format · Compatibility · Glossary · Live interaction guide

Stability and adapters

• Stability classifications — compatibility catalog (current train 0.20)
• Framework adapter contracts — Supported FastAPI / Flask / Django
• Job interaction contracts — durable JobBackend + polling Supported; SSE experimental

Current train notes

• Accessibility engineering (hedron_core.a11y, Explorer /a11y, PE / landmarks / Page(scripts=), automated AT-019) shipped on 0.19; living train 0.20 (Published as v0.20.0) — A11Y API, What's new in 0.19
• Native Flask/Django depth, QuerySet DataSource, forms bridge, HDJ manifests/CSP inventory (introduced in 0.11; Supported on 0.20.0)
• Advanced async / observability (prepare, audit sink, tracing, durable Redis job status) — Supported on 0.20.0
• Capture UI ships in 0.15+ (no longer deferred); specialty extras in 0.16 are Experimental
• Optional hedron-extras curated toolkit ships in 0.16 (hedron[extras]) — narrative What's new in 0.16; package CHANGELOG
• Model demos / inference workflows ship in 0.18 — Inference API, What's new in 0.18, optional Alpha hedron[gradio]