karthik.dev
Back to projects
AI

CodeRAG

Production-ready AST-parsed codebase RAG with hybrid search and precise file & line citations

GitHub
PythonTree-sitter (AST Parsing)PostgreSQLpgvectorHybrid SearchEmbeddingsLLMs

Overview

CodeRAG is a production-ready Retrieval-Augmented Generation engine for codebases that uses AST parsing (Tree-sitter) to chunk code at semantic boundaries — functions, classes, methods — rather than arbitrary character offsets. Combines dense vector search (embeddings) with sparse keyword search (hybrid) and generates responses with precise file-and-line-number citations.

Problem

Standard RAG systems chunk text at fixed character offsets, breaking semantic units in code — a function split mid-body produces useless context for LLM code analysis. Without precise citations, generated answers can't be verified against source code.

Solution

AST-parsed chunking using Tree-sitter extracts semantically complete code units (functions, classes, modules). Hybrid search combines embedding similarity with keyword matching for high-recall retrieval. Every LLM response includes precise file path and line number citations traceable to source.

Architecture

  1. 1Tree-sitter AST parser — language-aware code chunking at function/class boundaries
  2. 2Embedding pipeline — dense vector representations of code chunks
  3. 3PostgreSQL + pgvector — vector storage and approximate nearest-neighbor search
  4. 4Hybrid retrieval — combining dense embeddings with sparse BM25 keyword scoring
  5. 5LLM generation layer — code answers grounded in retrieved chunks
  6. 6Citation engine — precise file path and line number references in every response
  7. 7Multi-language support — Python, TypeScript, JavaScript, Java, and more via Tree-sitter grammars

Technical Challenges

  • Tree-sitter grammars vary significantly across languages — building a unified chunking interface that works correctly for Python, TypeScript, and Java.
  • Hybrid search score fusion: dense + sparse scores must be normalized before combination to avoid one dominating.
  • Citation accuracy: line numbers from AST nodes must survive chunking and remain stable across re-indexing.

Results

  • Production-ready codebase RAG with AST-aware chunking — significantly higher retrieval precision than character-offset approaches.
  • Every response includes file path + line number citations for source verification.
  • Open-sourced with MIT license for the AI engineering community.