Gamito

Gamito Local is a fully local, deterministic meal-planning engine exposed to AI agents through the Model Context Protocol (MCP). It turns a household's profile, budget, pantry, and taste history into budget-disciplined, allergy-safe weekly meal plans, shopping lists, and meal swaps — entirely on your own machine, with no cloud calls.

The system ships in two halves that are designed to work together:

• The MCP server (gamito-mcp) — 20 deterministic tools backed by a local recipe index and a local SQLite store. All math (budgeting, pricing, rescaling, hard allergy filters) is plain Python; nothing is left to a model.
• The Agent Skill (skills/gamito/SKILL.md) — the judgment layer that teaches an orchestrating assistant (e.g. Hermes) when to call which tool, in what order, and how to recover from errors. The server enforces safety; the skill supplies the workflow.

Design principle: Language understanding happens in the agent. Gamito's tools never parse free-form intent — the agent translates a request into a structured tool call, and the server returns deterministic, chat-forwardable results. The SQLite store (not conversation memory) is the single source of truth for every safety constraint.

Why MCP + Skill?

An MCP server alone exposes tool schemas, but a model still has to guess how to sequence them safely. The paired skill closes that gap:

Layer	Responsibility
MCP server	Deterministic execution, hard allergy/diet filters, pricing, persistence
Skill	Identity rules, onboarding interview, tool ordering, error recovery

This separation means allergies and dietary restrictions are enforced as hard filters in code — never as a polite request to the model — while the skill keeps the conversation coherent across planning, edits, feedback, and the household cookbook.

Use Cases

What the MCP + skill pairing is built to do:

• Plan a week of meals — "Plan 5 dinners for 2 people on a 60 EUR budget." Generates a full plan, shopping list, and budget check in one call.
• Stay allergy- and diet-safe — allergies, dislikes, and dietary preferences are stored per profile and applied as hard filters to every plan and swap.
• Respect a food budget — every plan is cost-checked against the stated budget, and assignment actively targets useful budget utilization instead of simply picking the cheapest matching recipes.
• Swap, rescale, and refine meals — "Make Tuesday dinner cheaper / vegan / faster" or "scale Friday up to 4 servings" without rebuilding the plan.
• Generate shopping lists with pantry awareness — items are split into "need to buy" vs. "already have" using the household pantry.
• Track the pantry from a photo — the agent reads long-shelf-life staples off a shelf/fridge photo; the server canonicalises and stores them.
• Learn household tastes — numeric ratings and soft feedback ("less spicy next time") bias future plans toward liked recipes and away from disliked ones.
• Improve a previous plan — regenerate from a source plan, automatically keeping highly-rated slots and avoiding poorly-rated ones.
• Keep a household cookbook — save "mama's recipe" from text or a photo as a custom recipe that competes for slots alongside the base dataset.
• Save and favourite plans — label plans ("Cheap weeknights"), mark favourites, and list them later.
• Automate recurring plans — e.g. "Every Sunday 18:00, generate next week's plan and send the text to the family group."

The 20 tools span six namespaces: Profiles, Planning, Plan Lifecycle, Edits, Shopping & Pantry, Feedback, and Recipes. See skills/gamito/references/tool-index.md for the full signatures and error contract.

Architecture

Household / Hermes agent
        │  natural language
        ▼
  skills/gamito/SKILL.md      ← judgment: when/which tool, ordering, recovery
        │  structured tool calls (gamito:<tool>)
        ▼
  gamito-mcp (FastMCP, stdio) ← 20 deterministic tools
        │
        ├── retrieval/   fastembed + brute-force vector index (data/index/)
        ├── planning/    LangGraph pipeline: assign → budget → shopping → render
        ├── pricing/     canonical ingredient pricing
        ├── pantry/      canonicalisation
        └── db/          SQLite store (profiles, plans, ratings, pantry, recipes)

Installation

Requirements: Python 3.12+ and uv.

# 1. Clone
git clone https://github.com/nerkyzas157/gamito.git
cd gamito

# 2. Install dependencies into a local virtualenv
uv sync

# 3. Initialise the SQLite store (profiles, plans, pantry, recipes)
uv run gamito db init

# 4. Ensure data/index exists before serving requests.
# Prefer copying a prebuilt data/ directory from a workstation:
rsync -az --delete /path/to/prebuilt/gamito/data/ ./data/

The index build encodes the bundled data/recipes_dataset.csv with the BAAI/bge-small-en-v1.5 model into data/index/ (embeddings, metadata, and a manifest). It is resumable — re-run the command to continue an interrupted build — but it is CPU/RAM intensive enough to overwhelm a small VPS. For low-memory hosts, build once on a stronger machine and copy the whole data/ folder to the deploy checkout instead of running the builder in production.

If you do need to rebuild locally:

uv run python scripts/build_local_index.py

Optional: seed a demo profile and plan

uv run python scripts/seed_demo.py

Configuration

Paths are overridable via environment variables:

Variable	Default	Purpose
GAMITO_DATA_DIR	./data	Dataset and index root
GAMITO_INDEX_DIR	./data/index	Prebuilt retrieval index
GAMITO_DB	./gamito.db	SQLite store path

Running the MCP server

The server speaks MCP over stdio:

uv run gamito-mcp

To register it with an MCP client (e.g. Claude Desktop, Cursor, or Hermes), add an entry like:

{
  "mcpServers": {
    "gamito": {
      "command": "uv",
      "args": ["run", "gamito-mcp"],
      "cwd": "/absolute/path/to/gamito"
    }
  }
}

Then make the skill available to the orchestrating agent by pointing it at skills/gamito/SKILL.md. The agent calls tools by their fully-qualified name, e.g. gamito:generate_meal_plan.

Data origins

The bundled recipe corpus is derived from the public Kaggle dataset:

• Extended Recipes Dataset — 64k Dishes, by Wafaa El Husseini — https://www.kaggle.com/datasets/wafaaelhusseini/extended-recipes-dataset-64k-dishes

data/recipes_dataset.csv is a salvaged, normalised subset of that source (currently 14,619 recipes across 36 columns). At index-build time the retrieval pipeline normalises fields (e.g. total_time → total_time_min, list-like columns → JSON) before embedding. The committed index manifest records the source dataset's SHA-256 for reproducibility.

Please refer to the original Kaggle dataset page for its license and terms of use. Pricing and pantry canonicalisation rely on local lookup tables; see data/README.md for the provenance and current status of those auxiliary assets.

Repository layout

src/gamito/
  retrieval/    fastembed encoder + brute-force vector index + hard filters
  planning/     LangGraph plan pipeline and nodes
  pricing/      canonical ingredient pricing
  pantry/       ingredient canonicalisation
  db/           SQLite schema, connection, and data access
  models/       Pydantic models (profile, pantry, planning, meal)
  rendering/    chat-forwardable text rendering (compact / full / labels)
  mcp/          FastMCP app, server entry point, and the 20 tools
  cli.py        dev CLI (db init, custom-recipe import/list/re-embed)
skills/gamito/  Agent Skill (SKILL.md) + tool-index reference
scripts/        index build, retrieval eval, demo seed, test runner
data/           recipe dataset, prebuilt index, lookups
docs/           retrieval eval baseline
tests/          local unittest suite

Budget And Pricing Behavior

Gamito allocates the requested budget across meal slots before recipe assignment. Each non-leftover slot targets roughly 80% of its allocation, then combines semantic relevance with price fit so the plan stays realistic for the requested budget. To avoid cheap recipes dominating higher-budget plans, the assignment node supplements semantic retrieval results with filtered recipes ranked by closeness to the slot's target cost.

Shopping totals are estimated from canonical ingredient pricing when the local lookup tables in data/lookups/ are available. If those lookup tables are missing or empty, Gamito falls back to the selected recipes' estimated_cost_total_eur values whenever ingredient-level pricing would undercount the plan. This keeps budget summaries useful on small deploys that ship only data/index/.

Development

Run the local test suite:

scripts/test          # or: make test
uv run python -m unittest discover -s tests

Evaluate retrieval quality against the golden set:

uv run python scripts/eval_retrieval.py

The current retrieval baseline (12-query golden set) is recorded in docs/eval_baseline.md: 100% hard-filter integrity, ~17 ms warm p95 latency per query, and a manual precision@5 floor of 0.60.

Versioning

This project follows Semantic Versioning and Keep a Changelog; releases are managed with Commitizen. See CHANGELOG.md for the release history.