{"id":48126746,"url":"https://github.com/snowholt/chefbelle","last_synced_at":"2026-04-04T16:27:29.879Z","repository":{"id":288954337,"uuid":"961195509","full_name":"snowholt/chefbelle","owner":"snowholt","description":"Intelligent cooking companion that finds recipes based on your ingredients using advanced AI. Built for Google's Gen AI Intensive Course 2025Q1, showcasing 8 AI capabilities: LangGraph agents, RAG with ChromaDB, voice commands, nutrition API integration, Google Search grounding, and more.","archived":false,"fork":false,"pushed_at":"2025-06-06T00:06:51.000Z","size":30400,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T00:33:36.746Z","etag":null,"topics":["ai-agents","ai-assistant","chromadb","function-calling","generative-ai","google-ai","google-gemini","kitchen-aid","langchain","langgraph","natural-language-processing","nlp","nutrition-analysis","python","rag","recipe-assistant","speech-to-text","vector-database"],"latest_commit_sha":null,"homepage":"https://chefbelle.com/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snowholt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-06T00:54:49.000Z","updated_at":"2025-06-06T00:23:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"978d5c73-6bc6-4ba5-a09b-8eb417c88be2","html_url":"https://github.com/snowholt/chefbelle","commit_stats":null,"previous_names":["snowholt/chefbelle"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/snowholt/chefbelle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowholt%2Fchefbelle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowholt%2Fchefbelle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowholt%2Fchefbelle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowholt%2Fchefbelle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snowholt","download_url":"https://codeload.github.com/snowholt/chefbelle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowholt%2Fchefbelle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-assistant","chromadb","function-calling","generative-ai","google-ai","google-gemini","kitchen-aid","langchain","langgraph","natural-language-processing","nlp","nutrition-analysis","python","rag","recipe-assistant","speech-to-text","vector-database"],"created_at":"2026-04-04T16:27:29.738Z","updated_at":"2026-04-04T16:27:29.865Z","avatar_url":"https://github.com/snowholt.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://i.ibb.co/svNkqDC9/logo.png\" alt=\"Chefbelle Logo\" width=\"350\"\u003e\n\u003c/div\u003e\n\n# ✨ Chefbelle: Your Interactive AI Kitchen Assistant ✨\n\nChefbelle is an innovative AI-powered kitchen assistant designed to tackle the everyday dilemma: **\"What can I cook with the ingredients I actually have?\"**. It moves beyond traditional recipe apps by understanding your available ingredients, dietary needs, and preferences to suggest personalized recipes and provide interactive cooking guidance.\n\n**Developers:** Nariman Jafarieshlaghi, Neda Saberitabar.\n\n---\n\n## 👨‍💻 Contributors\n\n- **Nariman Jafarieshlaghi** - Lead AI Engineer\n- **Neda Saberitabar** - Data Scientist \u0026 ML Engineer\n- **You?** - We welcome contributions! See our [contribution guidelines](#contributing) below.\n\n---\n\n## 🍳 The Problem: The Everyday Kitchen Dilemma\n\nWe've all been there: staring into the fridge at a random assortment of ingredients – half an onion, some leftover chicken, a lonely bell pepper – wondering what meal we can possibly create. Traditional recipe apps often assume a fully stocked pantry, offer rigid instructions, and don't adapt to specific needs or available time. This often leads to food waste, mealtime stress, and reliance on takeout.\n\n## 🥗 Introducing Chefbelle: Cooking, Reimagined\n\nChefbelle aims to transform your cooking experience by being a smart, interactive kitchen companion. It helps you:\n\n1.  **Discover:** Find delicious recipes based on the ingredients you *already have*.\n2.  **Customize:** Adapt meals to fit dietary goals (Vegan, Gluten-Free, Low-Carb, etc.) and preferences.\n3.  **Guide:** Receive clear, step-by-step cooking instructions.\n4.  **Inform:** Understand the nutritional impact of your meals using reliable data.\n5.  **Interact:** Use natural language via voice or text commands.\n\n**Our Goal:** To build an intuitive and genuinely helpful kitchen assistant that empowers home cooks, reduces food waste, and makes cooking more enjoyable and personalized.\n\n---\n\n## 🧠 Technical Stack \u0026 Architecture\n\nChefbelle leverages a suite of cutting-edge Generative AI capabilities and related technologies:\n\n*   **LLM Core:** **Google Gemini** (specifically `gemini-1.5-flash` in this implementation) powers natural language understanding, intent recognition, response generation, and function calling orchestration.\n*   **Agent Framework:** **LangGraph** is used to build the stateful, multi-step agent, managing the conversation flow, tool usage, and state transitions.\n*   **Tools / Capabilities:**\n    *   **Database Querying (SQLite):** Tools to `list_tables`, `describe_table`, and `execute_query` (read-only) on a structured database (`kitchen_db.sqlite`) containing recipe details, interactions, and nutrition data. Includes specific tools like `get_recipe_by_id` and `get_ratings_and_reviews_by_recipe_id`.\n    *   **Semantic Search (ChromaDB):** A vector database stores recipe embeddings, enabling `gemini_recipe_similarity_search` to find recipes based on conceptual similarity, not just keywords. Includes filtering capabilities. An `gemini_interaction_similarity_search` tool is also available for review analysis.\n    *   **External Nutrition API (USDA FDC):** The `fetch_nutrition_from_usda_fdc` tool calls the official USDA FoodData Central API for reliable, standardized nutritional information per ingredient (with built-in retries).\n    *   **Grounding (Google Search):** Gemini's built-in grounding feature leverages Google Search for real-time answers to general cooking questions outside the scope of the structured data.\n    *   **Audio Understanding (Speech-to-Text):** The `transcribe_audio` function supports **Google Cloud Speech-to-Text** or **OpenAI Whisper** (tested with Google in the notebook) to process voice commands.\n    *   **Structured Output (JSON):** Tools often return results in JSON format for reliable parsing by the agent/nodes.\n    *   **(Placeholders):** `fetch_live_recipe_data` (simulates web scraping) and `customize_recipe` (simulates recipe modification logic) are included as placeholders for future development.\n*   **Data Handling:** **Pandas** for loading, preprocessing, and manipulating datasets.\n*   **Visualization:** **Matplotlib** and **Seaborn** for data exploration and nutrition visualization.\n*   **UI Simulation:** **ipywidgets** to create a basic interactive interface within the Jupyter notebook for testing.\n*   **Stateful Conversation:** The LangGraph `KitchenState` schema maintains context across turns, including message history, selected recipe, processed tool outputs, etc.\n*   **Sentiment Analysis (Optional):** **VADER** library integration for analyzing review sentiment within the `ReviewDashboardNode`.\n\n---\n\n## 📊 Data\n\nChefbelle's knowledge is built upon the following datasets (primarily sourced from Kaggle):\n\n1.  **Food.com Recipes:** (~230k recipes) Contains recipe ID, name, description, ingredients, steps, tags, cooking time, contributor info, etc.\n2.  **Food.com Interactions:** (~1.1M interactions) Includes user ID, recipe ID, rating, and text reviews.\n3.  **Nutritional Breakdown of Foods:** (~3.5k records) Provides nutritional details for common food items (used for fallback/exploration).\n4.  **Food.com Vectorized (ChromaDB):** A pre-computed ChromaDB vector database containing embeddings for the recipes, enabling fast similarity search. Loaded directly from Kaggle datasets.\n\n**Preprocessing Steps:** The notebook includes steps for:\n*   Parsing list-like columns (ingredients, steps, tags).\n*   Removing duplicate recipes.\n*   Normalizing ingredient names (lowercase, removing quantities).\n*   Basic dietary tag identification (vegetarian, gluten-free, etc.) based on keywords.\n\n---\n\n## ⚙️ Setup \u0026 Installation\n\nTo run this project locally (outside Kaggle):\n\n1.  **Clone the Repository:**\n    ```bash\n    git clone https://github.com/your-username/chefbelle.git\n    cd chefbelle\n    ```\n2.  **Create Environment (Recommended):**\n    ```bash\n    python -m venv venv\n    source venv/bin/activate  # On Windows use `venv\\Scripts\\activate`\n    ```\n3.  **Install Dependencies:**\n    ```bash\n    pip install -r requirements.txt\n    # Or install manually based on notebook imports:\n    # pip install google-generativeai langchain-google-genai langgraph chromadb pandas matplotlib seaborn requests ipywidgets beautifulsoup4 openai google-cloud-speech vaderSentiment pydub soundfile\n    ```\n    *(Note: Ensure compatible versions as specified in the notebook, especially for `google-generativeai`, `langgraph`, and `chromadb`)*\n\n4.  **API Keys:**\n    *   Obtain API keys for:\n        *   Google Gemini (from [AI Studio](https://aistudio.google.com/app/apikey))\n        *   USDA FoodData Central (from [FDC API site](https://fdc.nal.usda.gov/api-key-signup.html))\n        *   (Optional) OpenAI API Key (if using Whisper)\n        *   (Optional) Google Cloud Credentials JSON (if using Google Cloud Speech-to-Text - requires project setup, API enabling, service account creation).\n    *   **Securely store these keys.** Using environment variables is recommended:\n        ```bash\n        export GOOGLE_API_KEY=\"your_gemini_key\"\n        export USDA_API_KEY=\"your_usda_key\"\n        export OPENAI_API_KEY=\"your_openai_key\"\n        export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/your/google_credentials.json\"\n        ```\n        Alternatively, create a `.env` file and use a library like `python-dotenv`. **Do not commit keys directly into code.** The notebook uses Kaggle Secrets, which needs adaptation for local use.\n\n5.  **Data \u0026 Databases:**\n    *   Download the required datasets from Kaggle:\n        *   [Food.com Recipes and User Interactions](https://www.kaggle.com/datasets/shuyangli94/food-com-recipes-and-user-interactions)\n        *   [Nutritional Breakdown of Foods](https://www.kaggle.com/datasets/datasciencebowl/cleaned_nutrition_dataset) (or similar)\n        *   [Food.com Vectorized with ChromaDB](https://www.kaggle.com/datasets/narimanjafarieshlaghi/food-com-vectorized-with-chromadb) (Pre-built Vector DB)\n    *   Place the CSV files and the extracted `vector_db` directory in appropriate locations accessible by the notebook (e.g., an `input/` directory).\n    *   Update the `VECTOR_DB_PATH` and CSV loading paths in the notebook if necessary.\n    *   The notebook will create the `kitchen_db.sqlite` file in a `final/` directory upon running the database setup cells.\n\n---\n\n## ▶️ Usage\n\n1.  Ensure all setup steps are complete (environment, dependencies, API keys, data).\n2.  Launch Jupyter Notebook or JupyterLab:\n    ```bash\n    jupyter notebook capstone-2025-kma-nn.ipynb\n    # or\n    jupyter lab capstone-2025-kma-nn.ipynb\n    ```\n3.  Run the cells sequentially. Pay attention to:\n    *   **API Key Setup:** Ensure the code correctly loads your keys (modify the Kaggle Secrets part).\n    *   **Data Loading:** Verify paths to CSVs and the ChromaDB directory.\n    *   **Database Setup:** The SQLite DB will be created. The ChromaDB setup is commented out as it uses pre-existing data.\n4.  Interact with the agent using the **Simulated Interface** cells (Phase 9) or the **Chat Helper Functions** (Phase 10).\n\n---\n\n## 🚀 Future Work\n\n*   Implement the placeholder tools (`fetch_live_recipe_data`, `customize_recipe`) with actual logic (web scraping, advanced LLM calls).\n*   Persist user context (ingredients, preferences) across sessions.\n*   Develop a more robust web application interface (e.g., using Streamlit, Flask, or Gradio).\n*   Improve ingredient normalization and dietary tag accuracy.\n*   Enhance error handling and user feedback.\n*   Implement more sophisticated recipe recommendation logic.\n*   Deploy the assistant.\n\n---\n\n## 📄 License\n\n[Specify your license here, e.g., MIT License, Apache 2.0] (Defaults to None if not specified)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowholt%2Fchefbelle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnowholt%2Fchefbelle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowholt%2Fchefbelle/lists"}