Eve library

Metis Knowledge-Graph And Retrieval Algorithm Status

Guide

Revision 1

On this page

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