Metis Domain — Feature Reference

Metis is the AI-powered education and course-generation domain of the Oshun platform. It is an end-to-end backend for authoring courses, delivering them to learners, assessing learning with auto-grading and live-data calibration, running AI tutoring (including live-voice tutoring), grounding generated content in reviewed source material, issuing verifiable credentials, and exporting to and from standards-based learning management systems.

The production implementation is a Python backend service at services/metis/ — FastAPI for the REST API, SQLAlchemy 2.0 over PostgreSQL for persistence, and Celery over Redis for background work. The headline curriculum focus is the core six disciplines: philosophy, religion, psychology, neuroscience, anthropology, and astronomy; other subjects are treated as scaffolding for those disciplines.

A separate TypeScript library tree exists at libs/metis/*. This document describes the runnable Python backend under services/metis/.

Service: metis-backend | API prefix: /api | 16 domain routers

1. Course Authoring#

Metis organizes educational content in a strict three-level hierarchy:

Course → Module → Lesson

Each level is a first-class entity with its own metadata and lifecycle state, persisted in the courses, modules, and lessons tables. This fixed hierarchy — no sections, no content blocks, no nesting beyond three levels — keeps the data model simple and ensures every piece of learner-facing content can be addressed by a stable URL path.

• Course lifecycle: Courses move through draft, published, and archived states. They carry discovery metadata — category, difficulty (beginner/intermediate/advanced/expert), tags, estimated hours, thumbnail, a featured flag, an enrollment count, and an average rating.
• Modules: Ordered sections within a course, each with its own publish flag and estimated duration.
• Lessons: The atomic content unit. Each lesson has a content_type — text, video, interactive, quiz, or code_exercise — and a content field interpreted accordingly (markdown, a video URL, or JSON). Lessons can be marked as free preview for marketing and carry supplementary resource URLs.
• Course CRUD API (/api/courses): list with filtering, search, and pagination; create/update/delete courses; add/update/delete modules and lessons. Course creation, edits, and deletion require the instructor (or admin) role.
• Lesson evidence bundles: Published lessons, assessments, and questions are served with derived evidence bundles that summarize their grounding for learner-facing surfaces.

2. Enrollment and Learner Progress#

Once a learner enrolls in a course, Metis tracks their progress at two granularities: an overall completion percentage on the enrollment record, and fine-grained per-lesson bookmarks that survive session interruptions. An achievement system layers gamification on top of this progress data without requiring a separate points service.

• Enrollment: A learner enrolls in a course via POST /api/courses/{id}/enroll. An enrollment binds a user to a course (unique per user/course pair) with a status (active/completed/dropped/paused), an overall completion percentage, certificate URL, and an optional learner rating and written review.
• Per-lesson progress: Each progress row records whether a learner has completed a specific lesson, cumulative time spent, a bookmark position (e.g. a video timestamp), and private learner notes. Progress is updated via POST /api/courses/{id}/progress/{lesson_id} and requires an active enrollment.
• Achievements: Gamification badges awarded for milestones — course_completion, streak, perfect_score, first_enrollment, and milestone — each carrying a point value and badge icon. Each type/name combination is earned once per learner.
• Learner preferences: The user profile stores structured study preferences (study goal, pace, weekly-hours target, session length, preferred content types and subjects, tutor style, explanation depth, reminder schedule, and oversight context). Oversight context (independent / minor-supervised / managed-program) drives guardian and institutional transcript/progress/alert sharing rules.

3. Assessment and Evaluation#

The assessment system (/api/assessments) attaches evaluation instruments to courses and auto-grades objective responses. Beyond simple right/wrong scoring, it also computes live psychometric calibration from real learner data and detects differential item functioning across cohorts — capabilities that let instructors improve their assessments over time with empirical evidence rather than intuition.

• Assessments: Typed as quiz, exam, assignment, or practice, with a passing score, attempt cap, optional time limit and availability window, and toggles for question shuffling and showing correct answers after submission.
• Questions: Five question types — multiple_choice, true_false, short_answer, essay, and code — each with a point value, difficulty (easy/medium/hard), options, correct answer, explanation, and an optional hint.
• Submissions and auto-grading: A learner submits answers via POST /api/assessments/{id}/submit. The service validates attempt limits, auto-grades objective question types, computes a percentage score and pass/fail, and records the attempt. Essay and code questions are left for instructor manual grading.
• Live-data item calibration: GET /api/assessments/{id}/calibration returns per-question calibration computed from real learner submissions — a difficulty index, an IRT-style difficulty estimate, a discrimination index, and sample sizes — plus a mastery-threshold recommendation reporting balanced accuracy, precision, recall, and F1. A recompute endpoint refreshes it.
• Fairness and DIF review: GET /api/assessments/{id}/fairness-review reports differential item functioning (DIF) across learner cohorts, with a recommended action per item (monitor/recalibrate/retire), and adaptation-parity reviews. A recompute endpoint refreshes it. Calibration and fairness endpoints are restricted to the course author or an admin.
• Academic-integrity verdicts: A submission can carry an AcademicIntegrityVerdict produced by the Themis domain — detection signals, classifier outputs, evidence excerpts, a decision with an appeal path, the active policy binding, and governance metadata. The verdict schema enforces audit-completeness invariants (violation verdicts require evidence; severe verdicts require human review; clear verdicts cannot recommend sanctions).

4. AI Tutoring#

The tutoring system (/api/tutoring) runs conversational tutoring sessions backed by tutoring_sessions and tutoring_messages. The system is designed for pedagogical safety: integrity modes constrain how directly the AI answers, delivery-fallback logic ensures learners are never silently dropped to a degraded experience, and escalation paths hand off to a human when the AI cannot or should not respond.

• Sessions: A session is topic-scoped, optionally linked to a course and lesson, and has a tutor type of ai, human, or hybrid and a status of active, completed, abandoned, or escalated. Sessions track AI token usage, estimated cost, and a satisfaction rating.
• AI responses: POST /api/tutoring/sessions/{id}/generate-response generates an AI tutor reply. The service calls the configured LLM provider directly through its official SDK — OpenAI (gpt-4o by default) or Anthropic (claude-sonnet-4-20250514 by default) — selected by the ai_provider setting. If no provider key is configured, it falls back to a structured pedagogical response.
• Integrity modes: A session declares a tutoring integrity mode — teach, hint, practice, or do-not-complete-for-me — that constrains how directly the tutor may answer.
• Delivery modes and fallback: Tutoring can be delivered as text, live_voice, or live_avatar. A delivery-fallback mechanism degrades from avatar to voice to text when a runtime is unavailable or breaches a latency or fidelity budget, and emits learner-visible disclosures for each fallback stage. POST /sessions/{id}/delivery-health refreshes fallback state from runtime health signals.
• Live voice runtime: POST /sessions/{id}/voice-runtime provisions a short-lived live-voice bridge via the Psyche realtime runtime, with audio, voice-activity-detection, and transcript configuration. Companion endpoints record turn-taking and interruption events and resume a paused or interrupted runtime. The runtime supports barge-in, partial transcripts, session resume, turn-taking, and text fallback.
• Teacher representation safety: Each session resolves a teacher representation with a release status, consent status, disclosure label, and misuse-risk posture, plus an append-only consent and governance log.
• Escalation and handoff: A session can be escalated (low-confidence, safety-sensitive, or policy-sensitive) and handed off to a human tutor, teacher, guardian, or institution.
• Source-grounded tutoring: A session can require approved source material; AI tutor messages then carry an evidence bundle derived from the grounded response retrieval metadata.
• Tutoring quality evaluation: POST /sessions/{id}/quality-evaluation runs an embodiment-quality suite over a live tutoring session (speech, sync, and embodiment quality).

5. Source-Grounded Content Generation#

The source-ingestion pipeline (/api/source-ingestion) grounds generated educational content in reviewed source material. The core insight behind this system is that AI-generated content is only trustworthy when it can be traced back to specific passages in source documents that a human reviewer has approved. Every generation endpoint in Metis requires an approved, extracted package before it will produce content.

• Ingestion: A source package is created from files, remote URLs, feeds (rss/atom/jsonfeed), or LMS/institutional packages (scorm/imscc/lti_export/institutional_archive/zip_bundle). Files are staged through presigned upload targets. Each package is scoped to a course, workspace, notebook, or learner session.
• Extraction: POST /{package_id}/extract extracts text, structure, citations, metadata, content hashes, and rights posture from a package.
• Review and usage policy: A package goes through a review workflow with a status (pending/approved/changes_requested/rejected), a risk level, and recorded blockers. Grounded outline and grounded generation require the package to be approved and flagged high-stakes-allowed.
• Grounded outline and generation: POST /{package_id}/outline produces a grounded course outline from an approved, extracted package; POST /{package_id}/generate first attempts source-grounded lesson authoring through the explicitly configured OpenAI-compatible provider. The boundary fences retrieved text as data, rejects citations outside the exact retrieval result, retains provider/model and prompt/request/response digests, and keeps the result non-release pending verification. If the provider or evidence is unavailable, the deterministic lesson template remains available only as an explicitly labeled fallback; callers can disable fallback and receive a fail-closed 503. Assessments and study artifacts remain deterministic templates, so mixed aggregates are labeled mixed_unverified.
• Concept graph: POST /{package_id}/concepts/graph builds a concept graph whose nodes are typed (topic/skill/fact/procedure/principle) and whose edges express prerequisite-style relationships. The graph can be explored for prerequisite chains and graph-aware evidence retrieval, validated for cycles and orphans, and repaired with bounded operator-approved operations.
• Refresh and invalidation: POST /{package_id}/refresh re-snapshots remote-backed sources, diffs versions, and invalidates stale derived assets.
• Retrieval benchmark: POST /{package_id}/retrieval-benchmark runs a deterministic retrieval-quality benchmark against GraphRAG-style and hybrid baselines.
• Connector preview: Inspects staged LMS and institutional packages and surfaces importer previews.
• Study workspace: POST /study-workspace builds study guides, flashcards, quizzes, and tutor launches from scoped source bundles for a notebook or workspace flow.

6. Prerecorded Lecture Packages#

Courses can be turned into prerecorded multimedia lecture packages (/api/courses/{id}/lecture-package). This is how Metis bridges synchronous AI tutoring and asynchronous self-paced learning: an instructor triggers generation once and learners receive a polished package of narrated slides, captions, and study materials — without requiring a live AI session for every view.

• Lecture generation: A generation request specifies a target locale, a voice pack, a presentation template, caption/transcript options, subtitle formats (vtt/srt), dubbing locales, and pronunciation overrides, and can include a SCORM bundle.
• Package contents: A generated package contains, per lesson, narration script sections, caption cues, slides, diagrams, speaker notes / study guides, and narration variants (primary plus dubbed locales). It also produces render batches and export bundles with provenance and rights metadata.
• Rendered assets: Lecture render batches are labeled with the yemaya-batch-render provider; rendered slide, diagram, and notes assets are written to storage and served back via GET /lecture-package/assets/{asset_path}.
• Lecture media evaluation: POST /lecture-package/evaluation runs a lecture output-quality suite over the latest package; the result is persisted and retrievable.

7. Curriculum Discovery#

The curriculum router (/api/curriculum) exposes read-mostly catalogs that encode the Metis V1 curriculum. All data in this router is authoritative — it is not generated at runtime but maintained in code as a versioned taxonomy. This gives instructors and the course-generation pipeline a stable, queryable source of truth about which subjects are in scope and what treatment they warrant.

• Subject taxonomy: A versioned taxonomy of learning subjects. Each subject has a placement (core_discipline or supporting_subject), a role (headline or scaffolding_only), allowed treatments, and depth tiers. The core-six disciplines (philosophy, religion, psychology, neuroscience, anthropology, astronomy) headline the curriculum; supporting subjects default to scaffolding-only treatment.
• Subject lookup and routing: Free-form learner subject text can be resolved against the taxonomy; a pipeline route decides headline vs. scaffolding treatment for the tutoring or course-generation pipeline, including whether long-form curriculum, a full prerequisite graph, and advanced rubrics are permitted.
• Seed packs, standards mappings, reviewer pools, gold sets: Per-discipline curriculum launch assets — seed packs, standards mappings, expert reviewer pools, and gold-set bundles — plus a gold-set release-gate dashboard.
• Cross-core interlocks: Curated connections between core disciplines.
• Safety policies: Per-discipline curriculum safety policies, with an endpoint to evaluate content against a policy.

8. Agent Runtime#

The agent-runtime router (/api/agent-runtime, instructor-scoped) manages durable agent orchestration for content workflows. It exists as a separate concern from the tutoring and source-ingestion pipelines because it deals with multi-step, long-running agent plans that may require human approval gates, rollback capability, and formal research-integrity adjudication — concerns that do not fit inside a single synchronous request/response cycle.

• Agent registry: A catalog of Metis agents with versioned capabilities, lifecycle state (active/experimental/deprecated/disabled), release channel (stable/canary/shadow), cost class, trust zone, role visibility, and tool grants.
• Orchestration plans: A durable, replayable agent DAG with event topics, evidence records, approval gates, and kill switches (with pause / skip_stage / text_only / manual_review fallback behaviors). Plans are persisted and retrievable by build ID.
• Graph indexes: Persisted agent graph indexes with community summaries for lookup and traversal.
• Output verification: Deterministic symbolic, code, and numeric verification of generated agent output.
• Rollouts: Shadow, canary, and champion-challenger rollout plans with guardrail metrics, rollback, and kill switches.
• Evaluation: Versioned agent gold sets and rubrics, plus rubric scoring with privacy-preserving receipts.
• Safety screening: Deterministic threat, trust-zone, and tool-isolation screening before agent tools can execute.
• Research-integrity adjudication: Claim extraction, query decomposition, verifier checks, and safe-degradation / rollback decisions for generated research.

9. Credentials#

The credentials router (/api/credentials) issues and verifies digital credentials. Metis uses open standards (Open Badges 3.0 and IMS Global CLR) so that credentials can be verified by any standards-compliant verifier — learners are not locked in to the Oshun platform to prove what they have earned.

• Open Badges and CLR: Issues open_badge credentials and Comprehensive Learner Record (CLR) records, each emitting standards-conformant JSON-LD documents with IMS Global context URLs.
• Cryptographic proof: Each credential carries a DataIntegrityProof with an HMAC-SHA256-2026 cryptosuite, a canonical hash, and a proof value.
• Verification: A credential can be verified by ID/URL (suitable for a QR-code scan) or by submitting a presented credential document; verification returns a status (valid/invalid/expired/revoked/not_found) and a list of named checks.
• Revocation: An issued credential can be revoked with a reason, after which verifier endpoints fail it.
• CLR export: A learner's signed credentials can be exported in a CLR-compatible envelope.

10. LMS Interoperability#

Metis interoperates with learning management systems through dedicated routers. These integrations exist because many institutions already have an LMS and cannot migrate their entire workflow to a new platform. By speaking standard protocols — LTI 1.3, QTI 3, SCORM, xAPI, IMS Caliper, and OneRoster — Metis can slot into existing institutional infrastructure without requiring a custom integration.

• LTI 1.3 / LTI Advantage (/api/lti): Register an LTI platform, validate a tool launch and mint a Metis launch token, exchange a client assertion for a scoped token, build a Deep Linking response, read Names and Roles memberships, and create AGS line items and post AGS scores.
• QTI 3 (/api/qti): Import QTI 3 assessment item XML into normalized item-bank records and export item-bank records back to QTI 3 XML with a manifest.
• SCORM 1.2 / 2004 (/api/scorm): Create a SCORM fallback package with a manifest and runtime adapter for legacy LMS delivery, fetch the manifest, and commit and read token-protected SCORM CMI runtime state.
• xAPI / cmi5 (/api/xapi): Record idempotent learner activity statements, query them by learner/verb/object/registration/time/cursor, and replay them after a sequence cursor for downstream consumers.
• IMS Caliper (/api/caliper): Record idempotent Caliper analytics events, query them, and export them in a sensor envelope for institutional ingestion.
• OneRoster (/api/oneroster): Dry-run or apply a OneRoster rostering sync with conflict reporting (admin only).
• Course export: The export_course Celery task exports a full course to S3 in json or scorm format.

11. Learner Analytics#

The analytics router (/api/analytics) provides learning insights. Unlike the raw progress data in the course router, analytics aggregates and interprets learner activity into actionable signals — streaks, recommendations, reminders — that are cached in Redis to keep dashboard loads fast.

• Learner dashboard: GET /dashboard returns a personalized dashboard — streaks, course progress, recent activity, skills, tutoring metrics, and adaptive and graph-based course recommendations. Results are cached in Redis.
• Reminders: GET /reminders returns live learner reminders and continuation notifications derived from current activity.
• Achievements: GET /achievements returns the learner's earned achievements.
• Course analytics: GET /course/{id} returns enrollment totals, status breakdown, average progress, average rating, and completion rate for a course (course author or admin).
• Platform analytics: GET /platform returns platform-wide totals — users by role, courses by status, enrollments, submissions, tutoring sessions, and the platform average score (admin only, Redis-cached).
• Periodic aggregation: An hourly Celery beat task aggregates analytics.

12. Administration and Moderation#

The admin router (/api/admin, admin-only) provides operational surfaces for the humans responsible for keeping the platform safe and the content high-quality. These endpoints are intentionally separated from the instructor and learner surfaces so that administrative capabilities cannot accidentally be exposed to non-admin roles.

• Dashboards: An admin dashboard and analytics view, plus a Metis V1 launch-gate dashboard and an admin audit trail.
• User management: List and inspect users, update a user's status or role, and apply learner actions.
• Course management and approval: List and inspect managed courses and act on course approval requests (subject to publication release gates).
• Content moderation: List content flags and moderate them; list moderation incidents and record incident decisions.
• Review queues: A review-queue overview and per-queue listing, item detail, decisions, and avatar-teacher workflow actions.
• Incidents and complaints: An incident workspace and a learner-complaint workspace with complaint actions.
• Monitoring and alerts: A monitoring view, operator inspections, and alert configuration management.
• Source rights: A source-rights workspace and per-item rights decisions.

13. Platform Infrastructure#

The features above are all built on a shared infrastructure layer. This section describes the operational capabilities that every feature in Metis depends on: how requests are authenticated, how data is stored and cached, how background work is dispatched, and how the service exposes itself to operators.

• REST API: FastAPI application (metis.main:app) serving 16 domain routers under /api, plus root /health (liveness) and /ready (PostgreSQL
  • Redis readiness). An X-Request-Time header is added to every response.
• Authentication: JWT bearer tokens. The auth router issues an access/refresh token pair on register, login, and refresh. Role gates (student/instructor/admin) and resource-level ownership checks protect endpoints.
• Persistence: PostgreSQL via async SQLAlchemy 2.0, twelve tables created by a single Alembic migration; the Course → Module → Lesson hierarchy plus assessment, tutoring, enrollment, progress, and achievement tables.
• Caching: Redis, with a namespaced wrapper providing key prefixing, TTLs, and a sliding-window rate-limit helper.
• Object storage: S3 / MinIO via boto3 — buckets for courses, assets, exports, and uploads, with presigned upload/download URLs.
• Background tasks: Celery over Redis. Tasks are routed to six named queues; a beat schedule runs hourly analytics aggregation and daily cleanup of expired sessions and orphaned uploads.
• Document processing: PDF, DOCX, image, and OCR (tesseract) parsing for ingested source material.
• Observability: Structured logging via structlog (JSON in staging/production), optional OpenTelemetry tracing with an OTLP exporter and FastAPI/SQLAlchemy auto-instrumentation.
• Deployment: Docker images for metis-api, metis-worker, and metis-beat, composed with the shared Oshun infrastructure (PostgreSQL, Redis, MinIO, Mailpit).

14. Content Correctness Verification#

Because education is a verifiable domain, generated lessons pass through a correctness gate before release rather than being trusted on the strength of the generator alone (@metis/verification).

• Release gate — a VerificationGate composes independent verifiers into a single pass | needs-human | block decision. It is fail-loud: a required verifier with no backing model configured forces a refusal instead of a silent pass. Generation runs in a generate → verify → (regenerate|refine) → re-gate loop, with an optional best-of-N variant that picks the most-defensible candidate.
• Factual & faithfulness checks — lessons are decomposed into atomic claims, each verified against retrieved evidence and linked back to its supporting source span; RAG output is scored for groundedness, relevance, and completeness (TRACe); citations are checked for sufficiency.
• STEM correctness — mathematical identities are checked with a lightweight computer-algebra evaluator, code examples are executed in a sandbox against test cases, and worked solutions are verified step-by-step.
• Pedagogical quality — a judge panel scores rubric criteria with reliability diagnostics, abstaining on low-confidence items and routing them to human review; reading level, prerequisite ordering, and common misconceptions are checked.
• Operations — every verified artifact gets a tamper-evident evidence record; a human-in-the-loop queue captures reviewer decisions and feeds recalibration; per-mode compute budgets, cost/latency ceilings, drift monitoring, and champion-challenger promotion keep the gate honest in production.

15. Agentic Teaching Media#

Metis can generate teaching animations, not just composite supplied assets (@metis/agents + @metis/multimedia, with a Python Manim render worker).

• Author→critic loop — a Planner turns a verified lesson into a scene plan, a Coder compiles each scene to Manim code, the scene is rendered, and a Critic inspects the rendered layout for overlap/clutter/out-of-frame problems and re-checks any on-screen equation for correctness. The loop repairs and re-renders until the scene clears a quality+correctness bar or a render budget. No media is produced for a lesson the verification gate blocks.
• Sandboxed rendering — generated Manim/Python is rendered in an isolated, resource-limited worker (per-job working directory, wall-clock timeout, CPU limits) that returns an MP4 plus optional frames, or a structured syntax/runtime/timeout error — never a crash, and never a fabricated artifact when no renderer is available.
• Finished segments — rendered scenes are composited into a finished segment: one full-frame video layer per scene, synced TTS narration, a WebVTT/SRT caption track, a timestamped transcript, and an optional avatar/lip-sync overlay.

Cross-Domain Relationships#

The four external dependencies below are the only services Metis communicates with at runtime. Understanding the boundary in each case explains why these concerns are not handled inside Metis itself.

• OpenAI / Anthropic — LLM providers called directly for AI tutoring. Tutoring prompt design is tightly coupled to pedagogical intent, so there is no shared AI gateway layer — Metis calls provider SDKs directly and owns the fallback behaviour when no key is configured.
• Psyche — supplies the live-voice tutoring runtime. Metis provisions short-lived voice bridges and degrades to text on runtime failure. Audio transport and voice-activity detection are Psyche's concern; the pedagogical session model and turn-taking state machine belong to Metis.
• Yemaya — referenced as the lecture render-batch provider (yemaya-batch-render) for prerecorded lecture media. Metis orchestrates what to render and labels the batches; Yemaya is responsible for running the actual rendering workers. This keeps GPU-bound workloads out of the Metis service.
• Themis — supplies academic-integrity verdicts for assessment submissions. Metis is the consuming domain: it stores and surfaces the verdict but never runs detection itself. The Themis contract schema is mirrored in schemas/assessment.py so that payloads are validated at the Metis API boundary.

Metis owns educational content authoring, learner progress, assessment, tutoring, source-grounded generation, credentialing, and LMS interoperability.

Training-Data Flywheel (Phases 85–86)#

libs/metis/training-data implements this domain's side of the ML-sovereignty data flywheel: a training-data pipeline that captures educational-content interactions (lesson authoring, assessment outcomes, learner feedback) as passive training signals. Signals are consent-gated, anonymized where required, and emitted in the shared flywheel envelope that Nous dataset management (Phase 87) ingests for training and evaluation. Nous owns the training infrastructure; this domain owns what constitutes a high-quality domain signal.