Plant Based Assistant - AI Chatbot

A production-ready Python chatbot that analyzes vegan ingredients, suggests alternatives, recommends recipes, and provides nutritional insights using LangChain orchestration and multiple data sources.

🎯 Project Status

Completed Phases

• ✅ Phase 1: Project Foundation (config, logging, exceptions)
• ✅ Phase 2: Data Source Integration (USDA, Spoonacular, Vegan DB)
• ✅ Phase 3: Tool Functions (ingredient, recipe, nutrition, meal planning)
• ✅ Phase 4: LangChain Agent Architecture (router agent, memory, synthesizer)
• ✅ Phase 5: Streamlit UI Enhancement (chat interface, nature theme, preferences, history)

In Progress

• 🔄 Phase 6: Error Handling & Robustness (API rate limits, timeouts, graceful degradation)

Coming Soon

• Phase 7: Testing & Quality Assurance (unit/integration tests, coverage targets)
• Phase 8: Documentation & Demo Video (API docs, demo video, GitHub CI/CD)

📋 Features

Core Capabilities

• Ingredient Analysis: Check vegan status with multi-source verification
• Vegan Alternatives: Get substitution suggestions with nutritional matching
• Recipe Discovery: Find recipes by ingredients with dietary filtering
• Nutrition Insights: Get USDA nutrition data with serving size scaling
• Meal Planning: Generate shopping lists and meal plans from recipes

Technical Features

• Multi-Source Synthesis: Combines data from USDA, Spoonacular, and local database
• LangChain Orchestration: Router agent with tool-based architecture
• Conversation Memory: 10-turn conversation context with user profile storage
• Caching Layer: File-based cache with TTL for API efficiency
• Error Handling: Graceful degradation with fallback strategies
• Type Safety: Full type hints throughout codebase

🚀 Quick Start

Prerequisites

• Python 3.9+
• Virtual environment (recommended)
• Git (for version control)

Installation

1. Clone/Set up project

cd c:\CODE KY\PlantBasedAssist

2. Create virtual environment

python -m venv .venv
.venv\Scripts\activate  # On Windows
source .venv/bin/activate  # On macOS/Linux

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

cp .env.example .env
# Edit .env with your API keys:
# GITHUB_TOKEN=your_github_token_with_gpt4o_access
# SPOONACULAR_API_KEY=your_spoonacular_key
# USDA_API_KEY=your_usda_key (free from USDA)

5. Run the application

streamlit run ui/app.py

The chatbot will be available at http://localhost:8501

Using the UI

Quick Start:

1. Click one of 8 suggested prompts, or type your question
2. View response with multi-source data
3. Continue conversation (10-turn memory)

Settings (Sidebar):

• Preferences Tab: Set dietary restrictions, cuisines, protein goals, budget
• History Tab: View conversation, export as JSON, clear history
• About Tab: View version and technologies

Features:

• 🌱 Nature-themed UI with forest green palette
• 💬 Chat with user/assistant avatars
• 📝 Export conversations for analysis
• ⚙️ Customize user preferences
• 💡 8 quick-start prompts for new users

🏗️ Architecture

Layer Structure

User Interface Layer (Streamlit)
         ↓
LangChain Orchestration Layer
- RouterAgent (main decision-maker)
- Tools (ingredient, recipe, nutrition, meal planning)
- Memory Manager (conversation + user profile)
         ↓
Data Access Layer
- USDA API Client (nutrition data)
- Spoonacular API Client (recipes)
- Vegan Database Client (local fallback)
- Cache Manager (response caching)

Key Components

agents/router_agent.py

• Main orchestrator using LangChain
• Defines tools and handles routing
• Manages conversation flow

agents/memory_manager.py

• Conversation history with sliding window
• User profile (preferences, restrictions, goals)
• LLM-compatible message formatting

agents/response_synthesizer.py

• Multi-source output formatting
• Error handling and user-friendly messages
• Response quality optimization

tools/ - Core tool implementations

• ingredient_tools.py - Vegan status checking, alternatives
• recipe_tools.py - Recipe search and details
• nutrition_tools.py - Nutrition analysis and comparisons
• meal_planning_tools.py - Shopping lists and meal plans

data_sources/ - Data integration layer

• usda_client.py - USDA FoodData Central API
• spoonacular_client.py - Recipe API (5M+ recipes)
• vegan_database.py - SQLite local database
• cache_manager.py - TTL-based caching

Configuration

Environment Variables

# AI & Authentication (GitHub token for Copilot GPT-4o)
GITHUB_TOKEN=ghp_...  # Your GitHub personal access token

# External APIs
SPOONACULAR_API_KEY=...  # Get from spoonacular.com
USDA_API_KEY=...  # Get from fdc.nal.usda.gov

# LLM Configuration
LLM_MODEL=gpt-4o  # Model to use
LLM_TEMPERATURE=0.7  # Creativity level (0-1)
LLM_MAX_TOKENS=2000  # Max response length

# Application Settings
DEBUG=False  # Development mode
LOG_LEVEL=INFO  # Logging level
CACHE_TYPE=file  # Cache backend
CACHE_TTL_HOURS=24  # Cache time-to-live

# UI Settings
STREAMLIT_SERVER_PORT=8501
NATURE_THEME=True

API Configuration Notes

GitHub Token for GPT-4o: The application is configured to use your GitHub token for GPT-4o access via Copilot. The standard OpenAI endpoint is currently used, but can be switched to the GitHub Copilot API by:

1. Setting the API base URL to GitHub Copilot endpoint
2. Using appropriate authentication headers
3. Adjusting model name if needed

Refer to GitHub Copilot documentation for specific configuration details.

📚 Usage Examples

1. Check if an ingredient is vegan

User: "Is milk vegan?"
Assistant: Milk: ✗ Not Vegan
Why: Animal product - from cow lactation
Vegan Alternatives:
1. Soy Milk...

2. Find recipes with ingredients

User: "I have tofu and broccoli. What can I make?"
Assistant: [Lists 10 vegan recipes using these ingredients]

3. Compare nutrition

User: "Compare milk and oat milk nutrition"
Assistant: [Nutritional comparison table with analysis]

4. Get meal plan

User: "Generate a 3-day vegan meal plan"
Assistant: [Meal plan with shopping list]

🧪 Testing

Run tests

# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_ingredient_tools.py -v

# With coverage
pytest tests/ --cov=. --cov-report=html

Current test status

• ✅ Ingredient tools: 5/5 passing
• ✅ Configuration: Working
• ✅ Data sources: Connected
• ✅ Cache system: Functional

📁 Project Structure

plant-based-assistant/
├── agents/              # LangChain agents and orchestration
│   ├── router_agent.py  # Main decision-making agent
│   ├── memory_manager.py # Conversation memory + user profile
│   └── response_synthesizer.py
├── data_sources/        # API clients and databases
│   ├── usda_client.py
│   ├── spoonacular_client.py
│   ├── vegan_database.py
│   ├── cache_manager.py
│   └── data/vegan_ingredients.csv
├── tools/               # Tool functions for agents
│   ├── ingredient_tools.py
│   ├── recipe_tools.py
│   ├── nutrition_tools.py
│   └── meal_planning_tools.py
├── ui/                  # Streamlit interface
│   └── app.py
├── config/              # Configuration
│   ├── settings.py
│   ├── constants.py
│   └── logger_config.py
├── utils/               # Utilities
│   ├── exceptions.py
│   ├── retry_logic.py
│   ├── validators.py
│   ├── formatting.py
│   └── logging_util.py
├── tests/               # Test suite
│   ├── conftest.py
│   ├── test_ingredient_tools.py
│   └── fixtures/
├── docs/                # Documentation
├── requirements.txt     # Python dependencies
├── setup.py             # Package setup
├── .env.example         # Environment template
├── .gitignore           # Git ignore rules
└── README.md            # This file

🛣️ Roadmap

Current: Phases 5-8

• Data sources (USDA, Spoonacular, local DB)
• Tool functions (7+ tools)
• LangChain agents (router, memory, synthesis)
• Streamlit UI (in progress)
• Comprehensive error handling
• Full test suite (80%+ coverage)
• Documentation and demo video

Future Enhancements

• User authentication and persistent profiles
• Multi-language support
• Advanced meal planning with nutritional targets
• Recipe scaling and substitution suggestions
• Integration with grocery delivery APIs
• Mobile app (React Native)
• Advanced analytics and user insights

📝 API Documentation

Tool Functions

check_ingredient_vegan_status(ingredient: str) → Dict

Check if ingredient is vegan with multi-source verification.

get_vegan_alternatives(ingredient: str, limit: int = 5) → List[Dict]

Get vegan substitutes with nutritional matching scores.

search_recipes_by_ingredients(ingredients: List[str], diet_type: str = None) → List[Dict]

Find recipes matching ingredients with dietary filters.

get_ingredient_nutrition(ingredient: str, serving_size: float = 100) → Dict

Get USDA nutrition facts for ingredient + serving size.

generate_shopping_list(recipe_ids: List[int], servings: int = 1) → Dict

Aggregate ingredients from multiple recipes.

See API_DOCUMENTATION.md for complete reference.

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit changes with clear messages
4. Push to branch
5. Create Pull Request

📄 License

MIT License - See LICENSE file for details

👨‍💻 Author

Plant Based Assistant Team

🙏 Acknowledgments

• USDA FoodData Central for nutrition data
• Spoonacular for recipe database
• LangChain for AI orchestration
• Streamlit for UI framework
• GitHub Copilot for code assistance

📞 Support

For issues, questions, or suggestions:

1. Check existing GitHub issues
2. Create new issue with detailed description
3. Include error logs and environment info
4. Reference relevant code sections

---

Built with ❤️ for plant-based living