Cauldron

Cauldron is a self-hosted companion app for Mealie that adds AI-assisted meal planning and a smart, household-shared shopping list. Mealie stays the source of truth for your recipes, plans and shopping lists; Cauldron layers extra automation on top and stores only per-user preferences and cached metadata.

Features

Ingredient sterilizer — turns free-form quantities ("about 2 cups", "a couple handfuls") into structured {qty, unit, food} parses and writes them back to Mealie, so downstream tooling has clean data to work with.
Weekly meal-plan generator — builds a per-week plan from your recipe library, honouring pinned picks, dietary targets (calories / macros) and allergen exclusions.
Household shopping list — aggregates ingredients across every recipe in a plan and collapses duplicates into single lines (e.g. "2 cups rice + 1.25 lb rice" → "~2 lb rice") using a USDA-derived food-density table.
Recipe discovery, dedupe and enrichment — scrape-and-import new recipes, cluster and merge duplicates, and enrich recipes with structured metadata for smarter planning.
Multi-user, OIDC-secured — every user connects their own Mealie token (encrypted at rest); an optional operator tier exposes the destructive admin tools.

Stack

Flask + gunicorn (Python 3.12+)
Any OpenID Connect provider for authentication (tested with Authentik)
MariaDB for per-user preferences and Fernet-encrypted Mealie tokens
An LLM runner reachable over HTTP for the AI features. This project targets clawdforge, but any service exposing the same POST /run contract works.

Quick start

Cauldron ships as a container and is configured entirely through environment variables.

cp .env.example .env       # then fill in the blanks (see Configuration)
docker compose up -d --build
curl http://localhost:7790/healthz

If you prefer to keep your secrets file outside the repo:

CAULDRON_ENV_FILE=/path/to/cauldron.env docker compose up -d

Requirements

A running Mealie instance and an API token.
An OIDC provider with a client configured for Cauldron's redirect URI.
A MariaDB database and user.
An LLM HTTP runner for the AI features (sterilize / plan / discover / enrich). Without it the app still runs; AI-backed endpoints return an error.

Configuration

All settings are read from the environment. See .env.example for the full, documented list. The most important variables:

Variable	Purpose
`SECRET_KEY`	Flask session signing key
`BIND_HOST` / `BIND_PORT`	Listen address (defaults `0.0.0.0:7790`)
`MEALIE_BASE_URL`	Base URL of your Mealie instance
`MEALIE_API_TOKEN`	System Mealie token for admin batch operations
`CLAWDFORGE_URL` / `CLAWDFORGE_TOKEN`	LLM runner endpoint + auth
`OIDC_ISSUER` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` / `OIDC_REDIRECT_URI`	OpenID Connect login
`DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD`	MariaDB connection
`CAULDRON_FERNET_KEY`	Key used to encrypt per-user Mealie tokens at rest
`ADMIN_BEARER`	Bearer token for the batch (`/api/...`) endpoints
`CAULDRON_ADMIN_SUBS`	OIDC subjects granted the operator-tier admin tools
`CAULDRON_BASE_URL` / `CAULDRON_BEHIND_TLS` / `CAULDRON_TRUSTED_PROXIES`	Public-deploy hardening (CSRF origin guard, HSTS, secure cookies, trusted-proxy `X-Forwarded-*` handling)

When deployed behind a reverse proxy, set CAULDRON_BASE_URL, CAULDRON_BEHIND_TLS=true and list the proxy peer in CAULDRON_TRUSTED_PROXIES so forwarded headers are honoured safely.

Endpoints

GET  /healthz                              liveness + LLM-runner upstream check
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.

Project layout

cauldron/
  config.py            env-driven configuration
  forge.py             LLM-runner HTTP client
  mealie.py            Mealie API client
  sterilizer.py        ingredient parse + apply pipeline
  aggregator.py        cross-recipe shopping-list aggregator
  foods.py             USDA-seeded food catalogue + density lookup
  recipe_index.py      local fuzzy recipe search index
  server.py            Flask app + routes
  data/                seed data (USDA SR Legacy foods)
scripts/
  build_foods_seed.py  build the foods seed from a USDA dataset
  clean_foods_seed.py  LLM-curated cleanup pass over the seed
tests/                 unit tests

Development

pip install -r requirements.txt
python -m pytest         # run the test suite

Contributing

Issues and pull requests are welcome. Please keep changes focused, add tests for new behaviour, and make sure pytest passes before opening a PR.

License

AGPL-3.0-or-later — see LICENSE.

5.2 KiB Raw Blame History