RecipePilot AI

Problem

• People often know what ingredients they have, but still struggle to turn them into a realistic meal.
• Time limits, dietary preferences, allergies, cooking skill, and family needs make ad-hoc recipe search unreliable.
• A single unstructured LLM prompt can produce incomplete steps, ignore exclusions, or invent unsafe guidance without a validation layer.

Solution

RecipePilot AI converts structured cooking constraints into a complete plan through a multi-step LangGraph workflow: analyze the request, generate a core recipe, run deterministic validation, enrich with substitutions and guidance, compose a validated response, and persist the result. Invalid recipes are blocked from persistence. Per-node observability tracks latency, tokens, model selection, failures, prompt versions, and estimated cost without blocking generation when telemetry fails.

Product Capabilities

• Recipe overview with servings, timing, and skill-level fit
• Structured ingredients and cooking steps
• Ingredient substitutions
• Cooking timeline
• Shopping list
• Nutrition and allergy notes
• Kid-friendly adjustments
• Storage and leftover recommendations
• “What can go wrong” recovery guidance
• Dedicated, refreshable recipe result URLs

Architecture

1. User → Next.js frontend (Vercel)
   ↓
2. FastAPI API (Railway)
   ↓
3. LangGraph recipe workflow
   ↓
4. OpenAI structured generation
   ↓
5. Deterministic validation
   ↓
6. PostgreSQL on Neon (generated_recipes + agent_runs)
   ↓
7. Refreshable recipe result page

AI Workflow

Engineering Decisions

• Why LangGraph: multi-step orchestration with explicit stages beats one unstructured prompt for reliability and observability
• Why structured outputs: Pydantic schemas keep a predictable API contract between the workflow and the frontend
• Why deterministic validation: servings, timing, exclusions, allergies, steps, and timeline references are checked in Python before persistence
• Why PostgreSQL JSONB: nested recipe results store cleanly without over-normalizing every enrichment field
• Why separate agent-run transactions: telemetry failures must not block recipe generation
• Why task-specific model routing: different nodes can use different models based on latency, tokens, and estimated cost

Observability

• Each LLM node can record model, prompt version, latency, input/output/total tokens, estimated cost, and success or failure
• agent_runs stores per-node telemetry independently from generated_recipes
• Telemetry is isolated so observability issues do not fail the user-facing recipe path
• Production metrics will be populated from agent_runs — no fabricated numbers are shown here

Performance

Challenges and Tradeoffs

• Balancing output quality with latency across multi-step LLM calls
• Handling structured-output failures without degrading the API contract
• Enforcing allergy and exclusion rules deterministically after generation
• Persisting nested recipe results in a queryable, maintainable shape
• Isolating telemetry so observability never blocks core generation
• Deploying and operating frontend, backend, database, and LLM services separately

Testing

• Schema validation for structured recipe and request contracts
• LangGraph node behavior and workflow routing
• Provider failure handling
• Persistence of validated recipes
• Frontend API loading, error, and success states
• Refreshable recipe result pages
• API pytest suite with mocked LLM calls (no live OpenAI in CI)

Future Roadmap

• Planned: curated cooking-knowledge RAG using pgvector
• Planned: RAG evaluation suite
• Planned: streaming workflow progress to the UI
• Planned: user accounts and saved preferences
• Planned: personal recipe uploads
• Planned: pantry tracking
• Planned: meal planning

Skills Demonstrated

• Full-stack architecture
• AI workflow orchestration
• LLM structured outputs
• Model routing
• Prompt engineering
• API design
• Database design
• Observability
• Cost optimization
• Testing
• Cloud deployment

Screenshots

Technology Stack

• Frontend: Next.js, TypeScript, Tailwind CSS, TanStack Query, React Hook Form, Zod
• Backend: Python, FastAPI, Pydantic, SQLAlchemy, Alembic
• AI: LangGraph, OpenAI, structured LLM outputs, task-based model routing, deterministic validation
• Data and infrastructure: PostgreSQL, JSONB, Neon, Railway, Vercel