Hierarchical RAG

HierarchicalRAG lives at alphaswarm_kb.rag.HierarchicalRAG (extracted from the legacy alphaswarm/rag/ tree per ADR-014). It is the default IMemoryEngine adapter for every KBCorpusSpec that doesn't explicitly choose another engine.

Four levels

Implements the Alpha-GPT "Human-AI Interactive Alpha Mining" design:

Level	Purpose
L0	Alpha / decision base — past agent_decisions, equity_reports, backtest_runs outcomes.
L1	High-level categories (price_volume, fundamental, news_sentiment, regulatory).
L2	Sub-categories (earnings_call, disclosures, cfpb_complaint, ...).
L3	Specific data fields / chunks — individual narratives + paragraphs.

Plus three orthogonal data "orders":

• first — bars / trades / performance.
• second — SEC filings / fundamentals / ratios.
• third — CFPB / FDA / USPTO regulatory data.
• theory — research papers + code chunks.

Public surface

Symbol	Use
HierarchicalRAG	Top-level facade.
HierarchicalRAG.query	Direct vector search at one level (optional reranker + compressor).
HierarchicalRAG.query_hybrid	Dense + sparse hybrid via Reciprocal Rank Fusion.
HierarchicalRAG.walk	Top-down L0 → L1 → L2 → L3 autonomous navigation.
HierarchicalRAG.recall_for_prompt	Markdown block ready for prompt injection.
HierarchicalRAG.index_chunks / index_summary	Write paths.
HierarchicalRAG.precompute_l0_alpha_base	Bulk-index past decisions.
get_default_rag()	Process-wide cached singleton.

Indexer registry

alphaswarm_kb.rag.indexers.INDEXER_REGISTRY maps every corpus slug to its indexer callable. Add a new corpus by writing an indexer that takes the source rows, renders them as text, chunks them via alphaswarm_kb.rag.chunker.semantic_chunks, and calls rag.index_chunks(corpus, ...).

Storage backend

Redis (RediSearch) is the default vector store; pgvector is the production-grade backend (Phase 3 refactor). Both implement the same RedisVectorStore / PgVectorStore surface that HierarchicalRAG consumes through composition.

Backward compatibility

alphaswarm.rag.* and alphaswarm.rag.indexers.* are DeprecationWarning shims that re-export from alphaswarm_kb.rag.*. Old call sites keep working for one release cycle.