🎓 Educational RAG Lab

An enterprise-grade RAG system for learning and experimentation - Built with modern AI architecture

📘 Read Current Status | View Changelog - Latest features and improvements

---

🌟 What is This?

The Educational RAG Lab is a production-ready reference architecture for LLM deployments, designed for hands-on learning and customer demonstrations. It features:

• 14 Microservices - Complete production-grade RAG architecture
• Modern React UI - TypeScript, Tailwind CSS, real-time streaming
• Performance Waterfall Chart - Visualize RAG pipeline latency breakdown
• Authentication System - JWT-based user auth with security controls
• Citation Validation - Hallucination detection for accurate sourcing
• Baseline Prompts - Pre-built queries for performance testing
• Configuration Toggles - UI controls for all RAG features
• Security Guardrails - PII detection, rate limiting, input sanitization
• Research Agent - Autonomous AI paper discovery and ingestion
• Comprehensive Documentation - Architecture, deployment, testing guides

Unique Value:

"This isn't just a RAG lab - it's a reference architecture for production LLM deployments, instrumented for Splunk from day one."

Perfect for:

• 🎯 Splunk/Cisco Field Teams - Architects, SEs, Sales Leaders
• 🎓 Students - Learning RAG, LLMs, and production AI
• 👨‍🏫 Instructors - Teaching enterprise AI deployment
• 🔬 Researchers - Experimenting with RAG configurations
• 👨‍💻 Developers - Building production RAG systems

---

☁️ AWS EC2 Deployment (Recommended for Production)

Launch on GPU-enabled EC2 with automated setup:

With vLLM Support (g5.2xlarge - NVIDIA A10G)

cd aws/scripts
./setup-github-secret.sh  # One-time security setup
./launch-g5-vllm.sh        # Launch with vLLM + Ollama

• ✅ vLLM - 2x faster inference (Ampere GPU)
• ✅ 24GB VRAM - Larger models (13B+)
• ✅ Cost: ~$29/day running, ~$0.65/day stopped

Ollama Only (g4dn.2xlarge - NVIDIA T4)

cd aws/scripts
./setup-github-secret.sh   # One-time security setup
./aws-launch-rag-lab.sh    # Launch with Ollama

• ✅ Ollama - Cost-effective development
• ✅ 16GB VRAM - Small/medium models (7B)
• ✅ Cost: ~$18/day running, ~$0.50/day stopped

Features:

• ✅ Automated deployment (10-20 minutes)
• ✅ Secure private repo access (AWS Secrets Manager)
• ✅ No SSH needed (AWS Session Manager)
• ✅ Stop when not using (save 97-98%!)

📘 AWS README | GPU Compatibility Guide | Security Best Practices

---

🚀 Quick Start (One Command!)

Fresh Deployment (Recommended)

# 1. Clone the repo
git clone https://github.com/sandbreak80/rag_lab.git
cd rag_lab/scripts

# 2. Run the clean deployment script
./clean-deploy.sh

This will:

• ✅ Stop all containers & prune Docker
• ✅ Build fresh images (no cache)
• ✅ Start Ollama with GPU support
• ✅ Pull required models (llama3.1:8b + nomic-embed-text)
• ✅ Prompt for 8 optional models (for lab exercises)
• ✅ Start all 14 microservices
• ✅ Verify health checks

Total time: 15-30 minutes (depending on model downloads)

Quick Start (Existing Install)

cd rag_lab/scripts
./build-and-start.sh

No npm, Node.js, Python, or other host dependencies needed. Everything runs in Docker.

Time: ~5-10 minutes (first run with model downloads)

Access the Application

• Frontend (React UI): http://localhost:3000
• API Gateway: http://localhost:8000
• Ollama: http://localhost:11434
• SearXNG (Web Search): http://localhost:8080

Stop Everything

cd scripts
./stop.sh

Clean Start (Fresh Install)

# Remove all data and rebuild
./build-and-start.sh --clean

Docker Compose Commands

# View logs
docker compose logs -f

# Restart a service
docker compose restart frontend

# Check service status
docker compose ps

---

📚 Documentation

• 🚀 Quick Start Guide - Get up and running in minutes
• 🎯 Model Selection Guide - Choose the right model for your use case
• 🖥️ GPU Setup - NVIDIA GPU configuration
• 🐧 Ubuntu Deployment - Server deployment guide
• 📖 Complete Project Summary - Everything we built

---

✨ Key Features

🎛️ Interactive Settings Panel

• 6 Quick Presets: Minimal → Fast → Balanced → Quality → Maximum → Production
• 6 RAG Toggles: Query Expansion, BM25, Hybrid, Knowledge Graph, Re-ranking, Web Search
• 4 LLM Settings: Model selection, Temperature, Max Tokens, Context Window
• Real-time Preview: See expected performance before running

📊 Real-time Metrics Dashboard

• Component Breakdown: See exactly where time is spent
• Performance Tracking: Latency, precision, recall estimates
• Visual Indicators: Color-coded status and percentage breakdowns
• Expandable Details: Deep dive into each component's performance

⚖️ A/B Comparison Mode

• Side-by-side Comparison: Test two configurations simultaneously
• Automatic Winner: System determines the better config
• Intelligent Insights: AI-generated analysis of differences
• One-click Switch: Apply either configuration instantly

📖 Progressive Lab Guide

• 6 Interactive Sections: From beginner to advanced
• Progress Tracking: Save your learning progress
• Hands-on Activities: Learn by doing
• Checkpoints: Verify understanding at each step

---

📊 Configuration Presets

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     WEB UI (Port 5555)                       │
│  Settings Panel | Metrics Dashboard | Comparison | Lab Guide │
└────────────────────────────┬────────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
    ┌─────▼─────┐     ┌─────▼──────┐    ┌─────▼─────┐
    │  Search   │     │   Ingest   │    │  Vector   │
    │  Service  │     │  Service   │    │    DB     │
    │  (8002)   │     │   (8001)   │    │  (8005)   │
    └─────┬─────┘     └────────────┘    └───────────┘
          │
    ┌─────┴─────────────┐
    │                   │
┌───▼────┐  ┌──────▼──────┐  ┌────────▼────────┐
│Knowledge│  │  Reranker   │  │   Web Search    │
│  Graph  │  │   (8008)    │  │ (8009 + 8080)   │
│ (8007)  │  └─────────────┘  └─────────────────┘
└─────────┘           │
              ┌───────▼────────┐
              │  Ollama (LLM)  │
              │    (11434)     │
              └────────────────┘

10 Microservices working together to provide a complete RAG experience.

📖 Full Architecture Documentation: docs/ARCHITECTURE.md

---

🎓 Learning Path

1. Interactive Lab Guide (1-2 hours)

Built into the UI (📖 button) with 6 progressive sections:

1. Getting Started - Understand the interface
2. Your First Query - Execute searches
3. Understanding Metrics - Read performance data
4. Configuration Experiments - A/B testing
5. Advanced Features - Graph, re-ranking, web search
6. Production Configuration - Deploy-ready system

2. Student Exercises (3-4 hours)

10 comprehensive exercises with grading rubric:

• Exercise 1: Baseline Performance
• Exercise 2: Hybrid Search Benefits
• Exercise 3: Performance Profiling
• Exercise 4: Re-ranking Trade-offs
• Exercise 5: Web Search Integration
• Exercise 6: Configuration Optimization
• Exercise 7: A/B Testing
• Exercise 8: Production Deployment
• Exercise 9: Cost Analysis
• Exercise 10: Final Challenge

📖 Student Exercises: docs/lab/STUDENT_EXERCISES.md

3. Technical Deep Dive

Complete system documentation:

• Architecture and design patterns
• API reference for all endpoints
• Performance benchmarks
• Deployment guides
• Development practices

📖 Comprehensive Documentation: docs/COMPREHENSIVE_DOCUMENTATION.md

---

🛠️ Technology Stack

• Backend: Python, Flask
• Vector Database: ChromaDB
• LLM: Ollama (llama3.2)
• Search: Hybrid (Vector + BM25)
• Knowledge Graph: NetworkX
• Web Search: SearXNG
• Document Processing: Docling
• Containerization: Docker & Docker Compose
• Frontend: Vanilla JavaScript, CSS

---

📦 What's Included

rag_lab/
├── docs/                          # Documentation
│   ├── lab/                       # Student learning materials
│   │   ├── QUICK_START.md         # 5-minute setup
│   │   ├── LAB_GUIDE.md           # Interactive guide
│   │   ├── STUDENT_EXERCISES.md   # 10 exercises
│   │   └── LAB_OBJECTIVES.md      # Learning goals
│   ├── development/               # Developer docs
│   ├── deployment/                # Deployment guides
│   └── COMPREHENSIVE_DOCUMENTATION.md
├── services/                      # 10 microservices
│   ├── search/                    # Hybrid search orchestration
│   ├── vector-db/                 # ChromaDB wrapper
│   ├── ingest/                    # Document processing
│   ├── knowledge-graph/           # Graph service
│   ├── reranker/                  # LLM re-ranking
│   ├── web-search/                # SearXNG wrapper
│   └── ...
├── src/                           # Web UI
│   ├── webapp.py                  # Flask server
│   ├── templates/                 # HTML templates
│   └── static/                    # CSS, JavaScript
├── config/                        # Configuration
│   ├── presets.json               # 6 presets
│   └── searxng/                   # SearXNG config
├── tests/                         # Integration tests
│   └── test_integration.py        # 20+ tests (no mocks)
├── docker-compose.test.yml        # Orchestration
└── README.md                      # This file

---

🧪 Testing

Run the integration test suite (no mocks, real services):

# Services must be running
docker-compose -f docker-compose.test.yml up -d

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install pytest requests

# Run tests
pytest tests/test_integration.py -v

20+ integration tests covering:

• Service health checks
• Configurable search with all presets
• Web search integration
• Knowledge graph
• LLM re-ranking
• End-to-end RAG flow
• Metrics accuracy

---

📚 Documentation

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Code of conduct
• How to submit issues
• Pull request process
• Development setup
• Coding standards

---

📋 Requirements

• Docker and Docker Compose
• Ollama running locally (port 11434)
• 8GB+ RAM (recommended)
• 10GB+ disk space
• Python 3.8+ (for testing)

---

🐛 Troubleshooting

Services Won't Start

docker ps
docker logs rag-web-ui

Ollama Connection Failed

curl http://localhost:11434/api/tags

No Search Results

Upload documents first via the UI (drag-and-drop).

Web Search Timeout

Check SearXNG: curl http://localhost:8080/search?q=test&format=json

📖 Full Troubleshooting Guide: docs/COMPREHENSIVE_DOCUMENTATION.md#troubleshooting

---

📄 License

MIT License - see LICENSE file for details.

TL;DR: Free to use, modify, and deploy. Including commercially.

---

🙏 Acknowledgments

Built with:

• Flask - Web framework
• ChromaDB - Vector database
• Ollama - Local LLM
• SearXNG - Metasearch engine
• Docling - Document processing
• NetworkX - Knowledge graph
• Rank-BM25 - Keyword search

---

📞 Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/
• Email: [Your Contact]

---

🎯 Project Status

✅ Production Ready (v1.0.0)

• ✅ All 10 microservices operational
• ✅ All 6 presets tested
• ✅ Complete documentation (40,000+ words)
• ✅ Student exercises ready
• ✅ Integration tests passing
• ✅ Web search integrated
• ✅ A/B comparison working
• ✅ Lab guide complete

---

🚀 Next Steps

1. Quick Start: docs/lab/QUICK_START.md
2. Open UI: http://localhost:5555
3. Follow Lab Guide: Click 📖 button in UI
4. Complete Exercises: docs/lab/STUDENT_EXERCISES.md
5. Deploy: Use Production preset 🏆

---

⭐ Star this repo if you find it useful!

Built with ❤️ for education

Educational RAG Lab v1.0.0 - Interactive Learning Environment for RAG Systems