{"id":28089100,"url":"https://github.com/hoangsonww/pantrypal-streamlit-app","last_synced_at":"2025-05-13T12:53:46.623Z","repository":{"id":290145070,"uuid":"973497222","full_name":"hoangsonww/PantryPal-Streamlit-App","owner":"hoangsonww","description":"🍲 A Streamlit app powered by AI that transforms your pantry ingredients and dietary restrictions into chef-worthy recipes, complete with nutrition charts, shopping lists, and more!","archived":false,"fork":false,"pushed_at":"2025-05-06T03:23:32.000Z","size":6543,"stargazers_count":6,"open_issues_count":0,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-06T04:27:02.619Z","etag":null,"topics":["altair","application","artificial-intelligence","development","gemini","genai","google-ai","google-generative-ai","json","pandas","python","python3","recipe","recipes","streamlit","streamlit-application","streamlit-webapp","unsplash","web"],"latest_commit_sha":null,"homepage":"https://pantrypal-app.streamlit.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoangsonww.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-27T05:42:24.000Z","updated_at":"2025-05-06T03:23:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"a63e6d7c-2985-4bb1-9cd4-55c876983e45","html_url":"https://github.com/hoangsonww/PantryPal-Streamlit-App","commit_stats":null,"previous_names":["hoangsonww/pantrypal-streamlit-app"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FPantryPal-Streamlit-App","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FPantryPal-Streamlit-App/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FPantryPal-Streamlit-App/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FPantryPal-Streamlit-App/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoangsonww","download_url":"https://codeload.github.com/hoangsonww/PantryPal-Streamlit-App/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948212,"owners_count":21988952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["altair","application","artificial-intelligence","development","gemini","genai","google-ai","google-generative-ai","json","pandas","python","python3","recipe","recipes","streamlit","streamlit-application","streamlit-webapp","unsplash","web"],"created_at":"2025-05-13T12:53:45.837Z","updated_at":"2025-05-13T12:53:46.607Z","avatar_url":"https://github.com/hoangsonww.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PantryPal – AI Recipe Generator 🥕\n\n**Meet PantryPal: Your Personal AI-Powered Sous-Chef** 🎉🍽️\n\nSay goodbye to pantry panic! PantryPal instantly transforms whatever you’ve got on hand—plus any dietary preferences—into mouth-watering, chef-level recipes in just seconds. No more copy-pasting lists into ChatGPT or scrolling through endless recipe sites.  \n\nBuilt from the frustration of “what’s for dinner?”, PantryPal combines the power of Google Gemini AI with a sleek, intuitive Streamlit interface. Simply list your ingredients, set your dietary restrictions and servings, and watch as AI crafts a custom recipe complete with step-by-step instructions, nutrition breakdown, shopping list, and stunning hero images. Cooking has never been this effortless—or this inspiring!\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-%3E%3D3.9-3776AB?style=for-the-badge\u0026logo=python\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Streamlit-v1.44.1-FE4A49?style=for-the-badge\u0026logo=streamlit\" alt=\"Streamlit\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Snowflake-Cloud-00B2E2?style=for-the-badge\u0026logo=snowflake\" alt=\"Snowflake\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Google%20GenAI-Gemini-blue?style=for-the-badge\u0026logo=google\" alt=\"Google Gemini AI\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Unsplash-API-0052CC?style=for-the-badge\u0026logo=unsplash\" alt=\"Unsplash API\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python--dotenv-latest-212121?style=for-the-badge\u0026logo=dotenv\" alt=\"python-dotenv\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/pandas-latest-150458?style=for-the-badge\u0026logo=pandas\" alt=\"pandas\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Altair-latest-F47721?style=for-the-badge\u0026logo=altair\" alt=\"Altair\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-Container-2496ED?style=for-the-badge\u0026logo=docker\" alt=\"Docker\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Black-23.7.0-000000?style=for-the-badge\" alt=\"Black\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Streamlit%20Local%20Storage-FF4B00?style=for-the-badge\" alt=\"Streamlit Local Storage\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-4E9F3D?style=for-the-badge\u0026logo=github\" alt=\"MIT License\"\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [🌐 Live App](#-live-app)\n- [📝 Features](#-features)\n- [🛠️ Prerequisites](#-prerequisites)\n- [🚀 Installation](#-installation)\n- [🔑 Configuration](#-configuration)\n- [📂 Directory Structure](#-directory-structure)\n- [▶️ Running the App](#-running-the-app)\n- [🧰 Linting \u0026 Formatting](#-linting--formatting)\n- [🧑‍🍳 How to Use](#-how-to-use)\n- [⚙️ Customization](#-customization)\n- [🐳 Docker Support](#-docker-support)\n- [📊 Analysis Scripts](#-analysis-scripts)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [📧 Contact](#-contact)\n- [🙏 Acknowledgments](#-acknowledgments)\n\n## 🌐 Live App\n\nTry it now in your browser: **[https://pantrypal-app.streamlit.app](https://pantrypal-app.streamlit.app)**. Feel free to explore and generate recipes with your pantry items!\n\n### Home Page\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"docs/img/home.png\" alt=\"Home Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Recipe Page\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"docs/img/recipe-1.png\" alt=\"Recipe Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"docs/img/recipe-2.png\" alt=\"Recipe Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## 📝 Features\n\nAlthough **Streamlit** is not a full-fledged web framework, it provides a simple and effective way to create \ninteractive data-based web applications. Here are some of the key features of PantryPal:\n\n- **Pantry-based recipe generation**: Enter your pantry items and get a recipe tailored to what you have.\n- **Surprise Me!**: Let the AI create a random recipe from scratch.\n- **Dietary restrictions**: Choose from options like Vegetarian, Vegan, Gluten-Free, and more.\n- **Servings slider**: Adjust the number of servings from 1 to 12.\n- **Hero image selection**: Pick a beautiful image for your recipe from Unsplash.\n- **Interactive ingredients checklist**: Check off ingredients as you gather them.\n- **Shopping list download**: Download a TXT file of your shopping list.\n- **Nutrition bar \u0026 donut charts**: Visualize the nutritional breakdown per serving.\n- **Estimated difficulty**: Get an idea of how challenging the recipe is.\n- **Download recipe**: Save your recipe as JSON, Markdown, or plain TXT.\n- **Docker support**: Run the app in a containerized environment for easy deployment.\n- **Linting \u0026 formatting**: Code is formatted with Black and imports are sorted with isort.\n- **Environment variable management**: Use `.env` or `.streamlit/secrets.toml` for sensitive information.\n- **Interactive charts**: Nutrition information is displayed using Altair for better visualization.\n- **Persistent storage**: Recipe history is saved and persists across sessions for easy access.\n- **User-friendly UI**: Built with Streamlit for a clean and intuitive interface.\n\n## 🛠️ Prerequisites\n\n- Python 3.9 or later  \n- A Google Cloud API key with access to the Generative AI (Gemini) API  \n- An Unsplash developer access key for fetching food images  \n\n## 🚀 Installation\n\n1. **Clone the repository**  \n   ```bash\n   git clone https://github.com/hoangsonww/PantryPal-Streamlit-App.git\n   cd PantryPal-Streamlit-App\n   ```\n\n2. **Create \u0026 activate a virtual environment**  \n   ```bash\n   python3 -m venv .venv\n   source .venv/bin/activate      # for macOS/Linux\n   .venv\\Scripts\\activate         # for Windows PowerShell\n   ```\n\n3. **Install dependencies**  \n   ```bash\n   pip install --upgrade pip\n   pip install -r requirements.txt\n   ```\n\n## 🔑 Configuration\n\nCreate a file named `.env` in the project root with the following variables:\n\n```ini\n# .env\nGOOGLE_AI_API_KEY=\u003cYOUR_GOOGLE_GEMINI_API_KEY\u003e\nUNSPLASH_ACCESS_KEY=\u003cYOUR_UNSPLASH_ACCESS_KEY\u003e\n```\n\n- **GOOGLE_AI_API_KEY**: Your Google Cloud API key for the Generative AI (Gemini) API.  \n- **UNSPLASH_ACCESS_KEY**: Your Unsplash Access Key (register at https://unsplash.com/developers).\n\nAlternatively, create a `.streamlit/secrets.toml` file with the same variables:\n\n```toml\n# .streamlit/secrets.toml\nGOOGLE_AI_API_KEY = \"\u003cYOUR_GOOGLE_GEMINI_API_KEY\u003e\"\nUNSPLASH_ACCESS_KEY = \"\u003cYOUR_UNSPLASH_ACCESS_KEY\u003e\"\n```\n\n## 📂 Directory Structure\n\n```\npantrypal/\n├── app.py\n├── .env                 # Environment variables\n├── .streamlit/\n│   ├── config.toml      # Streamlit configuration\n│   └── secrets.toml     # Alternative for .env\n├── Dockerfile           # Dockerfile for containerization\n├── docker-compose.yml   # Docker Compose file\n├── analysis/\n│   ├── ingredient_frequency.py\n│   ├── nutrition_summary.py\n│   └── trends_over_time.py\n├── components/\n│   ├── inputs.py        # Sidebar input UI\n│   └── display.py       # Recipe \u0026 history rendering\n├── utils/\n│   ├── genai_client.py  # Gemini AI wrapper\n│   ├── image_fetcher.py # Unsplash image fetcher\n│   └── storage.py       # JSON‐file storage for history\n├── requirements.txt     # Python dependencies\n└── README.md            # This file\n```\n\n## ▶️ Running the App\n\nWith your virtual environment active and `.env` configured, simply run:\n\n```bash\nstreamlit run app.py\n```\n\nThen open the URL shown in your terminal (e.g. `http://localhost:8501`) in your browser.\n\n## 🧰 Linting \u0026 Formatting\n\nWe use **Black** for code formatting and **isort** for import sorting. To check and format your code, run:\n\n```bash\n# Check code style\nblack --check .\nisort --check .\n\n# Format code\nblack .\nisort .\n```\n\n## 🧑‍🍳 How to Use\n\n1. **Enter Ingredients**  \n   - Paste a comma-separated list of pantry items (e.g. `chicken, rice, tomato`).  \n2. **Select Dietary Restrictions** (optional)  \n   - Choose from Vegetarian, Vegan, Gluten-Free, Dairy-Free, etc.  \n3. **Adjust Servings**  \n   - Slide to set portions (1–12).  \n4. **Generate**  \n   - Click **Generate Recipe** to fetch from Gemini AI.  \n5. **Pick a Hero Image**  \n   - If images are available, select your favorite and click **Confirm Image** once.  \n6. **View Recipe**  \n   - See the title, image, ingredients checklist, shopping list, nutrition charts, difficulty, instructions, and substitutions.  \n7. **Download**  \n   - Grab the recipe as JSON, Markdown, or plain TXT; download your shopping list (TXT).  \n8. **History**  \n   - Scroll down to revisit past recipes; use **Delete** to remove any entry.  \n9. **Surprise Me!**  \n   - Click to have Gemini invent a random recipe from scratch (no pantry required).  \n10. **Clear History**  \n    - Wipe all saved recipes with one click.  \n11. **Enjoy Cooking!**  \n    - Get cooking with your generated recipe! 🧑‍🍳\n    - Share your creations on social media with #PantryPal!\n\n## ⚙️ Customization\n\n- **Max output tokens** \u0026 **temperature** for AI calls can be adjusted in `utils/genai_client.py`.  \n- **Caching** for images is handled in `utils/image_fetcher.py` (TTL = 1 hour).  \n- **Recipe History** uses Local Storage to persist recipe history across sessions.\n  - This allows you to revisit past recipes without needing to regenerate them.\n\n## 🐳 Docker Support\n\nTo run the app in a Docker container, use the provided `Dockerfile` and `docker-compose.yml`. Build and run the container with:\n\n```bash\ndocker-compose up --build\n```\n\nThis will create a Docker image and start the app in a container. Access it at `http://localhost:8501`.\n\n## 📊 Analysis Scripts\n\nOnce you have generated some recipes, you can analyze the data using the scripts in the `analysis/` directory. These scripts provide insights into ingredient frequency, nutrition summaries, and trends over time.\n\nRun the following commands from the project root to execute the analysis scripts:\n\n```bash\npython analysis/ingredient_frequency.py\npython analysis/nutrition_summary.py\npython analysis/trends_over_time.py\n```\n\n## 🤝 Contributing\n\n1. Fork the repo  \n2. Create a new branch (`git checkout -b feature/foo`)  \n3. Commit your changes (`git commit -m \"Add foo\"`)  \n4. Push to the branch (`git push origin feature/foo`)  \n5. Open a Pull Request  \n\n## 📄 License\n\nThis project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.\n\n## 📧 Contact\n\nThis project is created and maintained by [Son Nguyen](https://sonnguyenhoang.com). Below are my contact details:\n- LinkedIn: [hoangsonw](https://www.linkedin.com/in/hoangsonw/)\n- GitHub: [@hoangsonww](https://github.com/hoangsonww)\n\n## 🙏 Acknowledgments\n\n- [Streamlit](https://streamlit.io/) for the web framework  \n- [Google Gemini AI](https://cloud.google.com/generative-ai) for recipe generation  \n- [Unsplash](https://unsplash.com/) for beautiful images  \n- [Altair](https://altair-viz.github.io/) for interactive charts  \n- [Python-dotenv](https://pypi.org/project/python-dotenv/) for environment variable management  \n- [pandas](https://pandas.pydata.org/) for data manipulation  \n- [Snowflake](https://www.snowflake.com/) for cloud deployment\n\n---\n\nThank you for checking out PantryPal! 👨‍🍳 We hope it makes your cooking adventures easier and more fun. If you have any questions or suggestions, feel free to reach out! 🚀\n\n[⬆️ Back to Top](#pantrypal--ai-recipe-generator-)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangsonww%2Fpantrypal-streamlit-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoangsonww%2Fpantrypal-streamlit-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangsonww%2Fpantrypal-streamlit-app/lists"}