Model Registry¶

OpenMed ships a manifest-backed registry (openmed.core.model_registry.OPENMED_MODELS) that annotates every official checkpoint with metadata such as category, specialization, recommended confidence, Hugging Face IDs, device fit, and benchmark summaries. Use it to pick the right model, surface dropdowns in UIs, or validate incoming requests.

The clinical NLI checkpoint preparation documents a planned sequence-classification release. It does not add a model alias.

Family API compatibility¶

RegistryService retains the v2.3 family-based signatures and schema-v1 return values. Caller-owned v1 files remain usable without migration. The committed v2 state is exposed through a read-only family view when every family has one unambiguous slot; mutations retain the stored v2 schema and its coordinate checks. Multi-slot applications explicitly use SlotRegistryService and openmed.core.registry_slots helpers. See the 2.3-to-2.5 migration guide for both contracts.

Exploring the registry¶

from openmed.core.model_registry import (
    get_all_models,
    list_model_categories,
    get_models_by_category,
    get_model_info,
    get_model_suggestions,
)

print(list_model_categories())

oncology_models = get_models_by_category("Oncology")
for info in oncology_models:
    print(info.display_name, info.model_id, info.recommended_confidence)

info = get_model_info("disease_detection_superclinical")
print(info.description, info.entity_types)

suggestions = get_model_suggestions("Metastatic breast cancer on paclitaxel.")
for model_key, info, reason in suggestions:
    print(model_key, info.display_name, reason)

• ModelInfo objects include display_name, category, entity_types, size hints, benchmark data, optional latency/RAM maps, optional recommended tier, audited script_coverage, and a default confidence threshold.
• get_model_suggestions leans on lightweight heuristics to recommend models based on text snippets or hints (disease, pharma, oncology, etc.).

Registry slots and pointers¶

Committed release-channel state lives in gates/registry_state.json (schema v2), keyed by family::tier::format slots — the same normalized key used by gates/baseline.json, gates/rollout_state.json, and the release ledger. Slots are sparse release channels: one is created only when a checkpoint is promoted with a RELEASABLE gate report whose (family, tier, format) coordinates match its manifest row, and latest names the selected shipping target for that channel, not the only manifest candidate. Untiered checkpoints use the family::none::format slot. Each slot records assigned SemVer per checkpoint — 1.0.0 for the first target, a minor bump for each new target, preserved on reload and re-promotion, and never parsed from the repo id (a -v1 in a checkpoint name is part of the upstream model name, not a version sequence).

The committed registry state also publishes generated model cards for the latest PII checkpoint and its last-green rollback target. A v1 (family-keyed) state file migrates deterministically with python scripts/release/registry_ctl.py migrate; the migration refuses ambiguous coordinates and leaves the file unchanged on any error.

Metadata for UIs & validation¶

• ModelInfo.size_category, .size_mb, .latency_ms, .peak_ram_mb, and .recommended_tier help you decide whether a model can fit on CPU-only infrastructure or a target device tier.
• entity_types feed dropdowns or filter chips in your frontend.
• recommended_confidence can drive slider defaults or guardrails on API calls (pass it to analyze_text).
• get_pii_models_by_language excludes any model whose audited tokenizer is explicitly unsupported for a script claimed by that language. The underlying UNK, byte-fallback, and tokens-per-grapheme measurements remain available on ModelInfo.script_coverage for diagnostics and UI warnings.

Plan downloads before using data¶

Use models size to inspect download, disk, and estimated peak RAM requirements from the committed manifest. The default path is offline-safe and does not contact Hugging Face:

OPENMED_OFFLINE=1 openmed models size disease_detection_tiny
openmed models size --budget-mb 100
openmed models size --budget-mb 100 --format json

With a budget, the command lists only models whose remaining download fits and recommends the smallest qualifying snapshot for each task. Models already in the local Hugging Face cache are marked cached — 0 MB to download and count as zero against the budget.

Use --remote only when you explicitly want to refresh an estimate from the current Hub file metadata. Supplying an alias keeps that opt-in lookup focused:

openmed models size disease_detection_tiny --remote

Sizes use decimal megabytes (1 MB = 1,000,000 bytes). Remote inspection requires the optional openmed[hf] dependencies; ordinary offline estimates do not.

Keeping the registry fresh¶

If you add a new Hugging Face checkpoint, refresh models.jsonl and, when measurements are available, enrich it with benchmark and device-fit results. See Model Manifest for the schema and merge command.

Manifest rows drive openmed/core/model_registry.py; avoid hand-editing the registry for new models. A new row should include:

1. The full HF model id (OpenMed/...) and core release metadata.
2. Representative canonical entity labels.
3. Required 11-script tokenizer coverage for PII-family entries, plus optional benchmark, latency, RAM, and recommended-tier enrichment.
4. Per-format download sizes and per-script recall/leakage-floor evidence when the release model card advertises those decision fields.

Regenerate all committed catalog surfaces from the local manifest, then review the resulting README, registry-card, and table changes:

python scripts/manifest/regenerate_surfaces.py

The command does not contact Hugging Face. CI runs the same command and rejects any generated diff, so manifest refreshes must commit every derived surface.

Manifest-backed catalog¶

The committed manifest contains 2,266 entries across 35 model-backed PII languages. Family counts: General=9, NER=1,093, PII=1,018, Vision=3, ZeroShot=143.