Spaces:
Sleeping
Sleeping
| title: Nutrition Multi-Agent System | |
| emoji: 🥗 | |
| sdk: gradio | |
| sdk_version: 5.50.0 | |
| app_file: app.py | |
| license: cc-by-nc-4.0 | |
| short_description: Multi-agent nutrition planner with LangGraph + Gemini | |
| # 🥗 MealGraph — Nutrition Multi-Agent System | |
| **Live demo:** <https://huggingface.co/spaces/moazeldegwy/mealgraph> | |
| A clinical-nutrition planner built on **LangGraph** and **Gemini 3.x** | |
| (`gemini-pro-latest` · `gemini-flash-latest` · `gemini-flash-lite-latest`). | |
| Three agents — **Coach**, **MedicalAssessmentAgent**, and | |
| **PlannerAgent** — sit on top of two safe-by-construction tools (a PuLP | |
| linear-program meal solver and a Gemini-grounded web search). Clinical | |
| math runs through closed-form Python formulas (Mifflin-St Jeor BMR, | |
| ACSM activity multipliers); the LLM interprets the numbers but never | |
| recomputes them. The Planner runs a deterministic plan check after the | |
| LP solver and self-revises on allergy / calorie / macro violations | |
| before returning. The Coach does an LLM-graded self-review (medical | |
| flag respect, citation presence, cultural fit) before composing. | |
| ``` | |
| ┌───────────────────────────────────────────┐ | |
| │ Coach │ | |
| │ one typed action per turn (LangGraph) │ | |
| │ + self-review of the Planner's output │ | |
| └──────────────┬────────────────────────────┘ | |
| │ call_agent / ask_user | |
| │ write_memory / compose_response | |
| ┌──────────────┴──────────────┐ | |
| ▼ ▼ | |
| MedicalAssessment Planner | |
| deterministic math draft -> LP -> check_plan | |
| + LLM enrichment (≤ 2 internal revisions) | |
| │ │ | |
| ▼ ▼ | |
| nutrition_formulas QuantitiesFinder (PuLP) | |
| (BMI / BMR / TDEE) WebSearchTool (grounded) | |
| ``` | |
| ## Quick start | |
| ```bash | |
| pip install -r requirements.txt | |
| python app.py | |
| ``` | |
| Open the Gradio UI, paste a Gemini API key, fill in the profile sidebar, | |
| and ask for a plan. | |
| The same repository deploys directly as a **Hugging Face Space** — the | |
| YAML front-matter above is the Space manifest, and `app.py` is the | |
| auto-detected entry point. | |
| ## Architecture | |
| | Component | Role | Key file | | |
| |---|---|---| | |
| | **CoachAgent** | Orchestrator. Picks one action per turn (`call_agent` / `ask_user` / `write_memory` / `compose_response`). After the Planner returns, runs an LLM-graded self-review (medical-flag respect, citation presence, cultural fit) and triggers a revision when needed. | [agents.py](agents.py) | | |
| | **MedicalAssessmentAgent** | Deterministic clinical math first (`full_assessment` → BMI / BMR / TDEE / macros), then an LLM step that emits flags / recommendations / evidence. The agent **overwrites** the LLM's `calculations` with the deterministic values so the math is exact by construction. | [agents.py](agents.py) | | |
| | **PlannerAgent** | Drafts meals, batches nutrition lookups via the grounded `WebSearchTool`, runs the `QuantitiesFinder` LP, then runs `check_plan` (allergy / calorie / macro tolerances) inline. Up to two internal revisions resolve any blocking issue before returning. | [agents.py](agents.py) | | |
| | **`check_plan`** | Deterministic post-LP critic. Allergy → severity `high` (hard block); calorie ±3 % / macro ±5 % → severity `medium`; disliked food → severity `low`. Same code path the Planner uses internally and the eval harness asserts against. | [agents.py](agents.py) | | |
| | **QuantitiesFinder** | PuLP linear-program meal-quantity solver. Default per-food bounds `min = max(20, est × 0.3)`, `max = min(400, est × 2.5)` keep the LP from suggesting 1 g of butter or 900 g of broccoli. Estimate-anchor weight is `0.3`. | [tools.py](tools.py) | | |
| | **WebSearchTool** | Single round-trip wrapper around Gemini's built-in `google_search` grounding. Returns answer + citations + queries from `grounding_metadata`. Prompt biases toward USDA / WHO / ADA / EFSA / NICE / FDA / MedlinePlus. | [tools.py](tools.py) | | |
| | **LongTermMemory** | SQLite-backed semantic / procedural / episodic tiers. | [memory.py](memory.py) | | |
| | **Guardrails** | Prompt-injection sniff, PII redaction, HITL escalation marker (`<<HITL:CLINICIAN_REVIEW_REQUIRED>>`). | [guardrails.py](guardrails.py) | | |
| | **MCP server** | Exposes `QuantitiesFinder` and `assess_user` to Claude Desktop, Cursor, and any MCP-aware client. | [mcp_server.py](mcp_server.py) | | |
| | **Agent cards** | A2A capability descriptors (three cards) with an in-process registry. | [agent_cards.py](agent_cards.py) | | |
| | **Observability** | LangSmith passthrough + in-process metrics surface. | [observability.py](observability.py) | | |
| | **Eval harness** | Three fixture personas; runs offline (no Gemini calls) against `check_plan`. | [evals/](evals/) | | |
| ### Models and rate limits | |
| Three Gemini 3.x rolling aliases, mapped per role. The free-tier RPM / | |
| RPD limits below are conservative defaults; override with | |
| `enable_rate_limiting=False` (or pass a paid quota) if you have one. | |
| | Alias | RPM | RPD | Default role | | |
| |---|---:|---:|---| | |
| | `gemini-pro-latest` | 5 | 100 | Coach, Medical, Planner | | |
| | `gemini-flash-latest` | 10 | 250 | Available for overrides | | |
| | `gemini-flash-lite-latest` | 15 | 500 | Tools (WebSearch), simulator | | |
| ### Safety guarantees | |
| | Guarantee | Where it lives | | |
| |---|---| | |
| | **Allergies never appear in the plan** | Planner's `check_plan` — severity `high` → hard block → internal revision. | | |
| | **Calorie target hit within ±3 %** | Planner's `check_plan` — severity `medium` → revision. | | |
| | **Each macro hit within ±5 %** | Planner's `check_plan` — severity `medium` → revision. | | |
| | **Medical flags respected** | Coach's self-review turn (LLM-graded). | | |
| | **Clinical claims carry citations** | `WebSearchTool` returns `grounding_chunks` natively; Coach checks for them in self-review. | | |
| | **Serious cases escalate** | Medical sets `requires_professional_consultation=True`; Coach appends `<<HITL:CLINICIAN_REVIEW_REQUIRED>>`. | | |
| | **No RCE via LLM-generated code** | No code-from-LLM path exists at all. `nutrition_formulas` is closed-form Python; `QuantitiesFinder` is a pure LP. | | |
| | **Deterministic math** | `full_assessment()` runs server-side; the Medical agent overwrites whatever the LLM emitted for `calculations`. | | |
| ### Run the offline eval harness | |
| Three persona fixtures (athlete, diabetic, vegan-budget) exercise the | |
| deterministic surface — no Gemini calls needed: | |
| ```bash | |
| python -m evals.runner | |
| ``` | |
| ### Run the test suite | |
| ```bash | |
| pytest -ra | |
| ``` | |
| Coverage: schemas, solver behaviour, safety surface, rate-limit pool, | |
| memory tiers, and full Coach ↔ specialist loops via a mock LLM. The | |
| post-LP allergy revision and deterministic-calculation overwrite are | |
| both unit-tested. | |
| --- | |
| ## Library usage | |
| The same code runs as a library. Import the `mealgraph` module, | |
| provide API keys, and call a few setup functions. | |
| ### 1. Import | |
| ```python | |
| import mealgraph | |
| ``` | |
| ### 2. API keys | |
| Provide a list of keys; the system rotates through them and respects | |
| each model's RPM / RPD limit. A single key is enough for evaluation. | |
| ```python | |
| api_keys = [ | |
| "your_api_key1", | |
| "your_api_key2", | |
| ] | |
| ``` | |
| ### 3. (Optional) Model overrides | |
| Override `model_name` or `params` per role. Other configuration is fixed | |
| in the module. | |
| ```python | |
| model_overrides = { | |
| "main": {"model_name": "gemini-pro-latest", "params": {"temperature": 0.5}}, | |
| "agents_llm": {"model_name": "gemini-flash-latest", "params": {"max_tokens": 6000}}, | |
| } | |
| ``` | |
| ### 4. Initialise | |
| ```python | |
| mealgraph.create_llm_instances(api_keys, model_overrides, enable_rate_limiting=True) | |
| mealgraph.initialize_tools() | |
| mealgraph.initialize_agents() | |
| mealgraph.setup_workflow() | |
| ``` | |
| ### 5. Run | |
| Either interactive mode (collects user data via stdin) or simulation | |
| mode (drives one or more synthetic users through a fixed question list): | |
| ```python | |
| mealgraph.run(simulate=False) | |
| # or | |
| mealgraph.run(simulate=True, simulated_users=[...]) | |
| ``` | |
| ## Behaviour notes | |
| * **User mode output** — high-level progress lines, one per agent / tool | |
| action. | |
| * **Debug mode output** — raw LLM input / output (or output only), | |
| scoped per agent / tool. Enable with `mealgraph.debug(level='full', | |
| scopes={'agents': ['CoachAgent'], 'tools': ['all']})`. | |
| * **API-key pooling** — the manager rotates keys and (when rate | |
| limiting is on) enforces per-model RPM / RPD. Keys that exhaust their | |
| daily quota are dropped from the pool until the next UTC day. | |
| * **Interactive mode** — prompts for profile fields, then accepts free | |
| questions; type `exit` to quit. | |
| * **Simulation mode** — each entry in `simulated_users` is a dict with | |
| `user_profile`, `medical_history`, and `questions`; the loop drives | |
| each user's questions sequentially. | |
| * **Error handling** — provide at least one API key (else | |
| `ValueError`). Each initialisation function checks that its | |
| predecessor has been called. | |