🥗 AI-Powered Meal Planner

Personalized meal planning powered by RAG, LLaMA 3, and semantic clustering — no generic recipes, no one-size-fits-all plans.

---

What it does

Most meal planners give you the same 10 recipes shuffled around. This one doesn't.

You enter your dietary preferences, health goals, and nutritional constraints — and the system retrieves semantically relevant foods from the USDA FoodData Central database, clusters them by macronutrient profile using KMeans, and uses LLaMA 3 to generate a personalized meal plan that fits your actual numbers.

The result is a meal plan that's nutritionally grounded, not just keyword-matched.

---

---

Architecture

User Input (goals + constraints)
        ↓
  Embedding Layer (sentence-transformers)
        ↓
  FAISS Vector Store ←── USDA FoodData API
        ↓
  Constraint-Aware Retrieval (RAG)
        ↓
  KMeans Clustering on macronutrient embeddings
        ↓
  LLaMA 3 (meal plan generation via LangChain)
        ↓
  Streamlit UI

---

Stack

Layer	Tool
LLM	LLaMA 3 (via Ollama or HuggingFace)
RAG Framework	LangChain
Vector Store	FAISS
Clustering	KMeans (scikit-learn)
Data Source	USDA FoodData Central API
Frontend	Streamlit
Language	Python

---

Key features

• RAG pipeline — retrieves nutritionally relevant foods using semantic similarity, not keyword search
• KMeans clustering on macronutrient embeddings — groups foods by protein/carb/fat profile so meal variety is nutritionally meaningful, not random
• Constraint-aware retrieval — respects calorie targets, dietary restrictions (vegan, gluten-free, etc.), and macro ratios at query time
• LLM-generated plans — LLaMA 3 assembles retrieved foods into coherent, readable meal plans with portion guidance
• USDA FoodData integration — grounds every recommendation in real nutritional data, not scraped recipe blogs

---

Setup

Prerequisites

• Python 3.10+
• Ollama running locally (for LLaMA 3): ollama pull llama3
• USDA FoodData API key — free at fdc.nal.usda.gov

Install

git clone https://github.com/MaDHuPRi/UMBC-DATA606-Capstone
cd UMBC-DATA606-Capstone
pip install -r requirements.txt

Configure

cp .env.example .env
# Add your USDA API key to .env:
# USDA_API_KEY=your_key_here

Run

streamlit run app.py

Open http://localhost:8501

---

How it works — in detail

1. Data ingestion

Foods and their nutritional profiles are fetched from the USDA FoodData Central API and embedded using sentence-transformers. Embeddings capture both the semantic meaning of food descriptions and their macronutrient context.

2. Semantic clustering

KMeans clustering groups foods by macronutrient embedding similarity — so "chicken breast," "Greek yogurt," and "lentils" end up in the same high-protein cluster regardless of whether you searched for "protein sources." This makes retrieval richer and more diverse.

3. Constraint-aware retrieval (RAG)

At query time, user constraints (calorie budget, macro targets, dietary restrictions) are encoded alongside the query. FAISS retrieves the top-k foods from matching clusters, filtered by the constraint layer before passing to the LLM.

4. Meal plan generation

LangChain orchestrates a structured prompt to LLaMA 3, passing retrieved foods with their nutritional data. The LLM generates a day-by-day, meal-by-meal plan with portions calibrated to the user's targets.

---

Example

Input:

Goal: muscle gain
Calories: 2800/day
Diet: no pork, no shellfish
Macro split: 40% protein, 35% carbs, 25% fat

Output:

Breakfast: 4 scrambled eggs + oats with almond butter (~620 cal, 42g protein)
Lunch: Grilled chicken breast + brown rice + roasted broccoli (~750 cal, 55g protein)
Snack: Greek yogurt + mixed berries + walnuts (~380 cal, 22g protein)
Dinner: Baked salmon + sweet potato + spinach salad (~810 cal, 48g protein)
...

---

Customization ideas

• Add a weekly grocery list export (PDF or CSV)
• Integrate a recipe database (Spoonacular API) to turn ingredient lists into actual recipes
• Add a feedback loop — user rates meals, system reweights embeddings over time
• Support multi-person households with different dietary constraints
• Add a calorie tracking mode that adjusts remaining macros day-by-day

---

Project structure

UMBC-DATA606-Capstone/
├── app.py                  # Streamlit frontend
├── rag/
│   ├── retriever.py        # FAISS retrieval + constraint filtering
│   ├── embedder.py         # Sentence-transformer embeddings
│   └── clusterer.py        # KMeans on macronutrient embeddings
├── llm/
│   └── planner.py          # LangChain + LLaMA 3 meal plan generation
├── data/
│   └── usda_fetcher.py     # USDA FoodData API integration
├── requirements.txt
└── .env.example

---