Eve library

V9-001 source-grounded model lesson generation

Evidence

Revision 1

On this page

Date: 2026-07-25

Source commit: 6c1ce4df9bba1e305c9d1082d1bc8c8d3a8c9cee

Claim#

The Python source forge now has a production-capable OpenAI-compatible model path for lesson authoring. SourceGenerationService invokes that path before its deterministic availability fallback when a provider is explicitly configured and approved retrieval returns evidence.

This is implementation evidence, not a live-provider or learner-release claim. No provider credential was used and no external response was retained in this slice. Model-authored output is therefore labeled generated_draft, retrieval_grounded_unverified, and release_eligible: false. The existing deterministic output remains labeled deterministic_template, template_draft, structure_only, and release_eligible: false.

Governed model boundary#

The source package must be approved and high-stakes-allowed even when the service is called directly rather than through the API. The model path also requires at least one result from the existing package-scoped retrieval service.

The provider prompt uses the shared Python prompt-trust renderer. Lesson specification, objectives, subject routing, curriculum-safety context, and retrieved source text are fenced as untrusted data. The provider is instructed to return strict JSON containing lesson content and the citation IDs it used.

The implementation independently enforces:

  • every declared citation exists in the exact retrieved result set;
  • every used citation has an inline [citation:CITATION_ID] marker;
  • provider, model, prompt version, prompt hash, request hash, response hash, retrieved result IDs, used citation IDs, and token counts survive persistence;
  • aggregate and lesson authoring-mode, artifact-status, and evidence-scope combinations cannot be relabeled inconsistently; and
  • no model result or template becomes release-eligible at this stage.

An invented citation, malformed provider response, request failure, or invalid evidence receipt cannot become a model-authored lesson. With allow_template_fallback: true, the service emits the existing disclosed template and records a bounded reason such as model_generation_failed:ValueError. With fallback disabled, it raises SourceLessonGenerationError; the HTTP route exposes that unavailable authoring path as 503 rather than returning unlabeled template content.

The aggregate reports model_generated only when all lessons are model generated and no deterministic assessment or study-artifact auxiliaries are included. Mixed model/template output is labeled mixed and mixed_unverified.

Configuration and contracts#

The path is off by default. Deployments select openrouter or openai through METIS_SOURCE_GENERATION_MODEL_PROVIDER and configure a dedicated key, with optional model, base URL, and timeout overrides. The checked-in environment example documents those controls without activating a provider.

The canonical OpenAPI document and generated TypeScript client expose the model, mixed, and fallback states, allow_template_fallback, and the model evidence receipt. Contract freshness passes.

Verification#

Check Result
Source-generation routing and direct provider specifications 7 passed
Source subsystem suite (test_source_*.py) 84 passed, 2 expected skips
Focused OpenAPI/export and source-generation suite 26 passed
Ruff format and lint on changed Python passed
Strict MyPy on changed production Python passed
pnpm metis:contracts:check passed
OpenAPI generated TypeScript freshness passed

The direct adapter tests verify trust-zone rendering, valid provider receipts, unknown-citation rejection, explicit configuration, model-result persistence, schema-level relabeling rejection, recorded fallback, and strict no-fallback failure.

Published artifact identities#

Artifact SHA-256
apps/metis/service/src/metis/services/source_lesson_model_provider.py 889e5af92508a77630aa9a9da84e9097c10045132308e55bc8c30298020fdee6
apps/metis/service/src/metis/services/source_generation_service.py 9eef0b3627c2916497aad941ed5e54fa1f82c6577cb65d4ed99ecb5f1a5a29fc
apps/metis/service/src/metis/schemas/source_generation.py 49e52607adf2cb4f2c137b6f5bce4e91ae8f6263d031f8805b824219bc8a3a28
apps/metis/service/tests/test_source_lesson_model_provider.py 9ebbafc12006ef9f79f51b5e726966250654f4102e75ccc23ed17d65b452c13d
apps/metis/service/tests/test_subject_matter_routing.py ed5580de19c57878ca7bc8743ee9c53485e7c5f1350139d29dda8a3a013514d6
apps/metis/service/openapi/metis.openapi.json cf864687c2351494f2d9d025897cf94c75e92b105ddce90ba1c29edb034aba90
libs/openapi/src/generated/metis.ts 393aebdcd3802d3138f7bb899933c9b7534bdfe9edd308c346686ef7888b703d

Remaining boundary#

This slice did not itself supply a production approved source bundle, replace retrieval with a calibrated entailment decision, prove a live provider call, connect TypeScript verification evidence to Python promotion, or complete the full adaptive/rendered learner path. Subsequent increments connected TypeScript verification to Python promotion and made exact retrieved-passage bytes plus semantic entailment mandatory on the ordinary lesson-release path; see V9-001-TRANSACTIONAL-PROMOTION.md and V9-001-RETRIEVAL-ENTAILMENT.md. Production-approved source acquisition and a complete live learner path remain open.