Skip to content

Migrate from OpenMed 2.2 to 2.3

This guide covers the public compatibility boundary from v2.2.0 to v2.3.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.2.0 HEAD \
  --json api-surface-diff.json \
  --check docs/migration/2.2-to-2.3.md

Compatibility result

The static Python API inventory grows from 37,735 to 41,729 symbols:

  • 3,994 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 remains at 19 paths and 17 component schemas. Swift, Kotlin/Android, JavaScript, CLI, configuration, trace schemas, evidence records, model artifacts, and deployment contracts require separate review because the Python AST comparison does not inspect them.

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

Upgrade checklist

  1. Install openmed==2.3.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. Re-qualify application-owned multimodal asset profiles, manifest limits, digest policies, abstention handling, and document parsing acceptance tests.
  4. Refresh generated CLI, REST, schema, agent-outcome, and trace consumers before adopting the new machine-readable contracts.
  5. Keep PHI, credentials, restricted datasets, licensed vocabularies, external model weights, and third-party runtimes outside the package and its evidence.
  6. Treat clinical evidence, SDOH extraction, record filtering, terminology mappings, and training outputs as assistive evidence requiring qualified review; they must not trigger diagnosis, treatment, billing, or publication.
  7. Exercise each enabled desktop, browser, Android, Apple, TensorRT, WebGPU, search, batch, or cluster adapter on the actual deployment platform.
  8. Review container, Helm, Kubernetes operator, HPA, sidecar, and remote-function policy before rolling out the new operational surfaces.

Multimodal intake and provenance

OpenMed 2.3 adds bounded asset manifests, streaming digests, media-type detection, typed abstention records, deterministic manifest profiles, expanded PDF layout and fidelity tooling, local email handling, and privacy-safe text extraction and redaction across additional document formats.

These APIs fail closed on malformed or unbounded inputs. Preserve caller-owned stream semantics, use the declared size and digest limits, and retain only the metadata, offsets, hashes, and aggregate evidence needed for review.

Agent, trace, and training contracts

Agent runs gain closed outcome codes, deterministic summaries, monotonic timing records, consent-verification results, and PHI-safe failure reasons. Trace tools add local discovery, schema-preserving redaction, streaming and parallel execution, transactional recovery, fidelity checks, and training-schema adapters.

Training adds teacher-ensemble manifests, deterministic federated-round records, and reproducibility verification. These are additive contracts, but downstream schema consumers should refresh snapshots and explicitly handle new closed vocabularies before enabling them.

Integrations and runtimes

The release adds opt-in adapters for OpenSearch, Elasticsearch, Spark, Beam, Airflow, LlamaIndex, PostgreSQL, dbt, warehouse remote functions, Kubernetes, browser extensions, Electron, Tauri, Android accelerators, TensorRT, GGUF, and WebGPU. External processes, clusters, browsers, databases, model files, and credentials remain explicit trust boundaries.

The MedCAT bridge remains out of process, installs no restricted dependency, and requires explicit acknowledgement of its third-party license. Core local processing does not gain a mandatory network or telemetry path.

npm token-classification compatibility

The npm default model is now OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1-onnx-android, exported as DEFAULT_MODEL_ID; -onnx-android repositories use the root INT8 loader. Install the optional @huggingface/transformers peer for this path, or inject your own local pipeline. Model download is separate from local inference.

Existing TokenClassificationEntity, TokenClassificationPipeline, and model loader outputs retain the v2.2 numeric start and end contract. The additive RawTokenClassificationEntity, RawTokenClassificationPipeline, and RawTransformersRuntime types accept runtime input that can omit offsets. Call alignTokenOffsets(text, tokens) to convert raw tokens to aligned entities; model loaders perform this conversion before returning pipeline output. Final OpenMedSpan offsets remain required and use JavaScript UTF-16 indices.

extractPii() retains O tokens for sequential alignment. Explicit pipeline offsets are preserved; missing offsets are reconstructed with case/accent and token-marker normalization. Unknown or unalignable tokens raise a content-free error rather than silently omitting redaction spans. For custom tokenizers or filtered output, provide exact source offsets and handle alignment errors as a failed scan, never as evidence that the document contains no PII.

Release and model evidence

OpenMed 2.3.0 is an SDK release and does not itself promote a model pointer. Model conversion, evaluation, and publication are explicit local maintainer operations. Any future pointer promotion still requires a real staged candidate, public SHIELD and golden evidence, signed extraction gates, and a final readiness decision of exactly READY.

The SDK tag is qualified independently by this migration guide, the machine-readable API comparison, exact-commit unit and platform gates, package artifact inspection, and the retained last-green model evidence.