Status: Canonical
Last updated: 2026-04-11
Owners: Metis Engineering, Metis Operations, Metis Safety
Purpose#
This document is the canonical classification of Metis knowledge-graph and retrieval algorithms.
It exists to answer one operational question unambiguously:
- which algorithms are learner-facing or release-approved production paths
- which algorithms exist only as classical baselines, benchmarks, or operator comparisons
This document should be kept aligned with:
services/metis/src/metis/services/source_retrieval_service.pyservices/metis/src/metis/services/source_concept_graph_service.pyservices/metis/src/metis/services/source_retrieval_benchmark_helpers.pyservices/metis/src/metis/services/source_access_policy_helpers.py
Release-Approved Production Path#
The canonical learner-facing and operator-approved production path is:
- Source-backed concept-graph generation from extracted source metadata, sections, and grounded outline structure.
- Safety and rights filtering before retrieval or graph traversal is allowed.
- Graph-aware hybrid retrieval scored with
metis_pedagogical_hybrid_v1. - Graph enrichment of returned evidence for linked concepts, prerequisite context, and related-concept context.
- Graph exploration only over the filtered, source-cleared subgraph.
Production Algorithms#
| Area | Release-approved algorithm | Where enforced | Notes |
|---|---|---|---|
| Concept graph construction | deterministic source-backed node and edge extraction from extraction + outline artifacts | build_concept_graph_nodes, build_concept_graph_edges |
This is the canonical graph materialization path for Metis V1. |
| Graph traversal | prerequisite-chain and related-concept traversal over the filtered graph | build_prerequisite_chain, build_related_concepts, SourceConceptGraphService.explore |
Traversal is policy-gated before any learner-facing exploration result is produced. |
| Retrieval ranking | graph-aware hybrid retrieval with pedagogical ranking weights | SourceRetrievalService.retrieve with ranking profile metis_pedagogical_hybrid_v1 |
This is the default release-approved retrieval path. |
| Retrieval governance | shared safety/rights/provenance allowlist enforcement | build_source_access_policy, filter_graph_for_access_policy |
Blocked packages, safety-sensitive queries, policy-sensitive queries, and uncleared sources are fail-closed. |
Supported But Not Canonical#
The following strategies exist in code, but they are not the canonical release path for Metis V1 unless a surface explicitly launches with separate signoff:
| Strategy | Status | Reason |
|---|---|---|
rerank retrieval |
supported, non-canonical | available as an internal retrieval mode, but not the declared V1 default production path |
multi-query retrieval |
supported, non-canonical | used for comparative evaluation and advanced retrieval experiments, not the default learner path |
If a future Metis release wants to promote one of these strategies into the canonical learner-facing path, the promotion must include:
- benchmark evidence
- release-gate review
- operator documentation update
- this document updated from
supported, non-canonicaltorelease-approved
Classical Baselines And Benchmark-Only Paths#
The following algorithm families are treated as baselines, comparison paths, or evaluation controls. They are not the canonical release-approved learner path.
| Baseline family | Metis label | Status | Where used |
|---|---|---|---|
| dense semantic retrieval | dense-baseline |
benchmark-only | retrieval benchmark comparisons |
| sparse lexical retrieval | sparse-baseline |
benchmark-only | retrieval benchmark comparisons |
| plain hybrid retrieval without graph-first focus guidance | hybrid-baseline |
benchmark-only | retrieval benchmark comparisons |
| GraphRAG-style focus-node-seeded retrieval | graphrag-style |
benchmark-only | retrieval benchmark comparisons |
| multi-query hybrid fusion baseline | multi-query-baseline |
benchmark-only | retrieval benchmark comparisons |
Benchmark-only means:
- the algorithm may run inside evaluation or operator-comparison tooling
- the algorithm may be useful for measuring regressions or upside
- the algorithm is not by itself enough to claim release approval
Operational Rules#
- Do not describe
dense,sparse,hybrid-baseline,graphrag-style, ormulti-query-baselinebenchmark results as proof that a new learner-facing production path is approved. - Do not ship a new default retrieval strategy just because it won a benchmark leaderboard.
- Treat the production path as the combination of: graph construction, access-policy filtering, graph-aware hybrid ranking, and graph-linked evidence output.
- If a retrieval or graph experiment is exposed to learners, it must be named explicitly in release review and moved into the release-approved section of this document.
Current V1 Decision#
As of 2026-04-11:
- release-approved knowledge-graph path: source-backed concept graph plus policy-filtered traversal
- release-approved retrieval path: graph-aware hybrid retrieval with
metis_pedagogical_hybrid_v1 - benchmark-only paths: dense, sparse, hybrid-baseline, GraphRAG-style, and multi-query baseline comparisons
Verification#
pytest services/metis/tests/test_source_retrieval_benchmark_service.py services/metis/tests/test_source_access_policy_helpers.py services/metis/tests/test_source_retrieval_service.py services/metis/tests/test_source_concept_graph_service.py services/metis/tests/test_openapi_contract.pyruff check services/metis/src/metis/services/source_retrieval_benchmark_helpers.py services/metis/src/metis/services/source_access_policy_helpers.py services/metis/src/metis/services/source_retrieval_service.py services/metis/src/metis/services/source_concept_graph_service.py services/metis/src/metis/schemas/source_retrieval.py services/metis/src/metis/schemas/source_retrieval_benchmark.py services/metis/src/metis/schemas/__init__.py services/metis/tests/test_source_retrieval_benchmark_service.py services/metis/tests/test_source_access_policy_helpers.py services/metis/tests/test_source_retrieval_service.py services/metis/tests/test_source_concept_graph_service.py services/metis/tests/test_openapi_contract.pypython3 services/metis/scripts/export_openapi.py