Low-resource language cohort and graduation contract¶

openmed.clinical.languages.graduation names the first cohort of low-resource clinical locales and the contract a locale must pass before OpenMed claims support for a task in it. The cohort is a small, explicit list. It is not a promise to support every language in one release.

Every locale records:

• a license/lineage record for its weights, fixtures and surrogates;
• a review role code (native_clinical_reviewer), never a person's name, and whether that role is filled;
• a synthetic fixture plan with the committed golden records, the critical labels they already cover, a target slice size and the script or morphology stressors to author;
• an explicit experimental or supported status.

No cohort locale has native-review or evaluation evidence in the repository yet, so all of them start experimental with the review role unfilled.

Initial cohort¶

All bundled weights and committed fixtures in the cohort are Apache-2.0. The ne and yo routes ship no weights, so their model license is empty rather than assumed. Restricted or DUA-gated corpora are never bundled: a lineage record that declares them is rejected.

Why these locales¶

Each criterion maps to evidence that already exists in the repository:

The cohort deliberately spans every route a low-resource language can take today: the declared multilingual fallback, the compatibility placeholder, a user-supplied model and the deterministic national-ID-only path. Other low-resource packs (for example xh, ig, ha, ml) wait for a later cohort.

repository_language_inventory() rebuilds this evidence from the language-pack catalog, the model manifest, the surrogate-locale report, the synthetic locale generators and the golden fixture metadata. It reads codes, counts and labels only and does not include fixture text in its output. cohort_inventory_findings() compares it with the declared cohort, and the unit tests require zero findings. A route, locale, script or license change, or a record that claims more evidence than the repository holds, fails the suite. New evidence, such as an added fixture, leaves the record conservative until it is refreshed.

The table and cohort records preserve selection-time evidence. The current inventory also records the explicit augmentation-only generators for ha, ig, yo, rw, tl and ne. That generator evidence does not add bundled model routes, fill native-review roles or graduate a language.

Status and fail-closed tasks¶

Only deidentification has a graduation contract. Every other task in the closed task vocabulary is unsupported for every cohort locale and always fails closed, with or without the experimental opt-in.

from openmed.clinical.languages.graduation import (
    INITIAL_LOW_RESOURCE_COHORT as cohort,
    LanguageGraduationError,
)

assert cohort.task_status("sw", "deidentification") == "experimental"
assert cohort.require_task("sw", "deidentification", allow_experimental=True) == (
    "experimental"
)
for task in ("deidentification", "summarization"):
    try:
        cohort.require_task("sw", task)
    except LanguageGraduationError as error:
        print(task, error.code)  # task_not_supported

Refusals carry fixed codes: language_not_in_cohort, locale_not_in_cohort (a region that differs from the recorded locale), invalid_language, unknown_task and task_not_supported. Messages never echo the request.

This gate governs support claims and callers that opt in to it. It does not change how deidentify() routes a language today. Experimental output stays assistive and needs human review.

Graduation contract¶

evaluate_graduation() checks aggregate evidence for one locale and task. Every gate is independent; a single failure keeps the locale experimental. A contract may tighten any threshold but never loosen it past its policy floor, and it may add critical labels but never remove one.

Critical-identifier recall is non-compensable. Each critical label must pass both its point recall and its Wilson lower bound on its own, and a missing label fails rather than being skipped. The report includes the micro-averaged recall for context, but a high average never offsets one failing label. A small slice with perfect point recall still fails the lower bound, which is how uncertainty enters the decision.

Cross-lingual regression is bounded per cell. The caller names the already-supported reference languages (never the candidate itself), and every (reference language, critical label) cell must be present, large enough and within the regression bound. An improvement in one cell cannot offset a drop in another. Unexpected cells also fail.

The remaining gates also block graduation:

• the review role must be active in the cohort record and the evidence must carry an approved review from the same role;
• evaluation fixtures must be native-authored synthetic or native-reviewed translations, so machine translation alone never graduates a locale;
• routes without bundled weights (user_supplied_model, national_id_only) cannot graduate a model-backed task.

graduate() re-runs the evaluation and returns the promoted record with the report digest bound to the task. A record cannot be declared supported without such a digest, an active reviewer and bundled weights.

Evidence and readiness¶

Evidence is content-free: counts, controlled codes and 64-character SHA-256 references to lexicon, fixture, evaluation, native-review and package artifacts held elsewhere. GraduationEvidence.to_readiness_evidence() projects those references onto kind, task, digest and model_tier fields, so the same evidence can feed the clinical language readiness inventory without either module importing the other.

Reports and cohort JSON are deterministic and contain only codes, counts, ratios and digests. They contain no reviewer names, note text, spans, paths or model outputs.