# Metis — Systems Deep Dive

> The `libs/metis/` area: ~25 Nx libraries that make up **Metis**, Oshun's
> AI-powered educational-content platform — the agents, LLM orchestration,
> assessment psychometrics, adaptive-learning engines, knowledge graph,
> multimedia generation, verification gates, and the typed primitives they all
> share.

## What this area is

Metis is the platform that turns a topic into a full, pedagogically-sound,
machine-verifiable course: it plans curricula with a multi-agent framework,
generates content and media through provider-routed LLM calls, models each
learner's mastery, assembles assessments with real item-response-theory
psychometrics, and gates everything behind correctness verifiers before
publishing. The `libs/metis/` directory is not one package but roughly
twenty-five separate Nx libraries (every project is tagged `scope:metis`), each
owning one slice of that pipeline and published under the `@metis/*` npm scope.

The area is layered. At the bottom sit the **typed primitives** — `metis-core`
(enums, shared domain types, Bloom/difficulty/quality scales) and three
contract-style type libraries (`metis-agents-types`, `metis-database-types`,
`metis-linters-types`) plus the richer `metis-models` entity library — which
carry no business logic and are imported by nearly everything above them. On top
of those sit the **engine libraries**: `metis-agents` (the agent framework and
the specialised educational agents), `metis-llm-client` (provider routing and
content generation), `metis-assessment` (IRT), `metis-adaptive` and
`metis-learning` (knowledge tracing and personalization),
`metis-knowledge-graph` (concept graphs), `metis-multimedia`
(audio/video/diagram/avatar generation), `metis-course`
(authoring/versioning/export), `metis-tutoring` (live sessions),
`metis-research` (corpus + citation), and `metis-verification` and
`metis-quality` (the correctness and linting gates). A final tier of
**operational** libraries supports the rest: `metis-model-registry`,
`metis-cost-tracking`, `metis-ab-testing`, `metis-prompt-management`,
`metis-gradebook`, `metis-discovery`, `metis-integrations`, and the
`metis-api-client` SDK.

Two things are worth flagging up front for honesty. First, several libraries
expose **fail-loud injectable seams** rather than bundling a live provider: the
LLM and verification layers take a model boundary you wire to a real
Anthropic/OpenAI/Google producer, and refuse to fabricate output when one is
absent. Second, every library in this area is genuinely implemented — there are
no empty `.gitkeep`-only scaffolds here (unlike, say, `@maat/contracts` in the
contracts area). The thinnest, `metis-discovery`, is still a single substantial
module, not a placeholder.

## How it fits the wider system

Metis is consumed both internally and across the monorepo. Inside the area the
flow is roughly: agents (`metis-agents`) drive generation through
`metis-llm-client`, drawing prompts from `metis-prompt-management`, picking
models via `metis-model-registry`, charging spend to `metis-cost-tracking`, and
emitting content shaped by `metis-models`/`metis-core`; that content is then
verified by `metis-verification`, linted by `metis-quality`, assembled into
courses by `metis-course`, scored by `metis-assessment`, and tracked per-learner
by `metis-adaptive`/`metis-learning`. Outward, `metis-integrations` wires Metis
into the rest of Oshun (Lilith conversation, Hathor worldbuilding, Bellona
engine, Sophia, Isis, Iris, Psyche, Yemaya, Themis, Aja and the shared infra),
and exports learner outcomes through `metis-gradebook` over real ed-tech
standards (LTI-AGS, xAPI, cmi5, Caliper). `metis-discovery` defines the unified
cross-domain search surface that lets Metis content sit alongside Tara, Arete,
Veritas, Nyx and Nisaba objects in one catalog. `metis-api-client` is the typed
SDK external callers use to reach the platform. The boundary rule mirrors the
rest of the repo: the `*-types` libraries and `metis-core` sit at the bottom of
the graph so producers and consumers share the same definitions without pulling
in each other's runtime.

## Entity reference

### metis-ab-testing

Experiment platform for the Metis pipeline (`@metis/ab-testing`,
`libs/metis/ab-testing/src`). It is built from five real modules behind the
barrel — `experiment-manager`, `variant-assigner`, `metric-collector`,
`statistical-analyzer`, and `result-reporter` — with branded ID types and a full
status/type/metric enum surface in `src/types.ts`. It exists so content and
model changes can be rolled out as controlled experiments (deterministic variant
assignment, metric collection, significance testing, and report generation)
rather than shipped blind. Factory variants such as
`createStrictExperimentManager` and `createRapidExperimentManager` preset the
statistical rigor.

### metis-adaptive

The adaptive-learning engine (`@metis/adaptive`, `libs/metis/adaptive/src`),
organised into `profiling/`, `adaptation/`, and `path/`. It carries genuine
knowledge-tracing algorithms, not heuristics: `path/bkt.ts` implements Corbett &
Anderson (1995) two-state-HMM **Bayesian Knowledge Tracing** (with the Beck &
Chang 2007 `pS + pG < 1` identifiability bound), alongside `fsrs.ts` (FSRS-5
spaced repetition / DSR model), `graph-knowledge-tracing.ts` (Nakagawa-style
GKT), and a unified `adaptive-knowledge-engine.ts` that composes BKT + GKT +
FSRS. The profiling and adaptation modules add learning-style detection,
difficulty adjustment, prerequisite checking, and pacing optimization, so the
platform can select the next best content for a given learner.

### metis-agents-types

A type-only library (`@metis/agents-types`, tagged `type:types`-adjacent under
`layer:domain`) that defines the agent framework's shared shapes: `base/` (agent
config, state, checkpoints, conversation messages, token estimation,
status-transition validation) and a **ReAct framework** module
(thoughts/actions/observations, iteration traces, convergence detection,
action-success metrics). It has no business logic of its own — it is the
contract surface that `metis-agents` and other agent consumers build against so
agent state and ReAct traces are defined once.

### metis-agents

The comprehensive multi-agent framework (`@metis/agents`,
`libs/metis/agents/src`). `core/` provides the infrastructure — agent registry,
lifecycle with validated status transitions, a communication/message bus,
events, priorities, retry policy, and monitoring — and `agents/` holds the
specialised educational agents: curriculum, content, assessment, evaluation,
fact-checking, moderator, research, citation (with a `citation-renderer`),
diagram, tutor, feedback, learning-style, scaffolding, an `adaptive-sequencer`,
a `misconception-graph`, an `arithmetic-equation-checker`, and a media sub-crew
(planner/coder/critic with a `media-benchmark`). An `adversarial-eval/` module
adds an evaluator and regression suite. This is the orchestration brain that
turns a request into planned, generated, checked educational content.

### metis-api-client

The typed REST/realtime SDK for the platform (`@metis/api-client`,
`libs/metis/api-client/src`), its header noting it was "ported and enhanced from
minerva/sdk/typescript/". It provides a middleware-pipeline `HttpClient`,
JWT/API-key/Basic auth with auto-refresh (`TokenStore`/`TokenProvider`), error
mapping into `@oshun/errors`, configurable exponential-backoff retry, in-memory
LRU request caching, cursor and offset pagination iterators, a reconnecting
WebSocket client, and request-mocking utilities for tests. It is the boundary
external callers use to reach Metis without re-declaring its HTTP surface.

### metis-assessment

The psychometrics and assessment-generation library (`@metis/assessment`,
`libs/metis/assessment/src`). It is split into `irt-models/` and `irt-calc/`
(real **item-response theory**, including the 3PL model with item difficulty,
discrimination, and guessing parameters), plus `rubric/`, `adaptive/` (adaptive
item selection), `feedback/`, `grading/`, `analytics/`, and a `generation/`
module re-exported under `Gen…`-prefixed names that builds question banks,
Bloom-aligned stems, and quality-scored distractors (semantic, misconception,
numerical, partial-truth, reversed-logic, overgeneralization). It exists so
Metis can author, calibrate, and adaptively administer assessments with genuine
measurement theory rather than ad-hoc scoring.

### metis-core

The shared primitive layer (`@metis/core`, `libs/metis/core/src`) that nearly
every other Metis library imports. `enums/` defines the platform's controlled
vocabularies — content types/formats, course status/level/category, difficulty,
**Bloom taxonomy**, cognitive-load, learning style, assessment/question types,
grading strategies, pipeline stages, lint severity/category, quality scores,
citation styles, credibility levels, accessibility levels — with helpers for
enum validation, numeric mapping, ordering, and legal status transitions. It
carries no engine logic; it is the bottom-of-the-graph type spine that keeps
Bloom/difficulty/quality scales consistent across the whole pipeline.

### metis-cost-tracking

LLM spend governance (`@metis/cost-tracking`, `libs/metis/cost-tracking/src`),
built from `budget-manager`, `cost-calculator`, `usage-predictor`,
`optimization-advisor`, and `reporting-engine` modules over a rich branded-ID
and enum surface in `src/types.ts` (budget periods/scopes, pricing tiers, cost
categories, model providers, carryover policies, optimization strategies). It
exists to attribute token cost to budgets and scopes, alert on overruns, predict
usage, recommend cheaper routing, and produce grouped cost reports — the
accounting layer behind `metis-llm-client` and `metis-model-registry`.

### metis-course

Course authoring and lifecycle (`@metis/course`, `libs/metis/course/src`),
composed of `syllabus/`, `versioning/`, `bundle/`, `export/`, `analytics/`,
`validation/`, and `operations/` modules. It takes the content the agents and
generation libraries produce and assembles it into a structured, versioned,
validated, exportable course — the packaging tier that sits between raw
generated material and a publishable artifact.

### metis-database-types

A type-only library (`@metis/database-types`, tagged `type:types`) that models a
database-agnostic schema and query surface. `schema/` defines collections,
fields, indexes, relations, and validation rules with constructor and accessor
helpers; `query-builder/` defines filter operators, sorts, joins, aggregates,
pagination, and result shapes with immutable
`addFilter`/`addSort`/`withPagination` builders. It is pure type-and-helper
scaffolding for persistence — no live driver — so Metis services can describe
storage shapes uniformly.

### metis-discovery

The unified cross-domain search surface (`@metis/discovery`,
`libs/metis/discovery/src`). It is the thinnest Metis library — a single
`index.ts` plus its test — but it is fully implemented, not a scaffold: it
declares the `DiscoveryDomain` set (Tara, Arete, Veritas, Nyx, Nisaba, Metis,
Oshun), the full `SearchObjectClass` taxonomy and its class→domain mapping, a
`SearchableObject` shape with accessibility, evidence-grounding, freshness,
entitlement and rights metadata, and a real `SearchableObjectCatalog` with a
lexical inverted index, facet vocabulary, embedding-class tracking, and
domain/class consistency enforcement on `upsert`. It defines how Metis content
becomes discoverable alongside other Oshun domains in one catalog.

### metis-gradebook

Outcomes emission over real ed-tech interoperability standards
(`@metis/gradebook`, `libs/metis/gradebook/src`). Beyond its `emission` core it
ships concrete adapters for **LTI-AGS** (`lti-ags.ts`), **xAPI** (`xapi.ts`),
**cmi5** (`cmi5.ts`), **IMS Caliper** (`caliper.ts`), and file export
(`file-export.ts`). It exists so learner grades and activity statements leave
Metis in the formats institutional LMSs and learning-record stores actually
expect, rather than a bespoke shape.

### metis-integrations

The cross-domain wiring layer (`@metis/integrations`,
`libs/metis/integrations/src`). Its barrel pulls in canonical-wiring and
integration modules for Lilith, Hathor, Isis, Iris, Psyche, Aja, Sophia, Themis,
Yemaya, and Kalika, plus `domain-integrations`, `cross-domain-flows`,
`shared-libraries`, and `byom/` and `standards/` (including
`institutional-delivery`). It is how Metis plugs into the wider Oshun monorepo —
the seam that connects the educational platform to conversation, worldbuilding,
engine, fitness, and shared-infrastructure domains (its header references
Phase-25 tasks).

### metis-knowledge-graph

The concept-graph engine (`@metis/knowledge-graph`,
`libs/metis/knowledge-graph/src`), the most module-rich library in the area with
`construction/`, `operations/`, `retrieval/`, `embeddings/`, `gnn/`,
`temporal/`, `persistence/`, and `applications/` directories. `construction/`
does concept and entity/relation extraction, entity resolution with conflict
handling, graph deltas, versioning, and validation (cycles, orphans,
severity-graded issues); the further modules add embeddings,
graph-neural-network support, temporal versioning, and persistence. It builds
and maintains the prerequisite/concept graph that adaptive sequencing, research,
and assessment all reason over.

### metis-learning

The learner-modeling and personalization library (`@metis/learning`,
`libs/metis/learning/src`), spanning `learning-paths`, `learner-profiles`,
`mastery`, `progress-tracking`, `adaptation`, `content-selection`,
`recommendations`, `personalization`, `learning-analytics`, and
`subject-taxonomy`. It models paths (with step typing, prerequisite ordering,
circular-dependency detection, completion/duration computation), mastery levels,
and per-learner progress. Where `metis-adaptive` owns the knowledge-tracing
math, `metis-learning` owns the broader learner profile, path construction, and
recommendation surface around it.

### metis-linters-types

A type-only library (`@metis/linters-types`, `libs/metis/linters-types/src`)
that defines the vocabulary of content-linting findings: finding severity/type/
category, section-type mappings and auto-fix flags, severity ordering and
weights, and a large family of constructors for specific finding kinds
(consistency, content, quiz-richness, lesson-richness, learning-objective,
fact-claim, code-verification, multimodal-consistency, terminology, bias,
citation) plus grouping/filtering helpers. It is the shared type spine the
`metis-quality` linters emit against.

### metis-llm-client

The educational LLM orchestration client (`@metis/llm-client`,
`libs/metis/llm-client/src`). `provider-adapter/` registers multiple provider
adapters and routes each educational task by strategy (round-robin,
capability-match, cost-aware, latency-aware, quality-weighted, task-specific),
scores providers on compatibility/cost/latency/quality, supports fallback
chains, and tracks per-provider performance — over a provider enum that includes
`ANTHROPIC`, `OPENAI`, and Google. Further modules cover content generation,
response parsing into typed content blocks, educational sessions, an
understanding-classifier, and a `quality-evaluator` whose default judge is
`anthropic`/`claude-haiku-3.5` (with OpenAI and Google alternatives). The actual
network call is an injectable producer seam rather than a vendored SDK, so the
routing/scoring logic is the real, testable substance here.

### metis-model-registry

The model catalog and task router (`@metis/model-registry`,
`libs/metis/model-registry/src`), built from `model-catalog`, `task-router`,
`capability-matcher`, `performance-tracker`, and `selection-optimizer` modules.
It maintains catalog entries (provider, capabilities, tier, benchmarks), matches
a task profile to a model by capability and confidence, records performance, and
optimizes selection against objectives (cost, latency, quality). It is the
decision layer `metis-llm-client` consults to pick which model serves a given
educational task.

### metis-models

The domain-entity model library (`@metis/models`, `libs/metis/models/src`) —
distinct from `metis-core`'s primitives in that it carries the richer
educational entities and the **action/diff** vocabulary used to edit them. Its
modules include `actions` (a large family of course/topic diffs: add-section,
add-lesson, add-quiz, add-concept-node/edge, merge-elements, link-to-concept,
etc., with validators), `plans`, `learning-objectives`,
`assessment`/`assessment-evidence`, `citations`, `findings`, `graph`,
`rich-media`, `persona`, `session-memory`, `study-aids`, and
`academic-integrity`. It is the shared shape of "what a course/topic/lesson is
and how it may be mutated" that the agents and course libraries operate on.

### metis-multimedia

The media-generation pipeline (`@metis/multimedia`,
`libs/metis/multimedia/src`), the largest module set in the area: `audio/`,
`video/`, `image/`, `diagram/`, `animation/`, `presentation/`,
`lecture-generation/`, `avatar-teacher/`, `interactive/`, `accessibility/`, and
`multilingual/`. The audio layer is concretely real — a `TTSEngine` with
Chatterbox and ElevenLabs variants and SSML generation/validation, plus an
EBU-R128 loudness module (`loudness-r128.ts`) that does genuine K-weighting,
integrated-LUFS and true-peak measurement, and WAV/PCM normalization, and a
`NarrationPlanner` with adaptive pacing. It exists to turn lesson text into
narrated, captioned, illustrated, accessible multimedia.

### metis-prompt-management

The prompt library and pipeline (`@metis/prompt-management`,
`libs/metis/prompt-management/src`), with `curriculum-prompt`,
`pedagogical-prompt`, `assessment-prompt`, `few-shot-library`, and
`prompt-pipeline` modules over branded prompt IDs and pedagogy enums (Bloom
level, pedagogical approach, prompt tone, audience, output format, rubric
criteria/levels). It centralises the platform's educational prompts and few-shot
exemplars so generation calls draw from versioned, typed templates rather than
inline strings.

### metis-quality

The content quality and compliance gate (`@metis/quality`,
`libs/metis/quality/src`), organised into `infrastructure/` (the linter
registry, severity model, quality dimensions, grade thresholds, weighted penalty
scoring), `content/`, `technical/`, and `compliance/` linter families. It runs
registered linters over generated content, scores it across weighted quality
dimensions into a letter grade, and produces a `LintReport`. Paired with
`metis-linters-types` (the finding vocabulary) and `metis-verification`
(correctness), it is the style/compliance half of Metis's publish gate.

### metis-research

The research and evidence library (`@metis/research`,
`libs/metis/research/src`), with `knowledge-graph`, `corpus`, `search`,
`embeddings`, `citations`, `credibility`, and `analytics` modules. It maintains
a research-oriented knowledge graph (entities/relationships with confidence
levels, validation status, cross-domain links, orphan detection, basic metrics),
gathers and searches a corpus, scores source credibility, and produces
citations. It is the evidence-gathering substrate behind the fact-checking,
citation, and research agents.

### metis-tutoring

The live-tutoring session engine (`@metis/tutoring`, `libs/metis/tutoring/src`),
spanning `session/`, `conversation/`, `hints/`, `scaffolding/`,
`learning-style/`, `persona/`, `loop/`, and `analytics/`. The `session/` module
is a full state machine — start/pause/resume/complete/expire/abandon
transitions, event logging, difficulty updates, hint/error counters, idle/expiry
tracking, and computed accuracy/hint-ratio/completion metrics. It powers a
one-on-one tutoring interaction with adaptive hints, scaffolding, and persona,
distinct from the batch content-generation agents.

### metis-verification

The educational-correctness verification layer (`@metis/verification`,
`libs/metis/verification/src`). It reuses `@oshun/content-quality-judge` for
generic judge/calibration/grounding machinery and adds education-specific
verifiers — factuality, faithfulness (`faithfulness/trace-scorer`), STEM/process
step verification, claim extraction and verification with span-linking,
contradiction detection, citation-sufficiency, pedagogy and judge-reliability
checks — composed through a fail-loud `VerificationGate`. It also ships a
generate→verify→refine loop (`gate/generate-verify-refine.ts`), conformal
selective calibration, an eval harness with a gold fixture set, and hardening
modules (budget ceiling, verification drift). It is the correctness gate every
piece of generated content must clear before it ships, and it refuses to
fabricate a verdict when its model boundary is unconfigured.

### @metis/training-data

Phase 85–86 flywheel producer for education (`libs/metis/training-data/src`):
`MetisTrainingDataPipeline` turns eleven `MetisTrainingKind` signals —
`lecture-quality`, `assessment-effectiveness`, `learning-progression`,
`diagram-quality`, `agent-trace`, `cost-quality`, `educational-experiment`, and
peers — into governance-gated (`governanceGrantId`) `MetisTrainingRecord`s
emitted through a pluggable `MetisTrainingSink`.