baldur-framework 1.1.0

Baldur Reliability Layer for Python Applications

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. Durable dead-letter queue, audit, and replay are available in Baldur PRO. The core is framework-agnostic, with first-class adapters for Django, FastAPI, and Flask.

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)

@baldur.protected("name") composes circuit breaker, retry, and fallback into one pipeline. Add Redis (pip install baldur-framework[redis], BALDUR_REDIS_URL=...) when you move to multiple workers so the state is shared.

Quickstart

Pick your framework and have a protected endpoint running:

• Getting Started — Django, FastAPI, Flask
• Full documentation & concept guides: https://baldur.sh

Compatibility

Component	Minimum	Tested in CI
Python	3.11	3.11 · 3.12 · 3.13
Django	4.2	4.2 LTS · 5.2 LTS · 6.0
FastAPI	0.100	latest ≥ floor (smoke)
Flask	2.3	latest ≥ floor (smoke)
Celery	5.3	5.4
Redis server	—	7.x

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

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.

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.

• Bugs / feature requests / docs → open an issue or a pull request.
• Security → see SECURITY.md (no public issues for vulnerabilities).
• Usage questions / commercial → [e-mail].