Skip to content

Migrate from OpenMed 2.1 to 2.2

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

Run the same comparison locally:

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

Compatibility result

The static Python API inventory grows from 31,619 to 37,307 symbols:

  • 5,688 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 17 paths and 15 component schemas to 19 paths and 17 component schemas. The new POST /ground and POST /pii/deidentify/stream operations do not replace an existing route.

Swift package source is unchanged in this range. Android keeps its public method signatures, while the diagnostic representation of detected entities becomes PHI-safe by default. JavaScript, 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.2.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, script, document format, and quantized runtime.
  3. Refresh cached MCP schemas and generated REST clients before adopting the grounding or streaming de-identification routes.
  4. Re-qualify application-owned terminology snapshots, FHIR profiles, OMOP mappings, structured-data policies, and clinical extraction acceptance tests before enabling the new workflows.
  5. Keep licensed vocabularies, gated corpora, PHI, credentials, and model files outside the package. New loaders and bridges remain caller-supplied and opt-in.
  6. On Android, audit diagnostics that interpolate EntityPrediction values. Use the explicit text field only inside a local UI boundary and never send it to logs, telemetry, crash reports, or remote diagnostics.
  7. Validate FHIR Bundle references and OperationOutcome reports, and retain digest-only Bulk Data checkpoints when resuming an exchange workflow.
  8. Treat structured release recommendations and clinical mappings as assistive evidence requiring qualified review; they must not automatically trigger diagnosis, treatment, billing, or data publication.

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

Preserved public names

Two package reorganizations required explicit compatibility bindings during the release audit:

  • openmed.clinical.grounding.SnapshotManifest remains the v2.1 snapshot-cache manifest. The new vocabulary manifest is exported as openmed.clinical.grounding.VocabularySnapshotManifest.
  • openmed.clinical.exporters.omop.ConceptResolver remains a public type alias after the OMOP exporter moved from a module to a package.

Existing imports keep their v2.1 meaning. New code that handles terminology vocabulary manifests should use VocabularySnapshotManifest explicitly.

Android diagnostic descriptions

EntityPrediction.description no longer contains the detected source text. It emits the label, Unicode-scalar offsets, confidence, and a SHA-256 digest. This is an intentional privacy hardening of diagnostic output, not a change to the prediction fields or span contract.

Applications may still render the explicit text field locally when that is necessary for an approved user interface. Do not rely on description as a source-text transport and do not add text to diagnostic or telemetry paths.

Clinical exchange and grounding

OpenMed 2.2 adds a local-first terminology workbench, pinned vocabulary snapshots, ranked grounding and calibration, caller-supplied Athena and crosswalk support, FHIR R4 patient-summary and clinical-document assembly, explicit R4/R5 boundaries, local profile validation, SDC privacy projection, Bulk Data resume support, and a FHIR-to-OMOP CDM 5.4 bridge.

No licensed terminology is bundled. Callers are responsible for vocabulary rights, snapshot integrity, version pinning, abstention policy, mapping review, and downstream clinical validation.

Document intake and structured privacy

Document intake expands with deterministic form and key/value extraction, cross-format offset projection, PDF table reconstruction, XLSX, PPTX, and ODT handling, HL7 v2 narrative extraction, X12 837 redaction, and fail-closed MIME quarantine.

Structured privacy adds k-anonymity, l-diversity, t-closeness, membership-inference self-tests, aggregate-only differential privacy, and review evidence for release decisions. These tools report risk and policy evidence; they do not guarantee that a dataset is anonymous or suitable for release.

Optional dependencies and integrations

OpenMed 2.2 adds focused fhir, dagster, and sqlalchemy extras and expands the multimodal and service extras. It also adds opt-in adapters for Arrow Flight, PostgreSQL PL/Python, executable UDFs, distributed SQL, Dataflow, Dagster, Ray, pandas-on-Spark, search ingest, and stream processors.

Install only the adapters needed by the deployment, for example:

pip install "openmed[fhir]==2.2.0"
pip install "openmed[dagster]==2.2.0"
pip install "openmed[sqlalchemy]==2.2.0"

External databases, services, credentials, and runtimes remain explicit trust boundaries. Core local processing does not require them.

Release and model evidence

OpenMed 2.2.0 is an SDK release and does not promote a model pointer. The committed PII/latest and PII/last_green pointers both remain OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1-mlx; PII/canary remains unset.

A future model promotion still requires a real staged candidate, public SHIELD and golden benchmark evidence, signed extraction gates, and a final decision of exactly READY. Missing candidate artifacts fail a model-promotion dispatch; they are not fabricated for an SDK tag whose pointers are unchanged.

The v2.2 tag is instead qualified by retained last-green model evidence, the v2.2 synthetic conformance matrix, this migration guide, the machine-readable API comparison, and exact-commit package and platform gates.