Migrate from OpenMed 1.8 to 1.9¶

This guide is generated from the public Python surface at v1.8.0 and the current release candidate. The comparison is static: it parses openmed/ source with Python's AST and never imports OpenMed or executes package code.

Run the same comparison locally:

python scripts/release/api_surface_diff.py \
  v1.8.0 HEAD \
  --json api-surface-diff.json \
  --check docs/migration/1.8-to-1.9.md

Compatibility result¶

The hand-audited v1.8.0-to-candidate diff contains no removed or renamed public Python symbols, no narrowed public callable signatures, and no existing symbols newly marked with @deprecated. There are therefore no breaking or deprecated entries that require before/after replacement snippets in this guide.

The generated inventory is additive: the current candidate has 3,810 more public symbols than v1.8.0, including class members and package-local re-exports. The most visible top-level additions are model-cache helpers and the ONNX inference API.

Additive Python surfaces¶

Model cache management¶

In 1.8, callers managed downloaded model snapshots through lower-level loader configuration. The additive cache API makes that lifecycle explicit:

from openmed import (
    clear_cached_model,
    list_cached_models,
    prefetch_model,
    resolve_repo_id,
)

repo_id = resolve_repo_id("pii")
local_path = prefetch_model(repo_id)
cached = list_cached_models()
clear_cached_model(repo_id)

These functions do not require changes to existing ModelLoader code. Network access remains explicit through prefetch_model; listing and clearing operate on the local cache.

ONNX inference¶

OpenMed 1.9 adds a direct ONNX Runtime inference surface alongside the existing backend adapters:

from openmed import OnnxEntity, OnnxModel, load_onnx_model

model: OnnxModel = load_onnx_model("path/to/exported-model")
entities: list[OnnxEntity] = model.predict("History of asthma.")

Existing MLX, Core ML, and PyTorch call sites remain valid; adopting ONNX is optional.

Offline model verification¶

OpenMed 1.9 adds an offline verification command for cached or local model artifacts. It checks the artifact against the signed manifest without sending model contents or clinical data over the network:

openmed models verify OpenMed/model-id
openmed models verify --all

This is additive. The existing openmed models validate <manifest> command continues to validate manifest structure.

Intentional deprecations¶

The candidate adds openmed.utils.deprecated for future transitions. It does not decorate any API carried forward from v1.8.0, so this migration has no deprecated-call replacement step. A future guide will show both forms when a symbol begins its warning window:

# Before
result = legacy_api()

# After
result = replacement_api()

Grounding and model-verification surface audit¶

The roadmap issue names four adjacent release surfaces. Three grounding-facing interfaces are not present in the current candidate, while offline model verification now ships. Recording each state explicitly prevents the migration guide from advertising interfaces that are not available.

Surface	`v1.8.0`	Current candidate	Migration action
Top-level `ground()`	Not exported	Not exported; the grounding registry notes that the facade is a later task	Keep existing linker integration until the facade lands
REST `POST /ground`	Not available	Not available	Do not send `/ground` requests to this release
Grounding MCP tool	Not available	Not available	Keep terminology grounding out of MCP calls until the tool is registered
`openmed models verify`	Not available	Available for local paths, model IDs, and `--all`; verification is offline	Adopt it for cached-model integrity checks; keep `models validate` for manifest structure

The REST and MCP rows are documented for release clarity, but they are outside the Python-only AST comparison. When those surfaces land, their implementation tasks must update this guide before a tag can pass the completeness gate.

Release completeness gate¶

Version 1.9 tag builds run the command at the top of this page against v1.8.0. Every detected breaking or newly deprecated symbol must appear exactly in this document. If an entry is removed or an undocumented required change is introduced, the command exits non-zero, prints each missing fully qualified symbol, and fails the release workflow. Other tags and non-tag workflow runs skip this historical migration step.