Skip to content

Migrate from OpenMed 2.0 to 2.1

This guide covers the public compatibility boundary from v2.0.0 to v2.1.0. The Python comparison is static: it parses the exported openmed/ surface without importing the package or executing application code.

The current published v2.0.0 tag resolves to 94ace7d76386ac2047126c00ccd61bc23a5f3d3b on the repository's rewritten history. Older clones can retain the pre-rewrite tag object; verify the local tag before reproducing the comparison and use a fresh remote-tracking ref when the hashes differ.

Run the same comparison locally:

python scripts/release/api_surface_diff.py \
  v2.0.0 HEAD \
  --json api-surface-diff.json \
  --check docs/migration/2.0-to-2.1.md

Compatibility result

The static Python API inventory grows from 20,538 to 31,619 symbols:

  • 11,081 public symbols are added.
  • No public symbol is removed or renamed.
  • No existing callable signature is narrowed.
  • No existing symbol is newly marked with @deprecated.

The REST contract grows additively from 15 paths and 12 component schemas to 17 paths and 15 component schemas. The new POST /cohort/resolve and POST /omop/load operations do not replace an existing route.

Swift package sources are unchanged in this range. Kotlin/Android, JavaScript/Flutter, CLI, configuration, model-manifest, and evidence contracts require separate review because the Python AST comparison does not inspect them.

Upgrade checklist

  1. Install openmed==2.1.0 with only the optional extras the application uses.
  2. Re-run privacy, direct-identifier recall, critical-leakage, span-integrity, and deterministic safety tests on synthetic fixtures for every deployed language and script.
  3. Refresh cached MCP schemas and generated REST clients if the application consumes the new clinical workflow tools or the two new REST operations.
  4. On Android, verify any code that previously treated OpenMed offsets as Kotlin UTF-16 indices; the documented cross-platform contract uses Unicode scalar offsets.
  5. Re-run application-owned structured-data policies, terminology snapshots, and clinical extraction acceptance tests before enabling new workflows.
  6. Keep gated corpora, licensed terminology, PHI, and model files outside the package. New loaders remain caller-supplied and opt-in.
  7. If an Android application filters or pins catalog entries, re-evaluate that selection against the refreshed 753-entry public ONNX/TFLite catalog rather than relying on the previously empty generated asset.
  8. If an application relies on the former dedicated Tamil default, configure and qualify explicit weights. The old checkpoint is not in the public Hub catalog; the retained pii_ta_msuperclinical_large registry key now points to a documented compatibility placeholder rather than dedicated Tamil weights.

No before/after replacement snippet is required for a removed or deprecated Python symbol because the static comparison found neither category.

Android Unicode offsets

OpenMedKit now consistently returns half-open Unicode scalar (code-point) offsets from EntityPrediction, OpenMedSpan, token-classification decoding, and policy de-identification. This aligns Android with the documented Python and Swift contract and fixes spans that follow non-BMP characters.

ASCII and Basic Multilingual Plane-only text keeps the same numeric offsets. Applications that used the values directly with Kotlin String.substring or replaceRange on text containing emoji or other non-BMP characters must convert first:

val nativeRange = prediction.utf16SpanIn(sourceText)
if (nativeRange != null) {
    val covered = sourceText.substring(nativeRange.start, nativeRange.end)
}

snappedToGraphemeBoundaries is available when a caller needs a complete user-perceived grapheme rather than a raw scalar span. The bundled decoder and de-identification engine perform this repair internally.

The 2.1 AAR derives its catalog from the committed 2,266-entry public manifest snapshot and refuses to package an empty result. Catalog entries are discovery metadata, not downloaded weights or validation evidence; applications still need to acquire, cache, integrity-check, and qualify the selected model for their deployment.

Clinical, grounding, and interoperability additions

OpenMed 2.1 adds section and document-type routing, clinical coreference and temporal graphs, medication and problem relations, radiology and discharge structures, span-grounded fact recall, terminology snapshot loaders, local cohort phenotype resolution, OMOP loading, FHIR/OpenEHR export helpers, and typed MCP clinical workflows.

These APIs are assistive. They must not automatically trigger diagnosis, treatment, billing, or other clinical decisions. Validate terminology versions, abstention behavior, evidence spans, and downstream mappings with qualified reviewers.

Structured privacy and batch adapters

The structured-data surface adds declarative generalization, relational k-anonymity, aggregate-only differential-privacy generation, attacker-model risk reporting, and streaming tabular workflows. Apache Beam, Ray Data, PySpark, Haystack, LangGraph, and sdcMicro integrations are optional adapters.

The interop-gpl extra installs no GPL code. R and sdcMicro remain a separate, out-of-process, user-managed integration. DUA-gated corpus loaders require caller-supplied credentials and never bundle the underlying data.

Optional dependencies

OpenMed 2.1 adds focused extras for beam, ray, haystack, langgraph, grounding, yasbd, and the empty policy marker interop-gpl. The integrity and development paths move to cryptography>=50,<51; the lock also constrains known transitive combinations used by Beam and the MCP stack.

Install adapters only where needed, for example:

pip install "openmed[grounding]==2.1.0"
pip install "openmed[beam]==2.1.0"
pip install "openmed[ray]==2.1.0"
pip install "openmed[yasbd]==2.1.0"

CLI, MCP, and release evidence

New CLI groups cover model-cache management, batch-run resume/reporting, OMOP loading, cohort resolution, OpenEHR export, registry lineage, and release rollback. MCP adds typed grounding, FHIR export, risk, signed-audit, model search, and staged clinical-pipeline tools. Existing commands and tools remain available.

Release readiness still requires a real staged candidate, public SHIELD and golden benchmark evidence, signed extraction gates, this migration guide, the machine-readable API comparison, and a final decision of exactly READY. Missing candidate files are a failed evidence gate, not a successful no-op.