HMA — Retrieval-Augmented Hierarchy

The Problem with Traditional RAG

Problem	What Happens
Loss of structure	File hierarchies, class definitions, cross-references destroyed
Context fragmentation	Related info split across chunks loses meaning
Token waste	Irrelevant chunks pulled in by keyword overlap
No relationship awareness	`auth.py` and its `config.py` treated as isolated islands

How I Built It

HMA is pure Python (≥3.9) with zero vector dependencies.

Python AST module — accurately maps Python code structures locally
Regex engines — extract imports/exports from 20+ languages (JS, TS, Rust, Go, Java, etc.)
LLM-agnostic design — you inject your own callable (OpenAI, Gemini, Ollama, HuggingFace)
Optional document parsers — PyMuPDF and python-docx for rich document support
PyPI published — pip install hma

The architecture runs in two distinct phases:

Phase 1 — Offline Indexing:

File Walker → File Analyzer → Summary Generator + Relationship Extractor → Knowledge Map

Phase 2 — Online Querying:

User Question → Query Router → LLM selects files → Targeted Reader → Single-Hop Traverser → Context Assembler → Answer

Challenges

Language-agnostic relationship extraction without spinning up language servers — solved with carefully tuned regex per language family
Keeping the single-hop constraint strict — it's tempting to traverse deeper, but depth causes exponential token blowup; one hop is the sweet spot
Making it truly LLM-agnostic — the protocol wraps any callable that takes a string and returns a string, with no SDK lock-in

What I Learned

That the hardest problems in AI tooling aren't model problems — they're data retrieval problems. A smarter map beats a bigger model almost whenever the task is "find the right context."