Meal-Planner/.agent/plan-recipe-discovery.md

Approved Plan — Feedback-Driven Recipe Discovery

Approved: 2026-05-23 User decisions: (1) dashboard badge only for review, (2) 4-week lookback, (3) skip manual review — auto-add on discovery.

Phase A — Feedback Analyzer

• Design complete (see docs/proposals/2026-05-23-feedback-driven-recipe-discovery.md)
• Implement app/services/feedback_analyzer.py
  • Reads feedback from past 4 weeks
  • Aggregates positive signals (preferred cuisines, proteins, high ratings)
  • Aggregates negative signals (avoided tags, ingredients, denial reasons)
  • Generates discovery_queries for external APIs
  • Outputs structured FeedbackAnalysis dataclass
• Add feedback_analysis JSONB column to weekly_run table
• Unit tests for analyzer logic
• Hook into orchestrator step_finalize

Phase B — Recipe Discovery + Ingestion

• Implement app/services/recipe_discovery.py
  • Spoonacular client with quota tracking
  • TheMealDB fallback
  • Query builder from FeedbackAnalysis
• Implement app/services/recipe_ingestion.py
  • Normalize external recipe → our schema
  • Ingredient name mapping (fuzzy + canonical seed data)
  • Duplicate detection via external_source+external_id and fuzzy name match
  • Auto-add to recipe table (no review queue per user)
• Add external_source, external_id, discovery_reason to recipe table
• Admin endpoint: POST /api/admin/trigger-discovery (manual trigger)
• Rate-limiting and quota exhaustion handling

Phase C — Orchestrator Integration

• Weekly finalize step: run analyzer → if queries found and quota available → run discovery → ingest → log
• Configuration env vars:
  • SPOONACULAR_API_KEY (existing)
  • AUTO_DISCOVERY_ENABLED=true
  • AUTO_DISCOVERY_MAX_RECIPES_PER_RUN=5
• Dashboard endpoints: /api/meals/dashboard/discovered-count and /api/meals/dashboard/discovery-insights

Phase D — Verification

• End-to-end tests: analyzer, discovery, ingestion, duplicate prevention
• Test quota exhaustion graceful degradation
• Update docs and README

Halt conditions

• Spoonacular API returns unexpected schema → stop, document, fix mapper
• Ingredient mapping consistently wrong → add LLM-assisted mapping or tighten threshold
• Duplicate recipes slipping through → improve detection logic

Context links

• Proposal: docs/proposals/2026-05-23-feedback-driven-recipe-discovery.md
• HANDOFF: docs/HANDOFF.md (updated with session notes)