🎓 RAG Playground

An interactive, educational web application for learning and comparing different Retrieval-Augmented Generation (RAG) architectures. Built with Next.js 15, TypeScript, and Supabase.

🌟 Overview

RAG Playground is a hands-on learning platform that helps you understand how different RAG architectures work by:

• Comparing 5 RAG architectures side-by-side in real-time
• Streaming execution timelines showing each step as it happens
• Interactive controls to tune parameters and see their effects
• Educational content explaining the theory behind each approach

Perfect for developers, researchers, and anyone learning about RAG systems!

🚀 Features

5 RAG Architectures

1. Standard RAG - Baseline vector similarity search
2. Advanced RAG - Query expansion with multi-query retrieval and reranking
3. Hybrid RAG - Combines semantic (vector) and keyword (full-text) search using RRF
4. Agentic RAG - Autonomous agent with planning, self-evaluation, and iteration
5. GraphRAG - Entity-relationship extraction with knowledge graph traversal

Real-Time Execution Timeline

Watch each RAG mode execute step-by-step in real-time:

• See embeddings generated
• Track similarity searches
• Monitor LLM calls
• View performance metrics
• Understand the complete flow

Interactive Comparison Mode

• Run two RAG modes side-by-side with the same query
• Compare speed, quality, and approach
• Adjust parameters (threshold, max tokens, model)
• View detailed sources and execution steps

Advanced Configuration

• Dynamic embedding models - Choose from 3 OpenAI models
• Adjustable chunk size/overlap - Optimize for your use case
• Similarity threshold control - Fine-tune retrieval precision
• Token output limits - Control response length
• Model selection - Currently supports GPT-4o-mini

Developer-Friendly

• Dark mode support
• Responsive design (mobile to desktop)
• Smart logging (no spam for large files)
• Type-safe TypeScript throughout
• Modular, maintainable codebase
• Optional LangSmith integration - Trace & debug RAG queries (not embeddings)
• Server-Sent Events (SSE) for real-time progress updates

📋 Requirements

• Node.js 18+ (20+ recommended)
• pnpm 8+ or npm 9+
• Supabase account (free tier works!)
• OpenAI API key with access to GPT-4o models

🛠️ Installation

1. Clone the Repository

git clone https://github.com/yourusername/rag-playground.git
cd rag-playground

2. Install Dependencies

Using pnpm (recommended):

pnpm install

Or using npm:

npm install

3. Set Up Supabase

1. Create a new project at supabase.com

2. Go to Settings → API and copy:

   • Project URL
   • service_role key (not anon key!)

3. Run the database setup in the Supabase SQL Editor:

Go to your Supabase project → SQL Editor → New Query

Copy the contents of supabase/migrations/000_complete_setup.sql and paste it into the editor, then click Run.

This single migration creates:

• ✅ pgvector extension
• ✅ documents and document_chunks tables
• ✅ Vector similarity indexes
• ✅ match_document_chunks() function (for Standard/Advanced/Agentic/GraphRAG)
• ✅ hybrid_search() function (for Hybrid RAG)
• ✅ Row Level Security policies

📋 View the complete SQL (click to expand)

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create documents table
CREATE TABLE IF NOT EXISTS documents (
  id UUID PRIMARY KEY,
  filename TEXT NOT NULL,
  content TEXT NOT NULL,
  file_type TEXT,
  uploaded_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  metadata JSONB DEFAULT '{}'::jsonb
);

-- Create document_chunks table with vector embeddings
CREATE TABLE IF NOT EXISTS document_chunks (
  id UUID PRIMARY KEY,
  document_id UUID REFERENCES documents(id) ON DELETE CASCADE,
  content TEXT NOT NULL,
  embedding vector(1536),
  chunk_index INTEGER NOT NULL,
  total_chunks INTEGER NOT NULL,
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create indexes
CREATE INDEX IF NOT EXISTS document_chunks_embedding_idx 
ON document_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

CREATE INDEX IF NOT EXISTS document_chunks_document_id_idx 
ON document_chunks(document_id);

-- Create similarity search function
CREATE OR REPLACE FUNCTION match_document_chunks(
  query_embedding vector(1536),
  match_threshold FLOAT DEFAULT 0.5,
  match_count INT DEFAULT 5
)
RETURNS TABLE (id UUID, document_id UUID, content TEXT, similarity FLOAT, metadata JSONB)
LANGUAGE plpgsql AS $$
BEGIN
  RETURN QUERY
  SELECT dc.id, dc.document_id, dc.content,
    1 - (dc.embedding <=> query_embedding) AS similarity, dc.metadata
  FROM document_chunks dc
  WHERE 1 - (dc.embedding <=> query_embedding) > match_threshold
  ORDER BY dc.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;

-- Create hybrid search function (full SQL in file)
CREATE OR REPLACE FUNCTION hybrid_search(...) RETURNS TABLE (...) LANGUAGE sql AS $$ ... $$;

-- Enable RLS and create policies
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE document_chunks ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Allow all operations on documents" ON documents FOR ALL USING (true);
CREATE POLICY "Allow all operations on document_chunks" ON document_chunks FOR ALL USING (true);

-- Grant permissions
GRANT EXECUTE ON FUNCTION match_document_chunks TO authenticated, anon, service_role;
GRANT EXECUTE ON FUNCTION hybrid_search TO authenticated, anon, service_role;

💡 Troubleshooting: If you get any errors, make sure you're using the service_role key in your .env.local (not the anon key).

4. Configure Environment Variables

Create a .env.local file in the root directory:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# OpenAI
OPENAI_API_KEY=your_openai_api_key

# Optional: LangSmith (for tracing & debugging)
# LANGCHAIN_TRACING_V2=true
# LANGCHAIN_API_KEY=your_langsmith_api_key
# LANGCHAIN_PROJECT=rag-playground

⚠️ Important: Use the service_role key for SUPABASE_SERVICE_ROLE_KEY, not the anon key!

💡 Optional: LangSmith provides tracing and observability for debugging RAG operations. The app works perfectly fine without it. Free tier: 5,000 traces/month.

5. Run the Development Server

Using pnpm:

pnpm dev

Or using npm:

npm run dev

Open http://localhost:3000 in your browser.

📖 Usage

1. Upload Documents

• Click the Documents tab in the sidebar
• Select embedding model (text-embedding-3-small recommended)
• Adjust chunk size/overlap if needed (Advanced Settings)
• See estimated cost before uploading
• Drag & drop files or click to upload
• Watch real-time progress: Text extraction → Chunking → Embedding generation
• Supported formats: .txt, .md, .pdf, .docx

New Features:

• 📊 Live Progress Tracking - See exactly what's happening during upload
• 💰 Cost Estimation - Know the embedding cost before you upload
• 📄 PDF Support - Powered by LangChain's WebPDFLoader
• 🔒 Smart Error Handling - Helpful messages for encrypted PDFs and other issues

💡 Quick Start: A sample document is included at public/Sample_RAG_Paper.md — a comprehensive paper on RAG architectures perfect for testing!

2. Compare RAG Modes

• Select Left Mode and Right Mode from the comparison panel
• Adjust Threshold (0-100%) - higher = more strict matching
• Adjust Max Tokens (100-2000) - control response length
• Select Model (currently gpt-4o-mini)
• Enter your question
• Click Run Left, Run Right, or Run Both

3. Watch Execution Timeline

• Each mode shows a real-time Execution Timeline
• Expand to see detailed metrics for each step
• Learn how different RAG approaches work under the hood

4. Learn About RAG

• Click the Docs tab in the sidebar
• Read Overview for detailed architecture explanations
• Understand when to use each RAG mode
• Learn about trade-offs between speed, quality, and complexity

🏗️ Architecture

rag-playground/
├── app/
│   ├── api/
│   │   ├── documents/        # Document upload & management
│   │   └── rag/
│   │       ├── modes/        # Non-streaming RAG implementations
│   │       │   ├── standard.ts
│   │       │   ├── advanced.ts
│   │       │   └── hybrid.ts
│   │       ├── streaming/    # Streaming RAG implementations
│   │       │   ├── standard-stream.ts
│   │       │   ├── advanced-stream.ts
│   │       │   ├── hybrid-stream.ts
│   │       │   ├── agentic-stream.ts
│   │       │   └── graph-stream.ts
│   │       └── query/        # Main query endpoint
│   └── page.tsx              # Main app component
├── components/
│   ├── comparison-mode.tsx   # Side-by-side comparison UI
│   ├── execution-timeline.tsx # Real-time step visualization
│   ├── file-upload.tsx       # Document upload component
│   ├── learn-content.tsx     # Educational content
│   └── rag-response-display.tsx # Response renderer
├── lib/
│   ├── openai.ts             # OpenAI client config
│   ├── supabase.ts           # Supabase client config
│   └── logger.ts             # Structured logging utility
└── types/
    └── rag.ts                # TypeScript type definitions

🧪 How It Works

Standard RAG

1. Generate query embedding (1536 dimensions)
2. Vector similarity search in Supabase
3. Retrieve top-K chunks above threshold
4. Generate answer with LLM

Advanced RAG

1. Query expansion (generate 2 alternative phrasings)
2. Multi-query retrieval (3 parallel searches)
3. Deduplicate and rerank by similarity
4. Generate answer with enhanced context

Hybrid RAG

1. Generate query embedding
2. Parallel execution:
   • Semantic search (vector similarity)
   • Keyword search (full-text)
3. Merge results using Reciprocal Rank Fusion (RRF)
4. Generate answer with hybrid context

Agentic RAG

1. Autonomous Planning - Analyze query complexity, choose strategy
2. Adaptive Retrieval - Execute chosen strategy (semantic or expansion)
3. Self-Evaluation - Assess quality, re-retrieve if needed
4. Answer Generation - Generate response with optimized context

GraphRAG

1. Entity Extraction - Identify 2-4 key entities from query
2. Multi-Entity Search - Independent searches per entity
3. Relationship Discovery - Find connections between entities
4. Graph-Aware Answer - Generate response with relationship context

🎯 Use Cases

RAG Mode	Best For	Speed	Quality
Standard	Simple Q&A, speed-critical	⚡⚡⚡	⭐⭐
Advanced	Better recall, diverse phrasings	⚡⚡	⭐⭐⭐
Hybrid	Exact terms + semantic meaning	⚡⚡⚡	⭐⭐⭐
Agentic	Complex reasoning, adaptive	⚡	⭐⭐⭐⭐
GraphRAG	Relationship questions	⚡	⭐⭐⭐⭐

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please ensure:

• Code follows TypeScript best practices
• All linting passes (pnpm lint)
• Components are properly typed
• New features include appropriate logging

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Next.js and TypeScript
• Vector database powered by Supabase with pgvector
• LLM integration via OpenAI and LangChain
• UI components from shadcn/ui
• Icons by Lucide

📧 Contact

Questions? Feedback? Open an issue or reach out!

---

Made with ❤️ for the RAG community

⭐ If you find this project helpful, please star it on GitHub!