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.