===============
LIBRARY RULES
===============
From library maintainers:
- Wrap an external or otherwise-unreliable call in @baldur.protected("name") instead of hand-rolling a circuit breaker, a retry loop, or a try/except fallback. For an inline (non-decorator) call site, use baldur.protect("name", fn).
- Do not add a separate circuit-breaker or retry library alongside Baldur. @baldur.protected composes circuit breaker, retry, timeout, fallback, idempotency, and dead-letter capture into one ordered pipeline.
- The importable package is baldur (import baldur); the PyPI distribution is baldur-framework. Install with pip install baldur-framework. Python 3.11+ is required.
- Call baldur.init() once at process start. The Django, FastAPI, Flask, and Celery adapters do this in their own startup path; a plain script or CLI calls it explicitly.
- Reuse one stable name per protected dependency. Never generate random or per-call names.
- When adding retry= to a call with a non-idempotent side effect (charging a card, creating an order), also pass idempotency_key=. Propose the key and confirm it with the human when the signature is ambiguous - a wrong key is a silent correctness bug.
- Tune through decorator keywords: fallback=, retry=, circuit_breaker=, timeout=, dlq=True, idempotency_key=. Defaults are safe; override only when needed.
- Configuration is by BALDUR_* environment variables. Zero-config runs on an in-memory backend with no Redis. Set BALDUR_REDIS_URL and install baldur-framework[redis] only when breaker state must be shared across workers.

### Development Environment Setup

Source: https://github.com/baldurhq/baldur/blob/main/CONTRIBUTING.md

Commands to clone the repository, create a virtual environment, install dependencies, and set up pre-commit hooks.

```bash
git clone https://github.com/baldurhq/baldur.git
cd baldur-python
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pre-commit install        # installs the ruff lint/format gate
```

--------------------------------

### Install and Run Baldur Demo

Source: https://github.com/baldurhq/baldur/blob/main/README.md

Install the framework with Celery support and execute the self-healing demonstration script.

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

--------------------------------

### Install Baldur for Django

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/django.md

Install the framework and its Django-specific dependencies.

```bash
pip install baldur-framework[django]
```

--------------------------------

### Install and Configure SQL Backend

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/foundations/storage-backends.md

Install the required database driver and set the DSN environment variable to enable SQL storage.

```bash
pip install baldur-framework[postgres]
export BALDUR_SQL_DSN=postgresql://user:pass@host:5432/db
```

--------------------------------

### Install Baldur for FastAPI

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/fastapi.md

Install the required package with FastAPI support.

```bash
pip install baldur-framework[fastapi]
```

--------------------------------

### Install Baldur framework extras

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Install specific framework integrations using pip. Use quotes to handle brackets in shells like zsh or fish.

```bash
pip install "baldur-framework[django]"      # or [fastapi], [flask], [redis], [celery], [prometheus]
pip install "baldur-framework[django,redis]"  # combine extras with commas
```

--------------------------------

### Install Baldur OpenAPI extras

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/api-discoverability.md

Install the required dependencies for OpenAPI support in a Django project.

```bash
pip install 'baldur-framework[django,openapi]'
```

--------------------------------

### Install Baldur packages

Source: https://github.com/baldurhq/baldur/blob/main/README.md

Use pip to install the core framework or specific integrations for Django, FastAPI, Flask, Celery, Redis, and Prometheus.

```bash
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
```

--------------------------------

### Install Baldur Celery support

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/celery.md

Install the necessary package to enable Baldur integration with Celery.

```bash
pip install baldur-framework[celery]
```

--------------------------------

### Run the Django development server

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/django.md

Start the server and verify the protected endpoint.

```bash
python manage.py runserver
curl http://127.0.0.1:8000/demo/
# {"status": "ok", "service": "demo"}
```

--------------------------------

### Install Baldur for Flask

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/flask.md

Install the necessary package to enable Baldur support in Flask applications.

```bash
pip install baldur-framework[flask]
```

--------------------------------

### Install OpenTelemetry Dependencies

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/observability-stack-setup.md

Installs the necessary Python packages to enable OpenTelemetry and Prometheus support in the Baldur framework.

```bash
pip install "baldur-framework[opentelemetry,prometheus]"
```

--------------------------------

### Configure Redis backend

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/foundations/storage-backends.md

Install the required dependency and set the environment variable to enable Redis as the shared state store.

```bash
pip install baldur-framework[redis]
export BALDUR_REDIS_URL=redis://localhost:6379/0
```

--------------------------------

### Run the FastAPI server

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/fastapi.md

Start the application using Uvicorn and verify the endpoint with curl.

```bash
uvicorn app:app --reload
curl http://127.0.0.1:8000/demo
# {"status": "ok", "service": "demo"}
```

--------------------------------

### Configure production Redis backend

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/django.md

Install Redis support and configure the connection for multi-worker deployments.

```bash
pip install baldur-framework[django,redis]
export BALDUR_REDIS_URL=redis://localhost:6379/0
```

--------------------------------

### Install Prometheus dependency

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/oss/metrics.md

Install the optional Prometheus support for Baldur using pip. Quotes are required in zsh and fish shells to prevent glob expansion.

```bash
pip install "baldur-framework[prometheus]"
```

--------------------------------

### GET /api/baldur/health/ready/

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/oss/health-check.md

Checks if the application is ready to serve traffic.

```APIDOC
## GET /api/baldur/health/ready/

### Description
Checks if the application is ready to serve traffic. Returns 200 only when every configured database connection is usable.

### Method
GET

### Endpoint
/api/baldur/health/ready/

### Response
#### Success Response (200)
- **status** (string) - Indicates the application is ready.

#### Error Response (503)
- **status** (string) - Indicates the application is not ready.
```

--------------------------------

### Configure Baldur for Production with Redis

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/celery.md

Install the necessary dependencies and set the environment variable to point Baldur to a shared Redis instance.

```bash
pip install baldur-framework[celery,redis]
export BALDUR_REDIS_URL=redis://localhost:6379/0
```

--------------------------------

### Run the Flask server and test the route

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/flask.md

Start the Flask development server and verify the protected route using curl.

```bash
flask run
curl http://127.0.0.1:5000/demo
# {"status": "ok", "service": "demo"}
```

--------------------------------

### GET /api/baldur/health/live/

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/oss/health-check.md

Checks if the process is alive.

```APIDOC
## GET /api/baldur/health/live/

### Description
Checks if the process is alive. This endpoint always returns 200 while the application is running, even during shutdown drain.

### Method
GET

### Endpoint
/api/baldur/health/live/

### Response
#### Success Response (200)
- **status** (string) - Indicates the process is alive.
```

--------------------------------

### Configure I/O client timeouts

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Examples of setting explicit timeouts for common I/O clients to prevent indefinite blocking.

```python
requests.get(url, timeout=(5, 30))
```

```python
httpx.Client(timeout=httpx.Timeout(connect=5, read=30))
```

```python
aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30))
```

```python
psycopg.connect(..., options="-c statement_timeout=30000")
```

```python
redis.Redis(socket_timeout=5, socket_connect_timeout=5)
```

```python
subprocess.run([...], timeout=30)
```

--------------------------------

### Configure production Redis backend

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/flask.md

Install the Redis extra and set the connection URL to share state across multiple workers.

```bash
pip install baldur-framework[flask,redis]
export BALDUR_REDIS_URL=redis://localhost:6379/0
```

--------------------------------

### Configure production Redis backend

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/fastapi.md

Install the Redis dependency and set the connection URL to share state across multiple workers.

```bash
pip install baldur-framework[fastapi,redis]
export BALDUR_REDIS_URL=redis://localhost:6379/0
```

--------------------------------

### Run Celery beat and worker

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/celery.md

Standard commands to start the Celery beat scheduler and worker processes after configuring Baldur.

```bash
celery -A myproject beat -l info
celery -A myproject worker -l info
```

--------------------------------

### Gunicorn Hook Installation Status Logs

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/gunicorn-graceful-shutdown.md

These log lines appear approximately 2 seconds after baldur.init() to confirm whether Gunicorn hooks are correctly wired.

```text
baldur.gunicorn_hooks_installed     [info]     the hooks are wired; SIGTERM reaches the coordinator
baldur.gunicorn_hooks_not_installed [warning]  running under gunicorn with no hooks imported
```

--------------------------------

### Configure Redis for Multi-Worker Deployments

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Install the Redis extra and set the connection URL to ensure state consistency across multiple workers.

```bash
pip install "baldur-framework[...,redis]"
```

```bash
export BALDUR_REDIS_URL=redis://localhost:6379/0
```

--------------------------------

### Initialize Local Environment File

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/secure-deployment.md

Copies the template file to a local .env file for configuration.

```bash
cp .env.template .env  # .env is gitignored — never commit it
# edit .env, fill in real values, source it in your process manager
```

--------------------------------

### Initialize AI assistant guidance

Source: https://github.com/baldurhq/baldur/blob/main/docs/getting-started/ai-assistants.md

Run this command in the repository root to generate AGENTS.md and CLAUDE.md instruction files.

```bash
baldur init-ai
```

--------------------------------

### Verify Startup Log Output

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/audit-trail-activation.md

Expected log output confirming successful audit trail initialization.

```text
[info] audit.startup_completed
```

--------------------------------

### GET /api/baldur/health/pool/

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/oss/health-check.md

Checks the status of connection pools.

```APIDOC
## GET /api/baldur/health/pool/

### Description
Checks the status of connection pools. Returns 200 when healthy, and 503 when degraded or erroring.

### Method
GET

### Endpoint
/api/baldur/health/pool/

### Response
#### Success Response (200)
- **status** (string) - Indicates the connection pools are healthy.

#### Error Response (503)
- **status** (string) - Indicates the connection pools are degraded or erroring.
- **error** (string) - Error message describing the failure.
```

--------------------------------

### GET /api/baldur/health/

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/oss/health-check.md

Returns the overall system status and detailed per-component information.

```APIDOC
## GET /api/baldur/health/

### Description
Returns the overall system status and detailed per-component information. The status can be healthy, degraded, or unhealthy.

### Method
GET

### Endpoint
/api/baldur/health/

### Query Parameters
- **nocache** (boolean) - Optional - If set to true, forces a fresh computation of the health status instead of using the cached response.

### Response
#### Success Response (200)
- **status** (string) - The overall health status (healthy or degraded).
- **components** (object) - Detailed state of individual components.

#### Error Response (503)
- **status** (string) - The overall health status (unhealthy).
```

--------------------------------

### Configure PRO license

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Set the license key or file path environment variables to enable PRO features.

```bash
export BALDUR_LICENSE_KEY=<your-key>     # or BALDUR_LICENSE_FILE=/etc/baldur/license
```

--------------------------------

### GET /api/baldur/health/ping/

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/oss/health-check.md

Provides a fast health check response without database access.

```APIDOC
## GET /api/baldur/health/ping/

### Description
Provides a fast health check response without database access. Built for high-frequency load-balancer checks.

### Method
GET

### Endpoint
/api/baldur/health/ping/

### Response
#### Success Response (200)
- **status** (string) - Indicates the service is responding.
```

--------------------------------

### Example validation output

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/secure-deployment.md

Represents the expected structure of the secret validation check results.

```python
{'critical': [], 'warning': [...], 'info': [...]}
```

--------------------------------

### Configure Shared State Backend

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/multi-worker-coherence.md

Set the system control backend to Redis to ensure state visibility across all pods.

```bash
export BALDUR_SYSTEM_CONTROL_BACKEND=redis
export BALDUR_REDIS_URL=redis://your-redis:6379/0
```

--------------------------------

### Feature inventory response structure

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/api-discoverability.md

Example of the JSON response returned by the /features/ endpoint.

```json
{
  "entitlement": {"status": "active", "customer_id": "...", "expires": "...", "days_until_expiry": 312},
  "features": [
    {"module": "circuit_breaker.py", "class": "CircuitBreakerSettings", "field": "enabled", "tier": "Core", "default": true, "enabled": true, "env_var": "BALDUR_CB_ENABLED", "license_status": "active"}
  ]
}
```

--------------------------------

### GET /api/baldur/health/ping/

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Fastest health check. Always returns 200, no DB access performed.

```APIDOC
## GET /api/baldur/health/ping/

### Description
Fastest health check. Always returns 200, no DB access performed.

### Method
GET

### Endpoint
/api/baldur/health/ping/
```

--------------------------------

### Verify manifest file existence

Source: https://github.com/baldurhq/baldur/blob/main/docs/runbooks/api-discoverability.md

Use this command to check if the launch manifest file is correctly located within the package data.

```python
python -c "from importlib.resources import files; print(files('baldur._data').joinpath('V1_LAUNCH_MANIFEST.yaml').is_file())"
```

--------------------------------

### GET /api/baldur/health/live/

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Checks if the process is alive. Always returns 200 while running, even during drain.

```APIDOC
## GET /api/baldur/health/live/

### Description
Checks if the process is alive. Always returns 200 while running, even during drain.

### Method
GET

### Endpoint
/api/baldur/health/live/
```

--------------------------------

### GET /api/baldur/health/pool/

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Checks the connection-pool state. Returns 200 for healthy and 503 for degraded or erroring states.

```APIDOC
## GET /api/baldur/health/pool/

### Description
Checks the connection-pool state. Returns 200 for healthy and 503 for degraded or erroring states.

### Method
GET

### Endpoint
/api/baldur/health/pool/
```

--------------------------------

### Run the resource footprint probe

Source: https://github.com/baldurhq/baldur/blob/main/docs/concepts/foundations/resource-budget.md

Executes the built-in measurement script to sample process resource usage across initialization stages.

```bash
python -m baldur.scripts.measure_footprint
```

--------------------------------

### GET /api/baldur/dashboard/summary/

Source: https://github.com/baldurhq/baldur/blob/main/docs/troubleshooting.md

Retrieves a read-only rollup of the self-healing picture, including health verdict, overview counts, and recent activity.

```APIDOC
## GET /api/baldur/dashboard/summary/

### Description
Retrieves a read-only rollup of the self-healing picture, including health verdict, overview counts, and recent activity. Requires Viewer role or higher.

### Method
GET

### Endpoint
/api/baldur/dashboard/summary/

### Response
#### Success Response (200)
- **verdict** (string) - Health status (healthy, good, warning, critical)
- **counts** (object) - Overview counts and resolution rate
- **activity** (array) - Recent activity and failure types
```