# Metis Knowledge-Graph And Retrieval Algorithm Status

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.py`
- `services/metis/src/metis/services/source_concept_graph_service.py`
- `services/metis/src/metis/services/source_retrieval_benchmark_helpers.py`
- `services/metis/src/metis/services/source_access_policy_helpers.py`

## Release-Approved Production Path

The canonical learner-facing and operator-approved production path is:

1. Source-backed concept-graph generation from extracted source metadata,
   sections, and grounded outline structure.
2. Safety and rights filtering before retrieval or graph traversal is allowed.
3. Graph-aware hybrid retrieval scored with `metis_pedagogical_hybrid_v1`.
4. Graph enrichment of returned evidence for linked concepts, prerequisite
   context, and related-concept context.
5. 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-canonical` to `release-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

1. Do not describe `dense`, `sparse`, `hybrid-baseline`, `graphrag-style`, or
   `multi-query-baseline` benchmark results as proof that a new learner-facing
   production path is approved.
2. Do not ship a new default retrieval strategy just because it won a benchmark
   leaderboard.
3. Treat the production path as the combination of: graph construction,
   access-policy filtering, graph-aware hybrid ranking, and graph-linked
   evidence output.
4. 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.py`
- `ruff 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.py`
- `python3 services/metis/scripts/export_openapi.py`
