Skip to content

2.1-to-2.2.md

Latest commit

 

History

History
162 lines (126 loc) · 7.34 KB

2.1-to-2.2.md

File metadata and controls

162 lines (126 loc) · 7.34 KB
Raw

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,735 symbols:

  • 6,116 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 adds public Maple task/runtime types and Compass vision-language loading and generation without removing an existing OpenMedKit API. 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.
  9. If adopting Maple or Compass, pin and verify external model artifacts, re-run task- and image-specific acceptance tests on the deployment device, and keep model outputs inside the same human-review boundary as other clinical extraction results.

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.

Maple and Compass runtimes

Python adds the MapleClinicalAssistant task API, MLX Maple export/runtime helpers, and the openmed.mlx Compass vision-language runtime. OpenMedKit adds OpenMedMaple* request, response, parsing, and MLX runtime types plus OpenMedVisionLanguageModel loading and generation.

These are additive APIs, but their model artifacts remain external. The Swift package also pins MLX Swift LM to a reviewed revision for multimodal generation. Deployments that do not enable these runtimes do not gain an implicit network or model-download path.

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.