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 serveOpen http://127.0.0.1:8000.
Demo without Picnic or an LLM key
uv run chef-gaston init --demo
uv run chef-gaston serve --demoThe 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: 2Configurations:
sources: websites to use for recipe scrapingweekly_budget: a soft target for the total picnic cost of ingredientsmeals: how many meals and portions per week (for dinners and lunches)family_members: a description of each family membermeat_pct/fish_pct: maximum share of the week’s dinners that may contain that protein.100means no limit;0means never. Setting both to0is a vegetarian household.likes/dislikes/allergies: preferences for each household member
pantry: list of all ingredients you already ownsettings: various global settings to help steer the planning
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 translateThe 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
- Component-level preferences. Just because a member of the family doesn't like an ingredient doesn't reject the recipe, each ingredient has its own match with each family member. Makes substitutions easy to plan.
- Protein percentages, not diet labels. Each member sets a maximum share of the week's dinners that may contain meat and fish (
0–100%, default100%). Vegetarian is simply0/0; flexitarian is a low meat share with fish left open. - Shared base, split protein. The planner can serve a vegetarian base to the whole table, split the protein per person, or share a meat dinner. Per-person budgets decide which variants fit the week.
- Lactose-aware. Milk, cream, yogurt, and soft cheese prefer lactose-free/oat substitutes; hard cheese and butter are allowed.
- Cost-first. The planner minimizes the incremental basket subject to a per-person taste floor, repeat caps, diversity, and 1–2 new recipes per week.
- Cuisine ratings. Each member can rank a cuisine from Love to Avoid. Useful to find compromises in your weekly planning.
- New recipes. 1–2 per week, targeted at 20% exploration.
- Owned ingredients. Each planned component has a check icon. Click it to mark the item as already at home: the quantity moves to the pantry, leaves the basket, and is consumed when you cook the meal.
- Recipe editing. The recipe page has an Edit button for changing quantities or removing extras you never cook. A removed mapped component can make the recipe unpriceable, so the planner will skip it.
- English recipes. URL and Picnic imports are translated on the way in: name, component names, and cooking steps.
chef-gaston translate(or Translate library) covers the existing library. Picnic cooking steps are read from the recipe page instead of the old “available in the app” note.
Architecture
docs/architecture.d2 is the source; docs/architecture.svg is the rendered diagram.
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:
- It uses a temporary SQLite file, never the real database or
config/household.yaml. - HTTP is read-only: POST requests return 403, and the UI hides mutating forms.
- It uses the fake Picnic catalog and no LLM key, so it cannot spend money, scrape sites, or touch a real cart.
- The temporary database is deleted when the process exits.
- Dynamic requests are capped at 8 in flight by default (
CHEF_MAX_CONCURRENCY); extra requests get503withRetry-After. Health checks and static assets are exempt.
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-gastonThe 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-demoThe 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=/chefThe 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 pyrightProject layout:
src/chef_gaston/domain— preferences, variants, scoring, planner, basketsrc/chef_gaston/recipes— parsing, import, mapping, scout, generationsrc/chef_gaston/picnic— real, fake, and disconnected gatewayssrc/chef_gaston/services— planning, cart, onboarding, containersrc/chef_gaston/web— FastAPI app, templates, stylessrc/chef_gaston/cli.py— command linetests— unit, integration, web, and guardrail tests
Limitations
- The Picnic API is unofficial and can break when Picnic changes its pages.
- Fish classification and cooking-step extraction are heuristics over Picnic names and page layouts; review an unusual result before trusting it.
- Translation uses the configured LLM and can be approximate. The shared ingredient catalog keeps its source-language names so matching stays stable.
- Split protein and on-the-side components are supported. Completely different mains for the two people are not generated yet.
- Current-cart subtraction is product-level; a different brand of the same ingredient in the cart is not treated as the same product.
- This is a single-household local app. Add a private access layer before exposing it beyond localhost.
- No checkout. Ever.