CODESAGEZ/ARCHITECTURE SPECIFICATION
Pipeline & Graph Topology
Combines dense vector similarity with relational abstract syntax tree call graphs (Graph-RAG) to ensure LLM code generations remain grounded in actual repository compilation units.
Ingestion Pipeline Stages
7 STAGES // DETERMINISTICStage
Name
Engine / Worker
Transformation
Target SLA
01
Clone
asyncio.subprocess
Raw Repository Mirror
<1.2s
02
Parse AST
Tree-sitter 0.22
ASTNode Definitions
Zero Loss
03
Call Graph
NetworkX 3.2
Directed Reference DiGraph
1-Hop Bound
04
Chunking
Semantic AST Chunker
Discrete Code Chunks
<512 tok
05
Embedding
Google GenAI (Gemini)
3072-dim Float Vectors
Batch 64
06
Vector Store
ChromaDB HNSW
Indexed Vector Collection
P95 < 25ms
07
Graph RAG
SingleFlight + SQL Traversal
Augmented System Prompt
Total < 50ms
Structural vs Naive Chunking
Standard semantic chunking splits files by arbitrary token windows. If an LLM is asked about a class that calls internal helpers in sibling modules, naive retrieval returns incomplete signatures, triggering hallucinated implementations.
CodeSageZ traverses the NetworkX call graph 1 hop outward from the initial vector match, pulling callers, callees, and type definitions into the prompt without token blowup.
Execution Trace // 1-Hop Expansion
# 1. Vector Search locates seed nodeseed = chroma.query("auth header token", k=1)# -> match: validate_bearer_token() (sim: 0.88)# 2. Relational SQL expansioncallers = db.get_callers("validate_bearer_token") callees = db.get_callees("validate_bearer_token")# 3. Exact compiler context injected:- auth_middleware() [CALLER] - validate_bearer_token() [SEED] - decode_jwt_claims() [CALLEE]