Your AI-powered cooking companion.
Munchr is a recipe search and AI substitution assistant built with Python and Streamlit. Browse a pre-seeded collection of ~2,000 recipes sourced from AllRecipes.com, view ingredients and step-by-step instructions, and ask Google Gemini AI for ingredient substitutions when you're missing something in your kitchen.
Built for BABI 4005 - BCIT Business & Data Analytics
Live Demo: munchr.streamlit.app
| Search View | Recipe Detail | AI Assistant |
|---|---|---|
 |
 |
 |
| Feature | Description |
|---|---|
| Pre-Seeded Recipe Database | Ships with ~2,000 recipes across 186 search categories - ready to browse out of the box |
| Keyword Search | Search the local SQLite database by keyword; matches against titles, ingredients, and cuisines |
| "I'm Feeling Hungry" | Click once and get a random recipe from the collection |
| AI Ingredient Substitutions | Ask Munchr AI what to use when you're missing an ingredient - powered by Google Gemini |
| Multi-Ingredient Support | Ask about multiple missing ingredients at once (e.g. "I don't have cream or parmesan") |
| Custom UI | Roboto Mono font, crimson/gold/cream/charcoal colour palette, responsive card grid |
Note on live scraping: The codebase includes a live-search module that can scrape AllRecipes.com in real time and cache results locally. This works when running the app on your own machine, but AllRecipes blocks data-centre IPs, so the deployed Streamlit Cloud version relies entirely on the pre-seeded database.
User searches "chicken tikka"
│
▼
┌──────────────────────────────┐ found? ┌────────────────────┐
│ Local SQLite DB │──── yes ──────▶│ Display results │
│ (~2,000 pre-seeded recipes) │ └────────────────────┘
└──────────────────────────────┘
│ no (local only)
▼
┌──────────────────────────┐ ┌────────────────────┐
│ Scrape AllRecipes.com │───────▶│ Store in SQLite & │
│ (works locally, blocked │ │ display results │
│ on cloud deployments) │ └────────────────────┘
└──────────────────────────┘
User clicks "View Recipe" → sees ingredients + instructions
User asks "I don't have heavy cream" →
│
▼
┌──────────────────────────┐ ┌────────────────────┐
│ Google Gemini API │───────▶│ Structured JSON │
│ (gemini-2.5-flash) │ │ substitution cards │
└──────────────────────────┘ └────────────────────┘
- Python 3.13
- Streamlit - web app framework (UI, routing, session state)
- recipe-scrapers - extracts structured data from recipe URLs
- BeautifulSoup4 + lxml - parses AllRecipes search result pages
- google-genai - Google Gemini AI SDK for ingredient substitutions
- SQLite - local database (via Python's built-in
sqlite3) - python-dotenv - loads API keys from
.env - requests - HTTP client for scraping
munchr/
├── app/
│ └── streamlit_app.py # Streamlit web app (UI, styling, session state)
├── scraper/
│ └── recipe_scraper.py # Recipe scraping, SQLite database, search logic
├── ai/
│ └── gemini_assistant.py # Gemini AI ingredient substitution assistant
├── seeds/
│ ├── seed_urls.py # 24 curated AllRecipes URLs for starter seeding
│ └── bulk_seed.py # Bulk seeder - 186 search terms, ~2,000 recipes
├── data/
│ ├── recipes.db # SQLite database (~2,000 pre-seeded recipes)
│ └── sample_output.json # Example recipe JSON structure
├── docs/ # Screenshot images for README
├── .env # API key (not committed - see .env.example)
├── .env.example # Template for environment variables
├── .gitignore
├── requirements.txt
├── reflection.md
└── README.md
- Python 3.10+
- A Google Gemini API key (free tier works)
git clone https://github.com/gunmentoy/munchr.git
cd munchrpython3 -m venv venv
source venv/bin/activate # macOS / Linux
# venv\Scripts\activate # Windowspip install -r requirements.txtcp .env.example .envOpen .env and replace the placeholder with your actual Gemini API key:
GEMINI_API_KEY=your_actual_key_here
streamlit run app/streamlit_app.pyThe app will open in your browser at http://localhost:8501.
The repo ships with a pre-seeded SQLite database of ~2,000 recipes, so the app is ready to use immediately.
If you want to start fresh or update the recipe collection:
Quick seed (24 curated recipes):
python -m scraper.recipe_scraperBulk seed (~2,000 recipes across 186 diverse search terms - takes ~30 min):
python seeds/bulk_seed.py- AllRecipes.com - all recipe data (titles, ingredients, instructions, images, cook times) was scraped from allrecipes.com using the
recipe-scraperslibrary and BeautifulSoup, then pre-seeded into the included SQLite database - Google Gemini AI - ingredient substitution suggestions are generated at runtime by Gemini 2.5 Flash via the
google-genaiSDK
This project was developed with the assistance of GitHub Copilot (Claude Sonnet 4.6) for debugging and documentation. The AI assistant was used as an assistant throughout development - all code was reviewed and tested by the developer.
Google Gemini 2.5 Flash is used at runtime to generate ingredient substitution suggestions based on recipe context and user queries.
- No live search on cloud - AllRecipes.com blocks requests from data-centre IPs, so the Streamlit Cloud deployment searches only the pre-seeded database; live scraping works when running locally
- AllRecipes only - recipe data is sourced exclusively from allrecipes.com; other recipe sites are not supported
- Scraping fragility - if AllRecipes changes their HTML structure, the scraper may need updating
- AI accuracy - Gemini substitution suggestions are AI-generated and may not always be perfect; use your own culinary judgment
- No user accounts - recipes are stored in SQLite; there are no user profiles or saved favourites
- Rate limits - both AllRecipes scraping and Gemini API calls are subject to rate limits on heavy use
This project was created for academic purposes at BCIT.