# V9-001 source-grounded model lesson generation

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.
