Baldur

English | 한국어

Baldur keeps the Python calls that fail while a dependency is down, and replays them when it comes back. Wrap a call in one decorator: if the payment gateway dies mid-traffic, every charge that fails is captured with its arguments, a circuit breaker stops your service from piling onto the dying dependency, and the moment the gateway recovers the captured charges are replayed. Nothing is silently lost. Around that loop it ships what you need to run it in production — health checks, Prometheus and OpenTelemetry metrics, graceful shutdown, a built-in web console — with adapters for Django, FastAPI, Flask, and Celery.

Real run of the shipped demo: the gateway goes unreachable mid-traffic — an infrastructure failure, not a declined card — so five charges fail after their retries and are captured with their arguments, the circuit breaker opens and shields the dying dependency (the two charges it rejects never run, and are captured too), and the moment it closes again Baldur replays all seven for real. Zero lost. (Replay is for work that failed on the way out, never for a business rejection, and never for a checkout the customer already walked away from — where that line sits.) 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?

• The call that failed for good is not gone. dlq=True captures it with its arguments; the breaker's recovery replays it, through a handler you register and only for the failure types you opt in. Retry is a policy; capture-and-replay-on-recovery is the part no retry library gives you.
• Around that loop, one decorator composes the whole pipeline. @baldur.protected("name") orders a circuit breaker, a wall-clock budget, fallback, idempotency, and dead-letter capture into one pipeline — the parts your HTTP client or vendor SDK leaves to you. Retry composes in too, for calls that don't retry themselves; where your SDK already retries, keep it and let Baldur surround it.
• 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", dlq=True)
def charge(order_id: str, amount_cents: int) -> dict:
    # Circuit breaker by default; dlq=True parks the call if it fails for
    # good, with its arguments, and replays it once the gateway recovers.
    # Zero configuration runs on an in-memory backend — no Redis, no env
    # vars, no Docker.
    return payment_gateway.charge(order_id, amount_cents)

When the gateway dies, the breaker opens and your service answers fast instead of stacking up timeouts; the charges that failed on the way out wait in the dead-letter queue and come back when it closes. The same decorator protects any dependency — your database, a model provider mid-incident:

@baldur.protected("llm-summarize")
def summarize(doc_id: str) -> str:
    return llm_api.summarize(doc_id)

Need more than the default? Compose the pipeline declaratively:

@baldur.protected(
    "llm-summarize",
    timeout=30.0,                            # one bound on what the caller waits
    fallback=lambda: last_good_summary(),    # graceful answer while OPEN
    idempotency_key="doc_id",                # a redelivered job pays once
)
def summarize(doc_id: str) -> str:
    return llm_api.summarize(doc_id)

Notice what isn't there: retry=. Your SDK almost certainly retries already — anthropic and openai default to two attempts with backoff, boto3 has an adaptive mode — and it retries better than a generic wrapper can, because it knows which status codes are worth another attempt and honours retry-after. Keep it. What no SDK gives you is the rest: a breaker, so a provider incident doesn't mean every request pays its retries before failing; one wall-clock bound on what your caller waits, retries included (an SDK's own worst case is timeout × (max_retries + 1) — 30 minutes at anthropic's defaults); a fallback; and a dedup key that survives a job redelivery the SDK never sees. retry=True is there for the calls that don't retry themselves.

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 in early access: the API is stable and the core is tested under sustained load with Sentinel failover, but the project is young — minor releases may still ship breaking changes, always with a changelog entry. 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.