A retrieval-augmented Q&A bot that lets you chat with any local codebase in plain English and get answers grounded in the actual source — with file:line citations for every claim.

Runs entirely on your machine: embeddings and chat completion both go through Ollama, so there are no API keys, no per-query cost, and no code ever leaves your laptop.

Index multiple repos, switch between them instantly, and ask things like "how does the generator model work?" or "how is the dataset loaded for training?" — the bot retrieves the relevant functions/files and answers using only that context.

Above: indexing telco-churn-mlops and asking it a question about the FastAPI serving layer — the answer cites the exact files/line ranges it drew from.

This is a local-first tool by design (see "Why local, not hosted" below), so there's no live demo link — the GIF above is the fastest way to see it in action without installing anything.

Most "chat with your docs" RAG demos point at PDFs. This one points at code — chunking is AST-aware for Python (one chunk per function/class, not arbitrary line slices), so retrieval returns whole, coherent functions and the model can cite exactly where an answer came from.

This project is intentionally not deployed to a public server. Two reasons, both structural rather than incidental:

1. It indexes an absolute filesystem path. The whole point is pointing it at a codebase sitting on your machine — a hosted version would have no access to a visitor's local repos, so a "live demo" would only ever be able to index itself.
2. The privacy/cost model is the feature. Embeddings and generation both run through Ollama on-device — no API keys, no per-query cost, no code leaving the laptop. Swapping in a hosted LLM to make it publicly demoable would remove the property that makes it worth building.

 ┌─────────────┐     ┌──────────────┐     ┌────────────────┐
 │  chunker.py │ --> │ vectorstore  │ --> │   Chroma DB     │
 │ (AST split) │     │ (embeddings) │     │ (per-repo coll) │
 └─────────────┘     └──────────────┘     └────────────────┘
                                                    │
   question ──> embed ──> similarity search ───────┘
                                │
                          top-k chunks
                                │
                                v
                   ┌────────────────────────┐
                   │  qwen2.5-coder:1.5b    │  (via Ollama)
                   │  "answer using only    │
                   │   this context, cite   │
                   │   file:line sources"   │
                   └────────────────────────┘
                                │
                                v
                    answer + cited sources

1. Chunking (chunker.py) — Python files are split per function/class via ast; other text files (.md, .js, .yaml, etc.) fall back to overlapping line windows.
2. Indexing (indexer.py, vectorstore.py, registry.py) — each chunk is embedded with nomic-embed-text and stored in its own Chroma collection per repo, so multiple codebases can be indexed once and switched between without re-indexing.
3. Retrieval + generation (rag.py) — a question is embedded, the top-k most similar chunks are retrieved, and qwen2.5-coder:1.5b answers using only that retrieved context.
4. Serving (main.py + static/index.html) — a FastAPI backend exposes /index, /repos, and /chat, with a minimal chat UI (including a repo switcher) served at /.

# 1. Install Ollama (https://ollama.com) and pull the models used here
ollama pull qwen2.5-coder:1.5b
ollama pull nomic-embed-text

# 2. Python environment
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

open -a Ollama                                      # start the local model server
.venv/bin/uvicorn main:app --port 8008               # start the API + UI

Open http://127.0.0.1:8008. Paste an absolute path to any local repo into the "Index repo" box and click Index repo. Once indexed, pick it from the Active repo dropdown and start asking questions.

To stop everything:

pkill -f "uvicorn main:app"
pkill -f "ollama serve"      # optional, frees RAM

.venv/bin/python indexer.py /path/to/some/repo --reset

curl -X POST http://127.0.0.1:8008/repos          # list indexed repos

curl -X POST http://127.0.0.1:8008/chat \
  -H "Content-Type: application/json" \
  -d '{"repo_path": "/path/to/repo", "question": "How does the generator model work?"}'

Python · FastAPI · Ollama (qwen2.5-coder:1.5b, nomic-embed-text) · ChromaDB · vanilla JS

• Small-model hallucination: when a question has no real answer in the indexed repo, qwen2.5-coder:1.5b sometimes fabricates a plausible-sounding answer instead of saying "not found" — despite an explicit system-prompt instruction not to guess. This is a known trade-off of small local models; refusal-following improves significantly with larger models (e.g. qwen2.5-coder:7b) or stricter prompt constraints.
• Plain cosine retrieval: no reranking is applied, so the top-k chunks occasionally include topically-adjacent but not directly relevant code (the LLM generally filters this out, but not always).
• Each indexed repo's vector data lives in ./chroma_db (gitignored) and the repo registry in ./repos.json (also gitignored) — both are local state, not committed.

pip install pytest httpx fastapi==0.115.0 pydantic==2.9.2 ollama==0.3.3
pytest -q      # 21 tests, <1 s, no Ollama or Chroma required

Covers the AST chunker (exact line ranges, citations, syntax-error fallback, ignored dirs), collection naming and batching, prompt construction, the empty-index guard (the LLM is never called), the repo registry, and the FastAPI endpoints (index, chat, 404 and validation errors). Ollama and Chroma are mocked, so CI runs in seconds. Answer quality is not covered by these tests; see the hallucination note below.

• Swap in a larger Ollama model for better answer quality/refusal behavior.
• Add reranking (e.g. cross-encoder) on top of the initial vector retrieval.
• Stream responses token-by-token instead of waiting for the full completion.