title	emoji	colorFrom	colorTo	sdk	pinned	license
Recipe Recommendation Chatbot	🥘	indigo	pink	docker	false	mit

🥘 Recipe Recommendation Chatbot

An AI-powered recipe recommendation system with intelligent chat interface, built using RAG (Retrieval Augmented Generation) and modern streaming architecture. Features intelligent caching for 70-90% cost reduction and memory-optimized streaming for production-grade performance.

✨ Key Features

🤖 Advanced AI Capabilities

• Multi-Provider LLM Support: OpenAI (GPT-5), Google (Gemini-2.5), Anthropic (Claude), Ollama (Local models)
• RAG Pipeline: Context-aware recipe recommendations with vector search
• Intent Classification: Smart routing for greetings, recipe queries, and cooking advice
• Streaming Responses: Real-time chat with memory-optimized architecture

🚀 Performance Optimizations

• Intelligent Caching: 70-90% API cost reduction with multi-layer caching
• Memory Safety: O(1) memory usage during streaming (no memory leaks)
• Real-time Monitoring: Cache performance and system health monitoring
• Production Ready: Comprehensive optimization and documentation

🗄️ Data & Storage

• Vector Databases: ChromaDB (local) and MongoDB Atlas (cloud) support
• Recipe Mining: Automated scraping from multiple Nigerian recipe sources
• Smart Embedding: Optimized embedding models for recipe similarity

🚀 Quick Start

Prerequisites

• Python 3.9+ (backend)
• Node.js 18+ (frontend)
• API keys for your chosen LLM provider

1. Backend Setup

# Navigate to backend
cd backend

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys and preferences

# Run the backend server
uvicorn app:app --reload --host 127.0.0.1 --port 8080

2. Frontend Setup

# Navigate to frontend
cd frontend

# Install dependencies
npm install
# or
yarn install

# Configure environment
cp .env.example .env
# Configure API endpoint

# Run the development server
npm run dev
# or  
yarn dev

3. Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080
• API Documentation: http://localhost:8080/docs
• Health Check: http://localhost:8080/health

📁 Project Architecture

chatbot/
├── 🎯 backend/              # FastAPI backend with RAG pipeline
│   ├── handlers/            # Request handlers (chat, health, jobs)
│   ├── services/            # Core services (LLM, caching, routing)
│   ├── config/             # Configuration and settings
│   ├── data_mining/        # Recipe scrapers and data collection
│   ├── utils/              # Utilities and helpers
│   ├── docs/               # Comprehensive backend documentation
│   └── tests/              # Backend test suite
│
├── 🖼️ frontend/             # Next.js frontend application
│   ├── app/                # Next.js app directory
│   ├── components/         # React components
│   ├── services/           # API integration services
│   ├── hooks/              # Custom React hooks
│   └── types/              # TypeScript type definitions
│
├── 📚 docs/                # Project-wide documentation
│   ├── architecture.md     # System architecture overview
│   ├── api-documentation.md # API reference
│   └── deployment.md       # Deployment guides
│
└── 🚀 deploy-to-hf.sh      # HuggingFace Spaces deployment script

🏗️ System Architecture

Backend Architecture (Handler-Based Design)

• Smart Response Router: Intent-based routing with cache-first lookup
• Memory-Optimized Streaming: Real-time responses without memory leaks
• Intelligent Caching: Multi-layer caching (LLM, embeddings, search results)
• Multi-Provider Support: Unified interface for OpenAI, Google, Anthropic, Ollama

Frontend Architecture (Modern React/Next.js)

• Next.js 15: Latest React framework with TypeScript support
• Real-time Streaming: AI SDK integration for streaming responses
• State Management: Zustand for efficient state handling
• Modern UI: Responsive design with Tailwind CSS

🔧 Configuration

LLM Provider Options

OpenAI (Best Value)

LLM_PROVIDER=openai
OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-5-nano  # Best value: $1/month for 30K queries

Google Gemini (Best Free Tier)

LLM_PROVIDER=google  
GOOGLE_API_KEY=your_api_key
GOOGLE_MODEL=gemini-2.5-flash  # Excellent free tier, then $2/month

Ollama (Privacy/Self-Hosting)

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b  # 4.7GB download, 8GB RAM

📚 For detailed configuration guides, see Backend Documentation

📚 Documentation

📖 Getting Started

• Backend Setup Guide - Complete backend setup and configuration
• Frontend Setup Guide - Frontend development and deployment
• System Architecture - High-level system design overview

🚀 Performance & Optimization

• Performance Optimization - Memory management and cost optimization
• Caching Strategy - 70-90% cost reduction implementation
• Architecture Details - Complete architectural documentation

🔧 Configuration & Setup

• Model Selection Guide - Choose the right LLM provider
• API Documentation - Complete API reference
• Deployment Guide - Production deployment instructions

🛠️ Development & Troubleshooting

• Backend Documentation Index - Complete backend documentation
• Embedding Troubleshooting - Fix common issues quickly
• Contributing Guidelines - Development workflow and contribution guidelines

🧪 Testing & Validation

Performance Validation

• Cache Hit Rate: 87.5% in testing scenarios
• Memory Stability: Tested with 1000+ consecutive requests
• API Cost Reduction: ~79% with intelligent caching
• Response Times: <50ms average for cached responses

🚀 Deployment

HuggingFace Spaces (Recommended)

./deploy-to-hf.sh your-hf-space-name

Local Production

# Backend
cd backend
uvicorn app:app --host 0.0.0.0 --port 8080

# Frontend  
cd frontend
npm run build && npm start

Docker Deployment

The backend includes Docker configuration for containerized deployment.

🔒 Security & Production Features

• Input Sanitization: XSS protection and length validation
• Environment Variable Protection: Secure API key management
• CORS Configuration: Frontend integration protection
• Health Monitoring: Real-time system status and alerting
• Error Handling: Graceful degradation and structured logging

📊 Performance Features

Cost Optimization

• Intelligent Caching: 70-90% reduction in LLM API costs
• Cache Warming: Automatic caching of popular queries
• Usage Monitoring: Real-time token usage and cost tracking

Memory Management

• Stream-First Architecture: No response accumulation
• Constant Memory Usage: O(1) memory during streaming
• Automatic Cleanup: TTL-based cache eviction

Real-time Performance

• Streaming Responses: Real-time chat experience
• Cache-First Lookup: <100ms for cached responses
• Health Monitoring: Real-time system metrics

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for:

• Development setup and workflow
• Code standards and best practices
• Testing requirements and procedures
• Pull request process

👥 Team

GenAI PLG 4 - Andela Community Program

📄 License

This project is licensed under the MIT License.