Baldur

Baldur is a self-healing reliability layer for Python applications. It puts circuit breaker, retry, and fallback behind a single decorator, so a flaky downstream stops cascading into your service — and it ships the operational surface you need to actually run that in production: health checks, Prometheus and OpenTelemetry metrics, graceful shutdown, and a built-in web console. The core is framework-agnostic, with first-class adapters for Django, FastAPI, Flask, and Celery.

Real run of the shipped demo: the gateway dies mid-traffic — five charges fail and are captured with their arguments, the circuit breaker opens and shields the dying dependency, and the moment it closes again Baldur replays all five for real. Zero lost. Reproduce it yourself:

pip install "baldur-framework[celery]"
python -m baldur.scripts.demo_self_healing

(The breaker states and DLQ tallies in the recording are read live from the running framework. In your own service the same story surfaces as Baldur's structured log events, live breaker state in the built-in web console, and the Prometheus/OpenTelemetry metrics.)

Why Baldur?

• One decorator, whole pipeline. @baldur.protected("name") composes circuit breaker, retry with backoff, timeout, fallback, and idempotency into one ordered pipeline — instead of hand-wiring three separate libraries and hoping they interact correctly under failure.
• Zero-config start, production path built in. Out of the box everything runs on an in-memory backend — no Redis, no env vars, no Docker. When you move to multiple workers, add Redis and the same code shares state across the fleet. Call sites never change.
• Operate it, don't just import it. A built-in web console shows every breaker's live state and gives you runtime on/off controls; health checks tell your load balancer the truth; metrics come standard.
• Framework-native. Django, FastAPI, Flask, and Celery adapters wire the cache, metrics, and lifecycle hooks at startup, so protection works with your framework's idioms rather than around them.

Install

The Python package is baldur (you import baldur); the PyPI distribution is baldur-framework.

pip install baldur-framework                 # framework-agnostic core
pip install baldur-framework[django]         # Django integration
pip install baldur-framework[fastapi]        # FastAPI integration
pip install baldur-framework[flask]          # Flask integration
pip install baldur-framework[celery]         # Celery task protection
pip install baldur-framework[redis]          # Redis-backed shared state
pip install baldur-framework[prometheus]     # Prometheus metrics

Quick example

import baldur


@baldur.protected("charge-customer")
def charge(order_id: str) -> dict:
    # Wrapped in a circuit breaker by default. With zero configuration this
    # runs on an in-memory fallback — no Redis, no env vars, no Docker.
    return payment_gateway.charge(order_id)

When the payment gateway starts failing, the breaker opens and your service answers fast instead of stacking up timeouts. Need more than the default? Compose the pipeline declaratively:

@baldur.protected(
    "charge-customer",
    retry=True,                              # retry with exponential backoff
    timeout=5.0,                             # per-call time budget
    fallback=lambda: {"status": "queued"},   # graceful answer while OPEN
    idempotency_key="order_id",              # dedupe concurrent duplicates
)
def charge(order_id: str) -> dict:
    return payment_gateway.charge(order_id)

Sync and async callables are both supported — the decorator auto-detects coroutine functions.

What's in the box (OSS, Apache-2.0)

The read path heals the same way. Here a Django app under live HTTP traffic (recorded from a demo harness driving it) loses its network path to Redis for 21 seconds — every request keeps returning 200 off the in-memory cache tier, and the Redis tier resyncs itself on recovery:

Baldur PRO

PRO adds the durable, fleet-level machinery on top of the same API — nothing in the core gets relicensed or replaced. Highlights: DLQ at scale (batch replay from the console, success-rate-driven pacing, a disk-durable outbox, and archive/purge retention), hash-chained audit trail, unified notifications, emergency mode, bulkhead thread-pool isolation, adaptive throttling, canary recovery, governance gates, and a meta-watchdog that watches Baldur itself.

See the full OSS vs PRO capability matrix and pricing.

Documentation

Full documentation lives at https://baldur.sh.

• What is Baldur? — the problem it solves and how
• Getting started: Django · FastAPI · Flask · Celery
• Concept guides — one page per capability, linked throughout this README
• API reference
• Troubleshooting
• Compatibility

Using Baldur with AI assistants

Building with an AI coding assistant (Claude Code, Cursor, Copilot, Codex)? Run baldur init-ai in your repo to drop an AGENTS.md (read by Cursor, Copilot, and Codex) plus a CLAUDE.md that imports it for Claude Code — together they teach the assistant to reach for @baldur.protected("name") instead of hand-rolling a circuit breaker. See Using Baldur with AI assistants.

Compatibility

See Compatibility for the full matrix, the Python × Django test grid, and the version support policy.

Early access

Baldur is early, and it is looking for a small number of teams already running a Python service in production to work with directly. If that is you, the details and how to reach me are in Discussions.

License

Baldur is released under the Apache License 2.0 — see LICENSE and NOTICE.

Contributing

Contributions are welcome under the Apache License 2.0. Pull requests are accepted through a sign-off-based DCO flow — see CONTRIBUTING.md for the full model.

• Ideas, or showing what you built → Discussions.
• Bugs / feature requests / docs → open an issue or a pull request.
• Security → see SECURITY.md (no public issues for vulnerabilities).
• Usage questions / commercial → support@baldur.sh.