Build, inspect, and benchmark a local RAG pipeline where
retrieval results, prompts, citations, and generated answers stay fully visible.
✨ Overview · 🏗️ Architecture · 🚀 Quickstart · 🔎 Retrieval · 🧾 RAG & Citations
🧪 Experiments · 🖥️ Playground · ⚡ API · ⚙️ Config · 🛠️ Troubleshooting
The guide is split into focused pages so the root README stays clean and quick to scan.
Use this map to jump directly into setup, architecture, retrieval, experiments, API usage, or debugging.
| Section | What you will find | Open |
|---|---|---|
| ✨ Overview | Project purpose, local-first RAG flow, and what the system exposes for debugging. | Read overview |
| 🏗️ Architecture | Pipeline layers, component responsibilities, and how retrieval connects to generation. | View architecture |
| 🚀 Quickstart | Setup order for Docker, Weaviate, Python, Ollama, indexing, API, and frontend. | Start here |
| 🔍 Retrieval modes | BM25, dense MiniLM, hybrid search, top_k, and alpha tuning. |
Compare retrievers |
| 📝 RAG & citations | Prompt context, chunk IDs, valid citations, invalid citations, and validation logic. | Check grounding |
| 🧪 Experiments | Indexing, retrieval evaluation, sweeps, metrics, and repeatable run order. | Run experiments |
| 🖥️ Web playground | Browser workflow for inspecting chunks, scores, prompts, answers, and citations. | Use playground |
| ⚡ API | FastAPI routes for health, config, datasets, retrieval, and RAG generation. | Open API guide |
| 📊 Results | CSV, Markdown, JSON, plots, reports, and expected experiment artifacts. | Review outputs |
| ⚙️ Configuration | Dataset, retrieval, RAG, and sweep YAML settings. | Edit config |
| 🔧 Troubleshooting | Fixes for Weaviate, Ollama, ports, indexing, retrieval, frontend, and citations. | Debug issues |
| 🗺️ Roadmap | Planned improvements and future extensions. | See roadmap |
Note
For a first local run, start with the 🚀 Quickstart page.
For understanding the system design, start with 🏗️ Architecture and then continue with 🔍 Retrieval modes.
Figure 1. Local-first retrieval, evaluation, automation, and citation-aware generation.
Tip
The complete pipeline explanation is available in the Architecture guide.
Transparent retrieval. Local generation. Reproducible RAG experiments.
⭐ Star the repository if this project helps your work.