Family Recipe Assistant

A serverless AI recipe assistant powered by Amazon Bedrock AgentCore, Knowledge Bases, and S3 Vectors. Search, explore, and analyze 600+ family recipes with real-time USDA nutrition lookup, multi-turn conversations, and text-to-speech cooking mode -- all for about $0.08/month in AWS costs.

Features

• Semantic recipe search -- ask natural language questions like "what keto bread recipes do we have?" and get answers from your own collection
• Real-time USDA nutrition -- calculate accurate macros for any recipe or ingredient list using USDA FoodData Central
• Multi-turn conversations -- the agent remembers context across messages ("what are the macros in the second one?")
• SSE streaming -- responses stream word-by-word with real-time tool activity indicators
• Text-to-speech cooking mode -- Amazon Polly reads recipes aloud for hands-free cooking
• Multimodal recipe ingestion -- converts PDFs, photos of handwritten cards, DOCX files into structured markdown via Nova Pro

Architecture

Services Used

Service	Role
Bedrock AgentCore	Managed runtime for the Strands SDK agent
Bedrock Knowledge Base	Vector search over recipe collection
S3 Vectors	Zero-idle-cost vector storage for embeddings
Amazon S3	Recipe markdown storage + frontend static hosting
CloudFront	CDN, HTTPS, single distribution for frontend + API
Lambda	Streaming proxy -- bridges JWT auth to IAM, SigV4 signing
WAF	Rate limiting (100 req/5min per IP), bad input protection
Amazon Cognito	User authentication (User Pool + Identity Pool)
Amazon Polly	Text-to-speech for cooking mode
Bedrock LLM	Nova Pro (default) or Claude Sonnet 4
Titan Embed V2	Embedding model for Knowledge Base
Terraform	Infrastructure as code

Auth Flow

Agent Request Flow

Observability

Cost

Service	Cost (half month, dev)	Notes
Bedrock (LLM)	$0.00	Free tier -- Nova Pro, Titan Embed V2
Bedrock AgentCore	$0.06	~6 vCPU-hours, consumption-based
S3 (storage + vectors)	$0.02	Recipes, frontend, embeddings
CloudFront	$0.00	Free tier (1TB transfer/month)
Lambda	$0.00	Free tier (1M requests/month)
WAF	$0.00	Dev usage within free tier
Cognito	$0.00	Free tier (< 50K MAU)
Total	~$0.08

S3 Vectors replaces OpenSearch Serverless (~$350/month minimum), making RAG feasible for personal projects.

Prerequisites

• AWS account with Bedrock model access enabled for Nova Pro and Titan Embed V2
• AWS CLI configured with credentials
• AgentCore CLI (pip install bedrock-agentcore)
• Terraform >= 1.14
• Python 3.13+ with uv
• Node.js 20+ with npm
• USDA FoodData Central API key (free)

Quick Start

Bootstrap requires two passes because Terraform needs the AgentCore runtime ARN, but the agent can't be deployed until the infrastructure (KB, Cognito, S3) exists.

1. Install dependencies

git clone https://github.com/RDarrylR/serverless-family-recipe-assistant.git
cd serverless-family-recipe-assistant

make init               # Install Python deps (uv sync)
make install-frontend   # Install frontend deps (npm install)

2. First Terraform pass (infrastructure without agent)

cd infrastructure
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars: set alert_email and aws_profile
# Leave agent_runtime_arn empty and cognito_callback_urls as localhost only
# (CloudFront URL will be added after step 4)
terraform init
terraform apply
cd ..

3. Configure and deploy the agent

# One-time X-Ray setup (required for AgentCore observability):
aws xray update-trace-segment-destination --destination CloudWatchLogs

make agent-config       # Generate AgentCore YAML from Terraform outputs
make setup-env          # Generate .env and frontend/.env from Terraform outputs
# Edit .env:
#   - USDA_API_KEY: your USDA FoodData Central API key (free signup)
#   - RECIPE_SOURCE_DIR: path to your raw recipe files (PDFs, images, DOCX)
#   - ACTIVE_LLM: nova (default), nova-lite, claude, or claude-haiku
make deploy-agent       # Deploy agent to AgentCore
# The deploy output prints the agent_runtime_arn (needed for step 4).
# To find AGENT_RUNTIME_ID and MEMORY_ID for .env:
#   AGENT_RUNTIME_ID: run "make agent-status" — it's the runtime name
#                     (e.g., family_recipe_agent-aBcDeFgH)
#   MEMORY_ID: grep memory_id agent/.bedrock_agentcore.yaml
#              (AgentCore CLI populates this on first deploy)
# Edit .env: set AGENT_RUNTIME_ID and MEMORY_ID with these values

4. Second Terraform pass (wire up Lambda to AgentCore)

# Edit infrastructure/terraform.tfvars:
#   - set agent_runtime_arn from step 3
#   - add CloudFront URL to cognito_callback_urls:
#     cognito_callback_urls = ["http://localhost:5173", "https://<dist-id>.cloudfront.net"]
#     (get the URL from: cd infrastructure && terraform output cloudfront_domain_name)
make apply              # Re-apply Terraform (wires Lambda to AgentCore)
make setup-env          # Regenerate .env files (preserves your manual values)

5. Process recipes and deploy frontend

# Copy your recipe source files (PDFs, images, DOCX) to the RECIPE_SOURCE_DIR configured in .env
make preprocess         # Convert raw recipes to structured markdown via Nova Pro
make sync               # Upload to S3 + trigger KB ingestion
make deploy-frontend    # Build React app + deploy to S3 + invalidate CloudFront cache

6. Create a Cognito user

# Create a user (self-signup is disabled by default)
aws cognito-idp admin-create-user \
  --user-pool-id $(cd infrastructure && terraform output -raw cognito_user_pool_id) \
  --username your@email.com \
  --temporary-password 'YourPassword123!' \
  --user-attributes Name=email,Value=your@email.com Name=email_verified,Value=true

# Set a permanent password (skip the "change password" prompt on first login)
aws cognito-idp admin-set-user-password \
  --user-pool-id $(cd infrastructure && terraform output -raw cognito_user_pool_id) \
  --username your@email.com \
  --password 'YourPassword123!' \
  --permanent

Sign in at the CloudFront URL (from terraform output cloudfront_domain_name).

7. Local development

make serve-frontend     # Vite dev server at localhost:5173

Project Structure

+-- agent/                    # AgentCore agent (Strands SDK)
|   +-- agent.py              # Entrypoint - handles SSE streaming
|   +-- config.py             # LLM model configs (nova, claude, etc.)
|   +-- prompts.py            # System prompt
|   +-- tools/                # search_recipes, calculate_nutrition
|   +-- .bedrock_agentcore.yaml.template  # AgentCore deployment config template
+-- functions/                # Lambda functions
|   +-- chat/index.mjs        # Node.js streaming handler (SigV4 -> AgentCore, relays SSE)
+-- frontend/                 # React 19 + Vite SPA
|   +-- src/
|       +-- components/       # AuthScreen, ChatScreen, MessageList, MessageInput
|       +-- contexts/         # AuthContext (Cognito auth state provider)
|       +-- hooks/            # useAuth, useChat (SSE streaming), useTextToSpeech
+-- infrastructure/           # Terraform modules
|   +-- modules/
|       +-- storage/          # S3 buckets (recipes, frontend)
|       +-- knowledge-base/   # Bedrock KB + S3 Vectors
|       +-- auth/             # Cognito user pool + client + identity pool
|       +-- api/              # CloudFront + Lambda Function URL + WAF
|       +-- alerting/         # SNS alerts
+-- scripts/                  # Recipe pipeline
|   +-- preprocess_recipes.py # Extract markdown from PDFs/images via Nova Pro
|   +-- enrich_nutrition.py   # Enrich nutrition data using USDA FoodData Central
|   +-- sync_recipes.py       # Upload to S3, trigger KB ingestion
|   +-- audit_recipes.py      # Dedup + quality checks
+-- data/processed/           # Local processed markdown (gitignored)
+-- tests/                    # pytest (unit + integration)
+-- docs/                     # Agent overview, scripts documentation
+-- diagrams/       # Architecture diagrams (PNG)

Make Commands

# Infrastructure
make plan               # Terraform plan
make apply              # Terraform apply
make tf-init            # Initialize Terraform
make tf-validate        # Validate Terraform configuration

# Agent
make deploy-agent       # Deploy agent to AgentCore
make agent-status       # Check agent deployment status
make agent-invoke PROMPT="..."  # Test agent directly
make agent-config       # Generate AgentCore YAML from template + Terraform outputs
make setup-env          # Generate .env and frontend/.env from Terraform outputs

# Recipe Pipeline
make preprocess         # Extract markdown from raw recipes (PDFs, images, DOCX)
make enrich-nutrition   # Enrich nutrition with USDA data
make sync               # Upload to S3 + trigger KB ingestion
make audit              # Find duplicate recipes

# Frontend
make install-frontend   # Install frontend dependencies
make serve-frontend     # Vite dev server (localhost:5173)
make deploy-frontend    # Build + S3 sync + CloudFront cache invalidation

# Code Quality
make test               # Run all tests (pytest)
make test-unit          # Run unit tests only
make lint               # Ruff check
make fmt                # Ruff format

Agent Configuration

The agent supports multiple LLMs, selected via ACTIVE_LLM at deploy time:

Model	ID	Use Case
nova (default)	us.amazon.nova-pro-v1:0	General use, free tier
nova-lite	us.amazon.nova-lite-v1:0	Faster, cheaper
claude	us.anthropic.claude-sonnet-4-20250514-v1:0	Higher quality
claude-haiku	us.anthropic.claude-3-5-haiku-20241022-v1:0	Fast and cheap

Cleanup

If you deploy this, please remember to destroy the infrastructure when you're done to avoid ongoing charges:

cd infrastructure && terraform destroy

Also delete the AgentCore agent runtime via the AgentCore CLI or AWS console.

Documentation

• Agent Overview -- how the Strands SDK agent works
• Recipe Pipeline Scripts -- preprocessing, enrichment, sync details
• Cost Breakdown -- detailed AWS cost analysis
• Future Architecture -- planned enhancements

Author

Darryl Ruggles -- Blog | Bluesky | X | LinkedIn | AWS Community Builder

Join the Believe In Serverless community!