Recipe AI Skill

A reusable Python AI-agent skill for recipe generation, comparison, and weekly meal planning.

Installation

Quick Install

pip install git+https://github.com/peanutsguy/recipe-ai.git

Install from Source

git clone https://github.com/peanutsguy/recipe-ai.git
cd recipe-ai
pip install -e .

Platform-Specific Guides

See INSTALL.md for detailed setup instructions for:

Platform	Guide
OpenCode	INSTALL.md#opencode
OpenClaw	INSTALL.md#openclaw
Windsurf	INSTALL.md#windsurf
Claude (Anthropic)	INSTALL.md#claude-anthropic
Cursor	INSTALL.md#cursor
VS Code + Copilot	INSTALL.md#vs-code--copilot
MCP Servers	INSTALL.md#mcp-servers

Features

• Recipe Retrieval: Find recipes based on available ingredients
• Recipe Generation: Generate new recipes using LLM reasoning
• Recipe Comparison: Compare recipes and select the best one based on criteria
• Weekly Planning: Plan weekly menus respecting dietary constraints and maximizing ingredient reuse

Installation

pip install -e .

Quick Start

1. Load Recipes

from recipe_ai.data.loader import load_recipes_from_jsonl

recipes = load_recipes_from_jsonl("recipe_ai/data/recipes.jsonl")
print(f"Loaded {len(recipes)} recipes")

2. Find Recipes by Ingredients

from recipe_ai.retrieval.retriever import find_recipes_by_ingredients

available = ["pasta", "tomato", "garlic", "basil"]
matching = find_recipes_by_ingredients(available, recipes)

for recipe in matching:
    print(f"- {recipe.name}")

3. Generate a Recipe

from recipe_ai.skills.generator import RecipeGeneratorSkill

class MyLLM:
    async def generate(self, prompt: str) -> str:
        # Call your LLM provider here
        return '{"name":"Quick Pasta","recipeIngredient":["pasta","tomato"],"recipeInstructions":[{"text":"Cook pasta","position":1}]}'

generator = RecipeGeneratorSkill(MyLLM())
recipe = await generator.generate_recipe(["pasta", "tomato"])
print(recipe.name)

4. Compare Recipes

from recipe_ai.skills.comparator import RecipeComparatorSkill

comparator = RecipeComparatorSkill(MyLLM())
best = await comparator.compare_recipes(
    recipes,
    {"goal": "quick dinner", "max_time_minutes": 30}
)
print(f"Best recipe: {best.name}")

5. Plan Weekly Menu

from recipe_ai.planning.planner import WeeklyPlanner

planner = WeeklyPlanner()
plan = planner.plan_weekly_menu(
    recipes=recipes,
    dietary_constraints=["vegetarian"],
    planning_parameters={
        "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
        "meals_per_day": 1
    }
)

for day, meals in plan.items():
    print(f"{day}: {meals[0].name}")

Using with AI Agents

This skill is designed to be LLM-agnostic. Your agent provides the LLM interface:

from recipe_ai.utils.llm_interface import LLMInterface

class AgentLLM(LLMInterface):
    async def generate(self, prompt: str) -> str:
        # Use your agent's LLM here
        return your_agent.generate(prompt)

Then inject it into the skills:

llm = AgentLLM()
generator = RecipeGeneratorSkill(llm)
comparator = RecipeComparatorSkill(llm)

Example Agent Workflow

# User: "I have tomatoes, pasta, and basil. What can I cook?"

# Step 1: Find matching recipes
matching = find_recipes_by_ingredients(["tomatoes", "pasta", "basil"], recipes)

# Step 2: If no matches, generate a new recipe
if not matching:
    new_recipe = await generator.generate_recipe(["tomatoes", "pasta", "basil"])
    matching = [new_recipe]

# Step 3: Return suggestions
for recipe in matching:
    print(f"- {recipe.name}")

# User: "Plan vegetarian lunches for next week"

plan = planner.plan_weekly_menu(
    recipes=recipes,
    dietary_constraints=["vegetarian"],
    planning_parameters={"days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]}
)

for day, meals in plan.items():
    print(f"{day}: {meals[0].name}")

Recipe Dataset Format

Recipes are stored in JSONL format (recipe_ai/data/recipes.jsonl):

{"name": "Recipe Name", "recipeIngredient": ["ingredient1", "ingredient2"], "recipeInstructions": [{"text": "Step 1", "position": 1}], "nutrition": {"calories": {"value": 500, "unitText": "kcal"}}}

Required Fields

• name: Recipe name
• recipeIngredient: List of ingredients
• recipeInstructions: List of steps with text and position

Optional Fields

• nutrition: Nutrition information (calories, protein, etc.)

Architecture

recipe_ai/
├── schemas/          # Pydantic models (Schema.org Recipe)
│   └── recipe.py
├── data/             # Dataset loader
│   ├── loader.py
│   └── recipes.jsonl
├── retrieval/        # Ingredient-based retrieval
│   └── retriever.py
├── skills/           # LLM-powered skills
│   ├── generator.py  # Recipe generation
│   └── comparator.py # Recipe comparison
├── planning/         # Weekly planning
│   └── planner.py    # OR-Tools optimizer
└── utils/            # Utilities
    └── llm_interface.py  # LLM protocol

Design Principles

1. LLM-Agnostic: No hard-coded LLM provider. Inject your own.
2. Schema.org Compatible: Uses Schema.org Recipe structure
3. Constraint-Based Planning: OR-Tools for optimal meal planning
4. Structured Output: All outputs are validated Pydantic models

Testing

pytest

Documentation

• INSTALL.md - Installation guides for OpenCode, OpenClaw, Windsurf, Claude, Cursor, VS Code, and MCP servers
• example_usage.py - Complete working example
• integrations/ - Platform-specific integration files

Dependencies

• pydantic: Schema validation
• ortools: Constraint optimization for planning

License

MIT