Týdenní AI plánovač jídel pro českého uživatele orchestrující 5 LLM agentů přes Claude Agent SDK.
NutriFlow vezme uživatelský profil (váha, výška, věk, cíl, alergie, preference, obsah spíže) a vygeneruje na jedno volání týdenní plán jídel + nákupní seznam v češtině. Vše respektuje denní makroživinové cíle (Mifflin–St Jeor), dietní restrikce, akce v Rohlík.cz a obsah spíže. Plán je hotový za desítky sekund a uživatel vidí progres v reálném čase přes SSE stream.
Zadání vyžaduje projekt s praktickým použitím SDK pro kódovacích agentů, který demonstruje orchestraci (workflow / multi-agent). NutriFlow pokrývá více vzorů najednou — nejen minimum.
| Vrstva | SDK | Kde |
|---|---|---|
| Runtime orchestrace agentů uvnitř aplikace | Claude Agent SDK (claude_agent_sdk v Pythonu) |
backend/src/nutriflow/agents/ |
| Vývoj projektu samotného | Claude Code (kódovací agent) + 8 specializovaných subagentů | .claude/agents/ |
| Metodologie vývoje | Superpowers plugin (brainstorming → writing-plans → TDD → verification) | CLAUDE.md |
| Vzor ze zadání | Kde v kódu | Popis |
|---|---|---|
| Workflow — Sequential | orchestrator.py:184-272 | Nutritionist → Shopper.recon → Chef → Critic → Shopper.finalize |
| Workflow — Loop | orchestrator.py:216-261 | Validation revise loop (max 1× re-Chef, pokud Critic vrátí passed=False) |
| Workflow — Conditional | orchestrator.py:218-261 + tools/rohlik_mcp.py | Větvení podle validace + fallback path při výpadku Rohlík MCP (prázdný PromotionContext + warning; cart sync failure → items bez syncu) |
| Multi-agent — Supervisor | orchestrator.py:166-319 | OrchestratorAgent řídí 4 podagenty procedurálně, drží transakční hranice a perzistenci |
| Multi-agent — Collaboration | domain/schemas.py | Typovaný handoff mezi agenty výhradně přes Pydantic v2 (žádný volný text mezi agenty — viz GOAL.md §13) |
flowchart TD
Start([POST /plans/generate]) --> Skeleton[Create plan skeleton<br/>status=pending]
Skeleton --> Nutritionist[Nutritionist<br/>compute DailyTargets<br/>Mifflin–St Jeor]
Nutritionist --> Recon[Shopper.recon<br/>get PromotionContext<br/>via Rohlík MCP]
Recon -->|MCP unavailable| ReconFallback[empty PromotionContext<br/>+ warning_cs]
Recon --> Chef
ReconFallback --> Chef[Chef<br/>generate WeeklyMealDraft<br/>pantry-first, 7 days]
Chef --> Critic{Critic<br/>validate}
Critic -->|passed=true| Finalize
Critic -->|passed=false<br/>allergy violation| Fail422[HTTP 422<br/>status=failed]
Critic -->|passed=false<br/>other| Revise[Chef.run<br/>+ revision_prompt_cs]
Revise --> Critic2{Critic 2nd run}
Critic2 -->|passed=true| Finalize
Critic2 -->|passed=false| Partial[status=partial<br/>+ warnings_cs]
Partial --> Finalize
Finalize[Shopper.finalize<br/>aggregate ShoppingList<br/>+ optional cart sync] -->|MCP cart fail| FinalizeFallback[items without sync<br/>+ warning_cs]
Finalize --> Persist[Persist artifacts<br/>commit transaction]
FinalizeFallback --> Persist
Persist --> Done([WeeklyPlanResult])
- Backend: Python 3.12, FastAPI, Claude Agent SDK, Pydantic v2, SQLAlchemy 2.x async, Alembic, PostgreSQL 16, Redis 7,
uv, pytest, ruff, mypy strict - Frontend: Next.js 15 (App Router), TypeScript strict, Tailwind v4, shadcn/ui, TanStack Query, react-hook-form + zod
- Infra: Docker Compose, devcontainer, GitHub Actions ready
Vše běží v devcontaineru (.devcontainer/), takže nejjednodušší cesta je otevřít repo ve VS Code → „Reopen in Container“. Mimo devcontainer:
# 1) Spustit Postgres + Redis
docker compose up -d
# 2) Backend
cd backend
cp .env.example .env # doplnit ANTHROPIC_API_KEY
uv sync
uv run alembic upgrade head
uv run uvicorn nutriflow.main:app --reload
# → http://localhost:8000/docs
# 3) Frontend (v jiném terminálu)
cd frontend
cp .env.local.example .env.local
pnpm install
pnpm dev
# → http://localhost:3000Smoke test orchestrace:
curl -X POST http://localhost:8000/api/v1/plans/generate \
-H "Content-Type: application/json" \
-d '{"user_id":1,"week_start":"2026-05-18","regenerate":true}'
# → 202 Accepted s plan_id, dál sledovat:
# GET /api/v1/plans/{plan_id}/events (SSE stream)
# GET /api/v1/plans/{plan_id} (finální výsledek)| Generování plánu (SSE stream) |  |
| Detail hotového plánu |  |
Screenshoty jsou v
docs/screenshots/. Pokud chybí, viz Quick start — UI běží nahttp://localhost:3000.
Toto není toy projekt. Řeší konkrétní reálný problém:
- Vstup: profil uživatele + spíž + dietní restrikce + akce v Rohlík.cz
- Výstup: 7-denní plán × N jídel denně + agregovaný nákupní seznam, vše v češtině
- Hodnota: ušetří uživateli 30–60 minut týdně plánování, respektuje alergie (hard rule — žádný kompromis), využívá akce a obsah spíže
- Robustnost: validační smyčka chytá nesedící makra a alergické chyby ještě před odevzdáním uživateli; výpadek externí služby (Rohlík MCP) neshazuje workflow — pouze degraduje funkčnost s explicitním varováním v češtině
Architekturní spec a všechny invariant je v GOAL.md, pravidla pro práci s kódem v CLAUDE.md.
.
├── backend/ # FastAPI + 5 LLM agentů + DB
│ ├── src/nutriflow/agents/ # Orchestrator, Nutritionist, Chef, Shopper, Critic
│ ├── src/nutriflow/prompts/ # České prompty pro agenty (markdown)
│ ├── src/nutriflow/domain/ # Pydantic schémy (typed handoff mezi agenty)
│ ├── src/nutriflow/tools/ # Rohlík MCP adapter
│ ├── src/nutriflow/db/ # SQLAlchemy modely + Alembic migrace
│ └── tests/ # 158 testů (unit + integration proti real Postgres)
├── frontend/ # Next.js 15 App Router, UI v češtině
│ └── src/app/ # /profil, /spiz, /preference, /plans/generate, /plans/[id]
├── .claude/agents/ # 8 specializovaných subagentů pro Claude Code
├── .devcontainer/ # Reprodukovatelné dev prostředí (Postgres, Redis, tmux backend)
├── docs/ # Architektonická dokumentace + screenshoty
├── GOAL.md # Autoritativní produkt/architecture spec
├── CLAUDE.md # Coding rules + Superpowers metodologie
└── PLAN.md # Progres napříč fázemi vývoje
Projekt je MVP. Vědomě mimo scope (per GOAL.md §3):
- Multi-user / autentifikace (single-user MVP, dev session token)
- Jiné jazyky než čeština (cílová persona je česká domácnost)
- Mobile native, billing, sociální features
Vědomě nedokončené ve scope (Fáza 7 podle CLAUDE.md):
POST /plans/{id}/feedbackendpoint — ORM modelMealFeedbackexistuje, endpoint a UI formulář ne. Plánováno jako navazující práce.
Co je vědomě kompletní:
- 5 agentů s reálnými LLM voláními (žádné stuby v hot path)
- Validační revise loop + Rohlík MCP fallback path
- 158 testů (unit + integration), mypy strict zelený, ruff zelený, TypeScript strict zelený
- Konec-konec flow z UI: profil → generovat plán → vidět progres → otevřít detail
MIT