# cauldron

Mealie-backed meal planner + shopping-list aggregator. Wraps a Mealie
instance with: an ingredient sterilizer (free-form quantities → structured
parses), a weekly meal-plan generator, and a household shopping list that
collapses cross-recipe duplicates.

## Stack

- Flask + gunicorn, Python 3.12
- Authentik (or any OIDC provider) for sessions
- MariaDB for per-user prefs + Fernet-encrypted Mealie tokens
- [clawdforge](https://github.com/Sulkta-Coop/clawdforge) for the AI layer

Mealie remains the source of truth for recipes / plans / shopping lists.
Cauldron stores per-user prefs + cached metadata only.

## Run

```bash
cp .env.example .env   # fill in secrets
docker compose up -d --build
curl http://localhost:7790/healthz
```

`CAULDRON_ENV_FILE=/path/to/secrets.env docker compose up -d` if your env
file lives outside the repo.

## Endpoints

```
GET  /healthz                              liveness + clawdforge upstream
GET  /login            /auth/callback      OIDC flow
GET  /me                                   account + integration status
GET  /plan             /list               household plan + shopping list
GET  /api/recipes                          (admin bearer) proxy Mealie list
POST /api/sterilize/preview/<slug>         (admin bearer) dry-run parser
POST /api/sterilize/apply/<slug>           (admin bearer) write parses back
```

Admin-bearer endpoints expect `Authorization: Bearer $ADMIN_BEARER`.

## Layout

```
cauldron/
  config.py            env-driven config
  forge.py             clawdforge HTTP client
  mealie.py            Mealie API client
  sterilizer.py        ingredient parse + apply pipeline
  aggregator.py        cross-recipe shopping aggregator
  server.py            Flask app
scripts/
  build_foods_seed.py  USDA → foods seed
  clean_foods_seed.py  clawdforge-curated cleanup pass
```

## License

MIT.