Code Intelligence
Python · Static Analysis · Information Retrieval
Graph-Augmented Code Intelligence Engine
Search code as a program, not just as text.
A Python/C++ code-intelligence engine that turns source repositories into semantic code units and static program graphs, then combines lexical, dense, and structural retrieval into explainable context.
01 — The Idea
The Idea
Text similarity does not directly encode program structure.
Many code retrieval systems represent repositories primarily as text. This engine instead preserves semantic program entities and explicit relationships between them.
Can retrieval use both textual relevance and program structure?
Flat text chunks
file.py
────────
- chunk 01
- chunk 02
- chunk 03
Semantic program structure
02 — From Code to Structure
From Code to Structure
Tree-sitter parsing turns source into semantic program entities and an explicit CodeGraph — not arbitrary text slices.
Semantic Code Units
Classes · Functions · Methods
Language Adapters
Python · C++
Relation Model
CONTAINS · IMPORTS · CALLS · REFERENCES · INHERITS
- Python supports all five relation kinds. C++ intentionally does not implement REFERENCES.
- IMPORTS exists in the graph model but is not used as a graph-retrieval expansion channel.
03 — Retrieval Engine
Retrieval Engine
A staged ladder fuses textual ranking with bounded structural evidence, then compiles whole semantic units into a token budget.
Lexical
SQLite FTS5 · BM25
Dense
MiniLM · FAISS FlatIP
Hybrid
RRF
Graph
1-hop structural augmentation
Reranked
Relation evidence
Context
Token-budget compiler
RRF Fusion
Use ranking positions instead of comparing incompatible lexical and dense raw scores directly.
Bounded Graph Expansion
Top Hybrid seeds expand through resolved structural relationships only, with graph retrieval constrained to depth 1.
Structured Reranking
Relation evidence contributes deterministically rather than using an LLM reranker.
Whole-Unit Context
Context compilation preserves complete semantic CodeUnits rather than arbitrarily truncating source.
04 — The Experiment
The Experiment
I didn't stop at “it works.” I benchmarked the hypothesis.
A frozen synthetic Python benchmark compares Lexical, Dense, Hybrid, Graph, and Reranked retrieval. It is designed for controlled comparison — not as a production-scale evaluation.
24
Retrieval Queries
53
Code Units
5
Retrieval Modes
11
Python Files
05 — What the Benchmark Taught Me
Dense won. The graph didn't.
On the frozen benchmark, dense retrieval produced the strongest aggregate ranking. The current structural fusion displaced already strong text-ranked candidates often enough to reduce aggregate MRR@10.
MRR@10 — 24-query Python benchmark
Dense
0.8532
Hybrid
0.7604
Lexical
0.7431
Graph
0.4971
Reranked
0.4241
I kept the result instead of tuning the benchmark until the graph won.
Graph vs Hybrid: 3 wins · 7 ties · 14 losses
06 — Incremental Indexing
Incremental Indexing
Repository changes are detected through SHA-256-based ChangeSets, allowing the engine to selectively reanalyze changed files and reuse unchanged dense vectors.
These are work counts — not wall-clock latency or throughput claims.
Files Analyzed
| Scenario | Full | Incremental |
|---|---|---|
| No-op | 11 | 0 |
| Body edit | 11 | 1 |
| Symbol rename | 11 | 2 |
| Add + delete | 11 | 1 |
Vector Work
| Scenario | Reused | Embedded |
|---|---|---|
| No-op | 53 | 0 |
| Body edit | 52 | 1 |
| Symbol rename | 51 | 2 |
| Add + delete | 50 | 1 |
07 — Context Without the Chatbot
The LLM is downstream, not the engine.
The engine compiles ranked CodeUnits into a deterministic, token-budgeted CompiledContext. There is no LLM answer-generation layer in the engine itself.
Ranked candidates
TOKEN BUDGET
CompiledContext
08 — Engineering Proof
Engineering Proof
286
Automated Tests
2
Language Adapters
5
Relation Types
~8.2K
Engine LOC
project src/ Python only
253 unit · 33 integration · 286 total