Semantic Graph (orchestrata_ultimate.semantic_graph)

A repository abstraction for RAG / GraphRAG retrieval, distinct from the Neo4j knowledge_graph/ package (see Architecture). 16 modules; deliberately lightweight coupling — only 2 imports into core.

What it provides

• Repository abstraction (repository.py + interfaces.py): protocol-based SemanticGraph combining GraphStore and VectorStore protocols, with a factory that selects an adapter from config — the production Memgraph adapter (adapters/memgraph.py) or an in-memory adapter for tests.
• Memgraph HA: a 3-node Memgraph cluster fronted by an HA controller (ha_controller.py, CLI in ha_controller_cli.py) that handles leader tracking and failover.
• Embedders and rerankers (embedders.py, rerankers.py): pluggable embedding backends for vector search and an OpenRouter-based reranker for retrieval quality.
• Ingestion (ingestion.py): source-code ingestion into the graph (see scripts/ingest_orchestrata_ultimate.py), producing embedded nodes from the codebase.
• Spec/trace enrichment (spec_trace_parser.py, spec_trace_enricher.py): parses SPEC documents and @traces requirement decorators and enriches the graph with spec ↔ code trace edges, tying retrieval to the authoritative specifications.

Class hierarchy

Module dependencies

Source diagrams: docs/diagrams/semantic-graph-classes.mmd and docs/diagrams/semantic-graph-deps.mmd in the repo.

Retrieval & navigation (updated 2026-07-08)

• Hybrid search (SemanticGraphIngester.search): RRF fusion of vector + keyword passes, module and prominence boosts, optional reranker; every hit carries a retrieval_explanation. Env-tunable knobs on SemanticGraphConfig.
• CLI: uv run python scripts/semantic_search.py "where is escalation handled" --top-k 5
• TESTS edges: 161 TestCase (@traces) + 458 TestModule (path heuristic) entities, 13,085 TESTS edges — walk Spec→Story→Requirement→CodeElement→Test.
• Prominence: Entity.prominence (from the spec word cloud) feeds ranking.
• Canonical chunks: CodestralChunk; stale experiment labels prunable via scripts/ingest_orchestrata_ultimate.py --prune-stale-labels [--apply].

Related

• RAG retrieval & context-injection investigation — a 2026-10-21 deep-dive on this package's retrieval stack and its one production consumer (knowledge_graph.context_injector): the vector/embedding path is built but unwired, and the semantic bridge is keyword-only and project/module-unscoped.