jessejohnson/plg4-dev-server

1# Recipe Recommendation Chatbot - Backend API2 3Backend for AI-powered recipe recommendation system built with FastAPI, featuring RAG (Retrieval-Augmented Generation) capabilities, conversational memory, and multi-provider LLM support.4 5## 🚀 Quick Start6 7### Prerequisites8- Python 3.9+9- pip or poetry10- API keys for your chosen LLM provider (OpenAI, Google, or HuggingFace)11 12### Installation13 141. **Clone and navigate to backend**15   ```bash16   git clone <repository-url>17   cd PLG4-Recipe-Recommendation-Chatbot/backend18   ```19 202. **Install dependencies**21   ```bash22   pip install -r requirements.txt23   ```24   > 💡 **Note**: Some packages are commented out by default to keep the installation lightweight:25   > - **HuggingFace dependencies** (`transformers`, `accelerate`, `sentence-transformers`) - Uncomment if using HuggingFace models26   > - **sentence-transformers** (~800MB) - Uncomment for HuggingFace embeddings27 283. **Configure environment**29   ```bash30   cp .env.example .env31   # Edit .env with your API keys and configuration32   ```33 344. **Run the server**35   ```bash36   # Development mode with auto-reload37   uvicorn app:app --reload --host 127.0.0.1 --port 808038   39   # Or production mode40   uvicorn app:app --host 127.0.0.1 --port 808041   ```42 435. **Test the API**44   ```bash45   curl http://localhost:8080/health46   ```47 486. **HuggingFace Spaces deployment**49   ```50   sh deploy-to-hf.sh <remote>51   ``` 52   where <remote> points to the HuggingFace Spaces repository53 54## 📁 Project Structure55 56```57backend/58├── app.py                 # FastAPI application entry point59├── requirements.txt       # Python dependencies60├── .env.example          # Environment configuration template61├── .gitignore            # Git ignore rules62│63├── config/               # Configuration modules64│   ├── __init__.py65│   ├── settings.py       # Application settings66│   ├── database.py       # Database configuration67│   └── logging_config.py # Logging setup68│69├── services/             # Core business logic70│   ├── __init__.py71│   ├── llm_service.py    # LLM and RAG pipeline72│   └── vector_store.py   # Vector database management73│74├── data/                 # Data storage75│   ├── recipes/          # Recipe JSON files76│   │   └── recipe.json   # Sample recipe data77│   └── chromadb_persist/ # ChromaDB persistence78│79├── logs/                 # Application logs80│   └── recipe_bot.log    # Main log file81│82├── docs/                 # Documentation83│   ├── model-selection-guide.md      # 🎯 Complete model selection & comparison guide84│   ├── model-quick-reference.md      # ⚡ Quick model switching commands  85│   ├── chromadb_refresh.md           # ChromaDB refresh guide86│   ├── opensource-llm-configuration.md  # Open source LLM setup guide87│   ├── logging_guide.md              # Logging documentation88│   ├── optimal_recipes_structure.md  # Recipe data structure guide89│   ├── sanitization_guide.md         # Input sanitization guide90│   └── unified-provider-configuration.md  # Unified provider approach guide91│92└── utils/                # Utility functions93    └── __init__.py94```95 96## ⚙️ Configuration97 98### Environment Variables99 100Copy `.env.example` to `.env` and configure the following:101 102> 🎯 **Unified Provider Approach**: The `LLM_PROVIDER` setting controls both LLM and embedding models, preventing configuration mismatches. See [`docs/unified-provider-configuration.md`](docs/unified-provider-configuration.md) for details.103 104#### **Server Configuration**105```bash106PORT=8000                 # Server port107HOST=0.0.0.0             # Server host108ENVIRONMENT=development   # Environment mode109DEBUG=true               # Debug mode110```111 112#### **Provider Configuration**113Choose one provider for both LLM and embeddings (unified approach):114 115> 🎯 **NEW: Complete Model Selection Guide**: For detailed comparisons of all models (OpenAI, Google, Anthropic, Ollama, HuggingFace) including latest 2025 models, performance metrics, costs, and scenario-based recommendations, see [`docs/model-selection-guide.md`](docs/model-selection-guide.md)116 117> ⚡ **Quick Reference**: For one-command model switching, see [`docs/model-quick-reference.md`](docs/model-quick-reference.md)118 119**OpenAI (Best Value & Latest Models)**120```bash121LLM_PROVIDER=openai122OPENAI_API_KEY=your_openai_api_key_here123OPENAI_MODEL=gpt-5-nano             # 🎯 BEST VALUE: $1/month for 30K queries - Modern GPT-5 at nano price124# Alternatives:125# - gpt-4o-mini                     # Proven choice: $4/month for 30K queries126# - gpt-5                           # Premium: $20/month unlimited (Plus plan)127OPENAI_EMBEDDING_MODEL=text-embedding-3-small # Used automatically128```129 130**Google Gemini (Best Free Tier)**131```bash132LLM_PROVIDER=google133GOOGLE_API_KEY=your_google_api_key_here134GOOGLE_MODEL=gemini-2.5-flash       # 🎯 RECOMMENDED: Excellent free tier, then $2/month135# Alternatives:136# - gemini-2.0-flash-lite           # Ultra budget: $0.90/month for 30K queries137# - gemini-2.5-pro                  # Premium: $25/month for 30K queries138GOOGLE_EMBEDDING_MODEL=models/embedding-001 # Used automatically139```140 141**Anthropic Claude (Best Quality-to-Cost)**142```bash143LLM_PROVIDER=anthropic144ANTHROPIC_API_KEY=your_anthropic_api_key_here145ANTHROPIC_MODEL=claude-3-5-haiku-20241022  # 🎯 BUDGET WINNER: $4/month for 30K queries146# Alternatives:147# - claude-3-5-sonnet-20241022      # Production standard: $45/month for 30K queries148# - claude-3-opus-20240229          # Premium quality: $225/month for 30K queries149ANTHROPIC_EMBEDDING_MODEL=voyage-large-2 # Used automatically150```151 152**Ollama (Best for Privacy/Self-Hosting)**153```bash154LLM_PROVIDER=ollama155OLLAMA_BASE_URL=http://localhost:11434156OLLAMA_MODEL=llama3.1:8b            # 🎯 YOUR CURRENT: 4.7GB download, 8GB RAM, excellent balance157# New alternatives: 158# - deepseek-r1:7b                  # Breakthrough reasoning: 4.7GB download, O1-level performance159# - codeqwen:7b                     # Structured data expert: 4.2GB download, excellent for recipes160# - gemma3:4b                       # Resource-efficient: 3.3GB download, 6GB RAM161# - mistral-nemo:12b                # Balanced performance: 7GB download, 12GB RAM162OLLAMA_EMBEDDING_MODEL=nomic-embed-text # Used automatically163```164 165**HuggingFace (Downloadable Models Only - APIs Unreliable)**166```bash167LLM_PROVIDER=ollama  # Use Ollama to run HuggingFace models locally168OLLAMA_MODEL=codeqwen:7b             # 🎯 RECOMMENDED: Download HF models via Ollama for reliability169# Other downloadable options:170# - mistral-nemo:12b                # Mistral's balanced model171# - nous-hermes2:10.7b              # Fine-tuned for instruction following172# - openhermes2.5-mistral:7b        # Community favorite173OLLAMA_EMBEDDING_MODEL=nomic-embed-text # Used automatically174```175> ⚠️ **Important Change**: HuggingFace APIs have proven unreliable for production. We now recommend downloading HuggingFace models locally via Ollama for consistent performance.176> ⚠️ **HuggingFace Update**: HuggingFace dependencies are no longer required as we recommend using downloadable models via Ollama instead of unreliable APIs. For local HuggingFace models, use Ollama which provides better reliability and performance.177 178> 📖 **Local Model Setup**: See [`docs/opensource-llm-configuration.md`](docs/opensource-llm-configuration.md) for GPU setup, model selection, and performance optimization with Ollama.179 180> 💡 **Unified Provider**: The `LLM_PROVIDER` setting automatically configures both the LLM and embedding models, ensuring consistency and preventing mismatched configurations.181 182#### **Vector Store Configuration**183Choose between ChromaDB (local) or MongoDB Atlas:184 185**ChromaDB (Default)**186```bash187VECTOR_STORE_PROVIDER=chromadb188DB_COLLECTION_NAME=recipes189DB_PERSIST_DIRECTORY=./data/chromadb_persist190# Set to true to delete and recreate DB on startup (useful for adding new recipes)191DB_REFRESH_ON_START=false192```193 194**MongoDB Atlas**195```bash196VECTOR_STORE_PROVIDER=mongodb197MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/198MONGODB_DATABASE=recipe_bot199MONGODB_COLLECTION=recipes200```201 202#### **Embedding Configuration**203```bash204# Embedding provider automatically matches LLM_PROVIDER (unified approach)205# No separate configuration needed - handled automatically based on LLM_PROVIDER setting206```207 208> 💡 **Unified Provider**: The `LLM_PROVIDER` setting automatically configures both the LLM and embedding models, ensuring consistency and preventing mismatched configurations. See [`docs/model-selection-guide.md`](docs/model-selection-guide.md) for all available options.209 210## 🛠️ API Endpoints211 212### Core Endpoints213 214#### **Health Check**215```bash216GET /health217```218Returns service health and configuration status.219 220#### **Chat with RAG**221```bash222POST /chat223Content-Type: application/json224 225{226  "message": "What chicken recipes do you have?"227}228```229Full conversational RAG pipeline with memory and vector retrieval.230 231#### **Simple Demo**232```bash233GET /demo?prompt=Tell me about Italian cuisine234```235Simple LLM completion without RAG for testing.236 237#### **Clear Memory**238```bash239POST /clear-memory240```241Clears conversation memory for fresh start.242 243### Example Requests244 245**Chat Request:**246```bash247curl -X POST "http://localhost:8080/chat" 248  -H "Content-Type: application/json" 249  -d '{"message": "What are some quick breakfast recipes?"}'250```251 252**Demo Request:**253```bash254curl "http://localhost:8080/demo?prompt=What%20is%20your%20favorite%20pasta%20dish?"255```256 257## 🏗️ Architecture258 259### Core Components260 261#### **LLM Service** (`services/llm_service.py`)262- **ConversationalRetrievalChain**: Main RAG pipeline with memory263- **Simple Chat Completion**: Direct LLM responses without RAG264- **Multi-provider Support**: OpenAI, Google, HuggingFace265- **Conversation Memory**: Persistent chat history266 267#### **Vector Store Service** (`services/vector_store.py`)268- **ChromaDB Integration**: Local vector database269- **MongoDB Atlas Support**: Cloud vector search270- **Document Loading**: Automatic recipe data ingestion271- **Embedding Management**: Multi-provider embedding support272 273#### **Configuration System** (`config/`)274- **Settings Management**: Environment-based configuration275- **Database Configuration**: Vector store setup276- **Logging Configuration**: Structured logging with rotation277 278### Data Flow279 2801. **User Query** → FastAPI endpoint2812. **RAG Pipeline** → Vector similarity search2823. **Context Retrieval** → Top-k relevant recipes2834. **LLM Generation** → Context-aware response2845. **Memory Storage** → Conversation persistence2856. **Response** → JSON formatted reply286 287## 📊 Logging288 289Comprehensive logging system with:290 291- **File Rotation**: 10MB max size, 5 backups292- **Structured Format**: Timestamps, levels, source location293- **Emoji Indicators**: Visual status indicators294- **Error Tracking**: Full stack traces for debugging295 296**Log Levels:**297- 🚀 **INFO**: Normal operations298- ⚠️ **WARNING**: Non-critical issues299- ❌ **ERROR**: Failures with stack traces300- 🔧 **DEBUG**: Detailed operation steps301 302**Log Location:** `./logs/recipe_bot.log`303 304## 📁 Data Management305 306### Recipe Data307- **Location**: `./data/recipes/`308- **Format**: JSON files with structured recipe data309- **Schema**: title, ingredients, directions, tags310- **Auto-loading**: Automatic chunking and vectorization311 312### Vector Storage313- **ChromaDB**: Local persistence in `./data/chromadb_persist/`314- **MongoDB**: Cloud-based vector search315- **Embeddings**: Configurable embedding models316- **Retrieval**: Top-k similarity search (k=25)317 318## 🔧 Development319 320### Running in Development321```bash322# Install dependencies323pip install -r requirements.txt324 325# Set up environment326cp .env.example .env327# Configure your API keys328 329# Run with auto-reload330uvicorn app:app --reload --host 127.0.0.1 --port 8080331```332 333### Testing Individual Components334```bash335# Test vector store336python -c "from services.vector_store import vector_store_service; print('Vector store initialized')"337 338# Test LLM service339python -c "from services.llm_service import llm_service; print('LLM service initialized')"340```341 342### Adding New Recipes3431. Add JSON files to `./data/recipes/`3442. Set `DB_REFRESH_ON_START=true` in `.env` file3453. Restart the application (ChromaDB will be recreated)3464. Set `DB_REFRESH_ON_START=false` to prevent repeated deletion3475. New recipes are now available for search348 349**Quick refresh:**350```bash351# Enable refresh, restart, then disable352echo "DB_REFRESH_ON_START=true" >> .env353uvicorn app:app --reload --host 127.0.0.1 --port 8080354# After startup completes:355sed -i 's/DB_REFRESH_ON_START=true/DB_REFRESH_ON_START=false/' .env356```357 358## 🚀 Production Deployment359 360### Environment Setup361```bash362ENVIRONMENT=production363DEBUG=false364LOG_LEVEL=INFO365```366 367### Docker Deployment368The backend is containerized and ready for deployment on platforms like Hugging Face Spaces.369 370### Security Features371- **Environment Variables**: Secure API key management372- **CORS Configuration**: Frontend integration protection  373- **Input Sanitization**: Context-appropriate validation for recipe queries374  - XSS protection through HTML encoding375  - Length validation (1-1000 characters)376  - Basic harmful pattern removal377  - Whitespace normalization378- **Pydantic Validation**: Type safety and automatic sanitization379- **Structured Error Handling**: Safe error responses without data leaks380 381## 🛠️ Troubleshooting382 383### Common Issues384 385**Vector store initialization fails**386- Check API keys for embedding provider387- Verify data folder contains recipe files388- Check ChromaDB permissions389 390**LLM service fails**391- Verify API key configuration392- Check provider-specific requirements393- Review logs for detailed error messages394 395**HuggingFace model import errors**396- HuggingFace APIs have proven unreliable for production use397- **Recommended**: Use Ollama to run HuggingFace models locally instead:398  ```bash399  # Install and run HuggingFace models via Ollama400  ollama pull codeqwen:7b401  ollama pull mistral-nemo:12b402  # Set LLM_PROVIDER=ollama in .env403  ```404- For legacy HuggingFace API setup, uncomment dependencies in `requirements.txt` (not recommended)405- For detailed model comparisons, see [`docs/model-selection-guide.md`](docs/model-selection-guide.md)406 407**Memory issues**408```bash409# Clear conversation memory410curl -X POST http://localhost:8080/clear-memory411```412 413### Debug Mode414Set `DEBUG=true` in `.env` for detailed logging and error traces.415 416### Log Analysis417Check `./logs/recipe_bot.log` for detailed operation logs with emoji indicators for quick status identification.418 419## 📚 Documentation420 421### Troubleshooting Guides422- **[Embedding Troubleshooting](./docs/embedding-troubleshooting.md)** - Quick fixes for common embedding dimension errors423- **[Embedding Compatibility Guide](./docs/embedding-compatibility-guide.md)** - Comprehensive guide to embedding models and dimensions424- **[Logging Guide](./docs/logging_guide.md)** - Understanding the logging system425 426### Technical Guides427- **[Architecture Documentation](./docs/architecture.md)** - System architecture overview428- **[API Documentation](./docs/api-documentation.md)** - Detailed API reference429- **[Deployment Guide](./docs/deployment.md)** - Production deployment instructions430 431### Common Issues432- **Dimension mismatch errors**: See [Embedding Troubleshooting](./docs/embedding-troubleshooting.md)433- **Model loading issues**: Check provider configuration in `.env`434- **Database connection problems**: Verify MongoDB/ChromaDB settings435 436## 📚 Dependencies437 438### Core Dependencies439- **FastAPI**: Modern web framework440- **uvicorn**: ASGI server441- **pydantic**: Data validation442- **python-dotenv**: Environment management443 444### AI/ML Dependencies445- **langchain**: LLM framework and chains446- **langchain-openai**: OpenAI integration447- **langchain-google-genai**: Google AI integration448- **sentence-transformers**: Embedding models449- **chromadb**: Vector database450- **pymongo**: MongoDB integration451 452### Optional Dependencies453- **langchain-huggingface**: HuggingFace integration454- **torch**: PyTorch for local models455 456## 📄 License457 458This project is part of the PLG4 Recipe Recommendation Chatbot system.459 460---461 462For more detailed documentation, check the `docs/` folder or visit the API documentation at `http://localhost:8080/docs` when running the server.