RepoRAG

POST /query
{
  "question": "how does dependency injection work?",
  "repo_name": "fastapi"
}

→ {
  "answer": "FastAPI's DI system works by...",
  "sources": [{"file_path": "fastapi/dependencies/utils.py", ...}],
  "metrics": {"total_latency_ms": 840, "chunks_retrieved": 12, ...}
}

GitHub URL
  → git clone --depth=1 (temp dir, auto-cleaned)
  → LocalRepoLoader.stream_files() → RawFile (one at a time, constant RAM)
  → WAL check: skip if already indexed (resume on crash)
  → CodeParser.parse(raw_file) → CodeChunk[], RawEdge[]
      Python: tree-sitter recursive walk, extracts functions/classes/imports
      JS/TS:  same, plus JSDoc extraction
      Other:  FallbackStrategy (line-based chunking, no symbol extraction)
  → Batch accumulate (batch_size=32 by default)
  → NomicEmbedder.embed_batch() → (vector_768[], vector_128[])
      One forward pass, two vectors via MRL truncation
  → LanceStore.add_chunks() — merge_insert on chunk_id (idempotent)
  → KuzuStore.add_nodes() — MERGE on chunk_id (idempotent)
  → WAL.record("file_indexed", repo=repo_name, path=...)
  
  [Pass 2 — after all files]
  → resolve_edges(repo_name, all_raw_edges, name_map)
      Matches call targets to known chunk_ids
      Unresolved = external library = safely dropped
  → KuzuStore.add_edges() — MERGE (idempotent, silent skip if node missing)
  → WAL.record("edges_written", repo=repo_name)

QueryRequest (question, repo_name, symbol?, filename?, language?, k=5)
  → Step 1: Parse filters (already validated by Pydantic)
  → Step 2: Exact symbol lookup (if --symbol provided)
      If > 10 results: too ambiguous, fall through to hybrid search
  → Step 3: Route query → prompt template
      BoW keyword matching: debugging > setup > code_search > conceptual
      Default on zero matches: conceptual
  → Step 4: Embed query (768d + 128d, QUERY_PREFIX)
  → Step 5: Hybrid search (if symbol lookup didn't find enough)
      Stage 1: vector_128 IVF-PQ ANN → top 1000 candidates (fast)
      Stage 2: vector_768 flat numpy cosine on 1000 candidates (precise)
      BM25: FTS on search_content column
      Merge: RRF(stage2_ranks, bm25_ranks) → top k
  → Step 6: Graph expand (single-hop, max 20 neighbors)
      MATCH (a)-[:CALLS|IMPORTS]->(b) WHERE a.chunk_id IN [seeds]
  → Step 7: Fetch neighbor text from LanceDB by chunk_ids
  → Step 8: Merge + deduplicate (seeds + neighbors)
  → Step 9: Assemble context
      Interleave: retrieved chunks at attention peaks (start/end)
      Graph neighbors in middle
      Cap at 32,000 chars
  → Step 10: Generate
      prompt_template.format(context=..., question=...)
      OllamaLLM or GeminiLLM
  → Step 11: Validate
      CosineValidator: always (cosine(embed(answer), embed(context)))
      LLMJudge: 10% sample (faithfulness + answer relevance)
  → QueryResult (answer, sources, metrics, faithfulness, answer_relevance)

Index time:
  Store vector_768 (768d, precise) + vector_128 (128d, fast) per chunk
  One forward pass — truncate + re-normalize for 128d

Query time:
  Stage 1: IVF-PQ ANN on vector_128 → top 1000 candidates (fast)
  Stage 2: flat numpy cosine on vector_768 for candidates only (exact, ~microseconds)
  
Cost: quality close to full 768d, speed close to 128d

reporag/
├── src/
│   ├── core/
│   │   ├── models.py          Domain models: CodeChunk, GraphEdge, QueryResult...
│   │   └── ports.py           Write-path Protocols
│   ├── ingestion/
│   │   └── loaders.py         LocalRepoLoader, GitHubRepoLoader
│   ├── chunking/
│   │   ├── parser.py          CodeParser, PythonStrategy, JavaScriptStrategy, FallbackStrategy
│   │   └── graph.py           resolve_edges()
│   ├── embedding/
│   │   └── embedder.py        NomicEmbedder, MRL cascade
│   ├── storage/
│   │   ├── lance_store.py     LanceStore — hybrid search, upsert, FTS
│   │   └── kuzu_store.py      KuzuStore — graph nodes, edges, expansion
│   ├── query/
│   │   ├── pipeline.py        QueryPipeline — 10-step read path
│   │   ├── router.py          QueryRouter (BoW), ContextAssembler
│   │   └── validator.py       CosineValidator, LLMJudge
│   ├── observability/
│   │   └── metrics.py         Timer (context manager), StepMetrics
│   ├── llm.py                 OllamaLLM, GeminiLLM, build_llm()
│   ├── indexer.py             Indexer, WAL
│   ├── config.py              Settings (pydantic-settings, all env vars)
│   └── logger.py              setup_logging(), get_logger()
├── scripts/
│   └── generate_golden_dataset.py  Golden QA pair generation
├── data/
│   ├── qa_pairs.jsonl         Generated golden dataset
│   └── eval_results.json      Eval output
├── api.py                     FastAPI app, lifespan, 4 endpoints
├── eval.py                    Evaluation harness + CLI entry point
├── DECISIONS.md               All major architectural decisions
├── FAILURES.md                All bugs found and case studies
├── RESULTS.md                 Eval results (fill after running eval)
├── pyproject.toml
└── .env.example