Documents ──► Ingestion ──► ChromaDB (vector store)
                   │                                │
              Chunking                          Hybrid Search
              Embeddings                     ┌────┴────┐
                                           Vector    BM25
                                             └──┬───┘
                                            RRF Fusion
                                                │
                                          Cross-encoder
                                                │
                                           Results ──► MCP Server ──► LLM

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# (Optional) Install in dev mode for test dependencies
pip install -e .[dev]

# Index all documents
python -m rag ingest

# Or run the ingestion script directly
python rag/ingestion.py

2026-07-28  [INFO]  Indexing documents...
2026-07-28  [INFO]  Processing  Day 1.md
2026-07-28  [INFO]    └─ 8 chunk(s)
2026-07-28  [INFO]  Processing  Day 2.md
2026-07-28  [INFO]    └─ 6 chunk(s)
...
2026-07-28  [INFO]  Indexing complete — 247 total chunk(s) in collection

python mcp-servers/rag-mcp/server.py

python -m rag search

RAG interactive search — type :q to quit.

query> What is the difference between AI and ML?

Artificial Intelligence (AI) is the broad field of creating machines that...

query> :q

python -m rag evaluate
# With cross-encoder reranking:
python -m rag evaluate --rerank

  MRR       = 0.8923
  Recall@1  = 0.8276
  Recall@3  = 0.9655
  Recall@5  = 1.0000

pytest

# With verbose output
pytest -v

# With coverage
pip install pytest-cov
pytest --cov=rag tests/

# Windows
start_rag.bat

# Linux / macOS
bash scripts/start.sh

├── rag/                          # Core RAG library
│   ├── __init__.py               # Package init
│   ├── __main__.py               # CLI entry point (python -m rag)
│   ├── settings.py               # Central configuration
│   ├── ingestion.py              # Document indexing pipeline
│   ├── retrieval.py              # Hybrid search (vector + BM25 + reranker)
│   ├── evaluate.py               # Retrieval evaluation (MRR, Recall@K)
│   ├── chroma_db/                # Persistent vector store (gitignored)
│   ├── documents/                # Place your documents here
│   │   └── 30 days md/           # Pre-bundled Data Science tutorials (29 Q&A test cases)
│   └── test_set.json             # Curated Q&A test cases
├── mcp-servers/
│   └── rag-mcp/
│       └── server.py             # MCP server exposing search tool
├── tests/                        # Test suite (pytest)
│   ├── test_ingestion.py
│   ├── test_retrieval.py
│   └── test_evaluate.py
├── scripts/
│   └── start.sh                  # Linux/macOS startup script
├── start_rag.bat                 # Windows startup script
├── pyproject.toml                # Project metadata & packaging
├── requirements.txt              # Python dependencies
├── .gitignore
└── README.md