ijsbakje

chef-gaston

AI-assisted meal planner and Picnic grocery shopping helper.

License: MIT License

Chef Gaston

Chef Gaston is an AI-assisted household meal planner which learns from you and your family's tastes to suggest the best recipes every week while saving you money. Bonus: Chef Gaston can add all the ingredients directly in your Picnic cart.

Chef Gaston was vibecoded with ❤️. Bugs are expected, this is a personal piece of software first, not an official community project.

Quick start

uv sync --all-groups
cp config/household.example.yaml config/household.yaml
# edit config/household.yaml
uv run chef-gaston init
uv run chef-gaston serve

Open http://127.0.0.1:8000.

Demo without Picnic or an LLM key

uv run chef-gaston init --demo
uv run chef-gaston serve --demo

The demo seeds a fictional catalog, two fictional people, and sample recipes. It is safe to share and is separate from real Picnic data.

Household YAML

sources:
  - https://www.marmiton.org
  - https://www.giallozafferano.it
  - https://www.bbcgoodfood.com

weekly_budget: 75

meals:
  dinner: [7, 2]   # count, servings
  lunch: [3, 2]

family_members:
  - name: Alex
    meat_pct: 20             # max share of weekly dinners with meat (0-100)
    fish_pct: 100            # max share of weekly dinners with fish (0-100)
    lactose_mode: none       # none | prefer_free | strict
    spice_tolerance: high
    allergies: [peanuts]     # hard exclusions: ingredient names or groups
    likes: [guacamole, chickpeas]
    dislikes: [mushrooms]
  - name: Sam
    meat_pct: 100
    fish_pct: 100
    lactose_mode: prefer_free
    spice_tolerance: medium
    allergies: []
    likes: [salmon, feta]

pantry:
  - rice: 500g
  - pasta: 250g
  - olive oil: 200ml

settings:
  exploration_rate: 0.2
  taste_floor: 0.40
  household_floor: 0.55
  max_shared_meat_per_week: 2

Configurations:

Credentials

Never put credentials in YAML. Credentials come from the environment only (see .env.example):

export CHEF_LLM_BASE_URL=https://api.deepseek.com
export CHEF_LLM_MODEL=deepseek-chat
export CHEF_LLM_API_KEY=...
export CHEF_PICNIC_AUTH_KEY=...

A local .envrc or shell profile is a good place for these. chef-gaston config-check shows what is configured without printing secrets.

Picnic login

uv run chef-gaston picnic-login
uv run chef-gaston picnic-status
uv run chef-gaston picnic-import
uv run chef-gaston reclassify
uv run chef-gaston translate

The login helper handles 2FA and prints the auth key. It does not save the password; export the key as CHEF_PICNIC_AUTH_KEY in your environment.

LLM

Any OpenAI-compatible JSON endpoint works. Set CHEF_LLM_BASE_URL, CHEF_LLM_MODEL, and CHEF_LLM_API_KEY. Without a key, deterministic imports and planning still work; LLM recipe design and translation are disabled.

How the planning works

Architecture

docs/architecture.d2 is the source; docs/architecture.svg is the rendered diagram.

Chef Gaston architecture

For a blog post, docs/architecture-simple.d2 is the big-blob version, rendered as both docs/architecture-simple.svg and docs/architecture-simple.png.

Safety

Chef Gaston never orders for you, it can only add items to your Picnic cart. You can review, remove or confirm your cart in the app and manually checkout.

Public demo

uv run chef-gaston serve --demo --host 0.0.0.0 is safe to expose:

For a VPS, put it behind a TLS reverse proxy, set CHEF_ACCESS_PASSWORD to require HTTP Basic authentication, and let the proxy apply rate limits. Binding beyond localhost still requires CHEF_ALLOW_REMOTE=1. The concurrency cap is per process, so it is not a substitute for a proxy-level rate limit.

Docker

Build the main image:

docker build -t chef-gaston .

Run it with a persistent database and your household YAML:

docker run -d --name chef-gaston -p 8000:8000 \
  -e CHEF_ACCESS_PASSWORD='...' \
  -e CHEF_LLM_API_KEY=... \
  -e CHEF_PICNIC_AUTH_KEY=... \
  -v chef-data:/data \
  -v "$PWD/config/household.yaml:/config/household.yaml:ro" \
  chef-gaston

The image runs as a non-root user, listens on 0.0.0.0:8000, stores SQLite under /data, and reads the personal household file from /config. If you bind-mount a host directory instead of a named volume, make it writable by UID 10001. The mounted household.yaml must also be readable by that UID (for example chmod 644).

Build and run the read-only demo:

docker build -f Dockerfile.demo -t chef-gaston-demo .
docker run -d --name chef-gaston-demo -p 8000:8000 \
  -e CHEF_ACCESS_PASSWORD='...' \
  chef-gaston-demo

The demo image writes only to /tmp and deletes its temporary database when it stops. For a hardened run, add --read-only --tmpfs /tmp.

Serving under a path prefix

If the app is reverse-proxied at https://example.com/chef/, set:

CHEF_BASE_PATH=/chef

The app accepts both /chef/... and proxy-stripped /... paths, and generates every link with the prefix. The proxy can forward either form. The health endpoint follows the prefix too: /chef/health.

Development

uv run pytest
uv run ruff check .
uv run pyright

Project layout:

Limitations