Migrate from OpenMed 2.5 to 3.0¶

OpenMed 3.0 adds a versioned longitudinal Journey layer while preserving the local-first privacy boundary. Migration is an explicit data and contract operation; loading older records does not silently grant them v3 provenance, identity, consent, or review semantics.

This guide covers technical migration. It does not establish clinical validation, regulatory certification, or authorization for autonomous clinical action.

Before migration¶

OpenMed 3.0.0 is the prepared SDK candidate. The following pinned coordinates are intended for use after publication, not proof that packages or container tags are already available:

pip install --upgrade "openmed==3.0.0"
npm install openmed@3.0.0

SwiftPM: .package(url: "https://github.com/maziyarpanahi/openmed.git", from: "3.0.0"). Android: implementation("com.github.maziyarpanahi:openmed:v3.0.0"). Container: ghcr.io/maziyarpanahi/openmed:v3.0.0. Shared version numbers do not imply native feature parity across platforms; check the feature map and the relevant platform guide.

Pin the existing OpenMed package, model artifacts, tokenizer, policies, vocabularies, and database schema.
Export aggregate counts and digests for the source installation.
Back up the source store and test restore on an isolated system.
Inventory restricted models, datasets, and vocabularies. Keep them user supplied; do not copy them into the package or release fixture.
Record the intended v3 schema version, compatibility policy, storage backend, namespaces, consent policy, and retention policy.

Optional model runtime qualification¶

Model runtimes are optional and are not part of the base SDK dependency set. Torch-backed extras and current conversion/container recipes now require torch>=2.13.0; the frozen pair is Torch 2.13.0 / torchvision 0.28.0. Update downstream locks rather than overriding that security floor. Torch 2.13 macOS wheels require Apple Silicon and macOS 14+; Intel macOS is unsupported. Linux PyPI wheels use CUDA 13 dependencies, while the reference container uses the CPU wheel index. Validate the actual driver, architecture and converter. The full Maple export recipe requires Python 3.11+ because of its ONNX Runtime pin; this does not raise the base SDK's Python 3.10 minimum.

Audit the exact extra and deployment lockfile before enabling it. A passing core/development audit does not qualify Torch, Accelerate, GPU execution or model conversion. Follow the dependency policy; do not bypass its gate or treat a runtime upgrade as model qualification. The optional Accelerate checkpoint-index finding remains unresolved and has no approved exception; the Torch fix does not clear that separate risk.

Affected optional integrations also enforce Banks 2.4.5, Datasets 5.0.1, HTTP/2 4.4.1 and OAuthlib 4.0.0 security floors. These packages are not added to the base SDK. OAuthlib 4 removes JSONP revocation responses and validates grant types before client authentication; operators supplying their own OAuth server integrations must migrate those contracts independently of OpenMed's client URL and storage adapters.

Optional filesystem profiles also require fsspec 2026.6.0 and Jinja 3.1.6; graph/agent profiles require LangGraph SDK 0.4.4. The Beam profile requires PyMongo 4.18.2 for upstream host-parsing and BSON-size fixes. Operators using upstream Beam MongoDB IO must upgrade MongoDB Server 4.2 to 4.4 or newer before adopting this profile: PyMongo 4.18 no longer supports Server 4.2. OpenMed does not provide a native MongoDB storage API, and none of these packages is added to the base SDK.

Contract changes¶

V3 public and persisted Journey objects declare:

semantic schema version;
same_major compatibility policy;
stable opaque identifiers;
evidence locators bound to artifact digests and coordinate systems;
provenance and amendment history;
typed partial, unknown, conflict, unsupported, denied, and failure states; and
explicit consent, namespace, purpose, and review boundaries where relevant.

Do not map an absent v2 field to a fabricated v3 value. Use the appropriate typed state, preserve an explicit loss record, or require review.

Data migration sequence¶

Discover: inspect source schemas and counts without mutating data.
Plan: build a versioned mapping for artifacts, facts, identifiers, conflicts, corrections, and policy metadata.
Dry run: write to a new store or isolated namespace.
Validate evidence: verify offsets, coordinate systems, digests, and provenance links.
Validate semantics: compare fact counts, assertion state, units, partial dates, amendments, duplicates, conflicts, and correction history.
Validate identity: keep ambiguous matches unresolved and require review.
Validate consent: confirm that withdrawn or unavailable consent remains denied after migration.
Replay: repeat the migration against a fresh target and compare stable digests. Any duplicate effect or drift is a failure.
Recover: interrupt a synthetic run, restore from the documented checkpoint, and confirm the same result.
Cut over: change readers only after the isolated target passes the complete release gate.

The migration must never overwrite the only source copy. The v3 golden runner and release gate also refuse implicit replacement of existing outputs.

API and service migration¶

Continue to treat extraction results as assistive evidence, not final clinical decisions.
Adopt the versioned Journey resource page for facts, artifacts, conflicts, resolutions, cohorts, and datasets.
Handle every typed state explicitly. In particular, an empty page is not an unknown result, a denied result is not an empty result, and partial output is not success.
Bind pagination cursors to the full query and snapshot. Do not reuse cursors after a filter, role, purpose, consent, or namespace change.
Preserve idempotency keys across retries and record cancellation, checkpoint, lease, and invalidation outcomes.
Keep raw source values out of logs, telemetry, traces, and release evidence.

Breaking Python API migrations¶

The 3.0 major release deliberately changes exported signatures. The static API report records these changes rather than relabelling them as compatible. Update applications before upgrading; the release-readiness gate requires this guide to name every breaking symbol.

Unified grounding result and input name¶

openmed.clinical.grounding.api.ground, openmed.clinical.grounding.ground, and the imported openmed.mcp.server.ground now use text_or_entities instead of the former spans keyword. Positional input still works. The return value is a typed GroundingResult, not a bare list of GroundedSpan; consumers must handle uncertain and unsupported entries explicitly. Offline is now the default.

Before:

from openmed.clinical.grounding import ground

spans = ground(spans=entities, systems=["icd10cm"], loader=local_vocab)

After:

from openmed.clinical.grounding import ground

result = ground(text_or_entities=entities, systems=["icd10cm"], loader=local_vocab)
for concept in result.concepts:
    # Review ambiguous/unmapped outcomes; do not fabricate a resolved code.
    inspect(concept)

Explicit Journey resources and access policy in GraphQL¶

openmed.service.graphql_schema.OpenMedGraphQLContext and its re-export openmed.service.graphql_app.OpenMedGraphQLContext require both journey_resources and journey_access_policy, in addition to runtime. Before, applications constructed OpenMedGraphQLContext(runtime); after, construct OpenMedGraphQLContext(runtime, journey_resources, access_policy) from the application's reviewed catalog and policy. Never grant access merely to restore compatibility with the old constructor.

openmed.service.graphql_app.mount_graphql now requires a resource_getter. Before:

mount_graphql(app, runtime_getter=runtime_for_request)

After:

mount_graphql(
    app,
    runtime_getter=runtime_for_request,
    resource_getter=journey_catalog_for_request,
)

Supply the catalog through trusted application configuration and retain namespace, role, consent and purpose checks. The stock service app wires these dependencies; custom applications must do so explicitly.

Privacy and clinical behavior migration¶

Cross-run hashes and pseudonym linkage¶

Default canonical-span and pipeline-audit HMAC keys are private and random. One Pipeline retains its key for its lifetime, but independent pipelines and fresh deidentify(..., audit=True) calls no longer produce matching hashes. Trace redactors preserve pseudonyms within an instance, not across independent default instances. Update joins and reproducibility assertions that previously assumed cross-run linkage.

When linkage is intentional, provision the same non-empty, high-entropy private hmac_secret to the relevant Pipeline or TraceRedactor instances; the web SDK and React Native bridges accept an explicit private hashSecret for cross-call linkage. Keep keys out of source control and output artifacts. Offsets and labels are unchanged; unkeyed audit-integrity digests are not an anonymization boundary. See anonymization.

Clinical qualification boundaries¶

The composed Python EvidencePacket and build_clinical_brief contract accepts only synthetic evidence. A model or review callback does not authorize real-patient input. Do not relabel real evidence as synthetic to pass validation. The explicit extractive summarizer and synthetic fixture providers are technical baselines, not qualified clinical models. See the clinical brief contract.

Application-owned context providers can receive the original note before the composition guard; their networking, logging and storage remain the application's responsibility. The Python socket guard is not an operating-system sandbox. Review provider boundaries before enabling real deployments.

Remaining scope¶

The v3.0 candidate contains the eight fixes for doctor import diagnostics, explicit empty legacy offsets, tokenizer mappings, catalog row validation, CMEEE split discovery, calibration target validation, MedMentions alternatives and unmapped breaking-commit changelog entries. Consumers must preserve explicit empty annotations and typed unsupported or ambiguous results rather than coercing them to successful fallback output.

The separately scheduled v3.1 hardening work is not delivered by this candidate. In particular, do not assume differential-privacy report schema changes, new service authorization controls, stricter timestamp/script routing or expanded PDF/DICOM carrier sanitation merely from upgrading to v3.0. Inspect and qualify the actual enabled component before accepting sensitive inputs or exports.

Interoperability boundaries¶

V3 can preserve evidence from text, FHIR R4, HL7 v2, delimited tables, and DICOM SR-derived content and can project selected facts to OMOP. This does not make every source lossless.

Pin the exact FHIR profiles and terminology releases used by the deployment.
Preserve HL7 message structure and record unsupported segments or fields.
Keep DICOM coordinates and derived text tied to the originating artifact digest.
Record table column and row coordinates explicitly.
Treat partial dates, post-coordinated concepts, local codes, and unsupported OMOP fields as disclosed loss or review work.
Re-run downstream conformance tools supplied by the deploying organization.

Model and data migration¶

Training and publishing new models are optional, unscheduled research work, not requirements for a feature or SDK release. Keep existing qualified local models or supply your own independently reviewed local backend. Clinical brief generation still requires calibrated NLI and reviewed evidence; missing assets produce typed refusal. The explicit extractive summarizer needs no trained summarization model. Neither synthetic fixture callbacks nor deferred failed checkpoints count as clinical model qualification.

V3 does not require a mandatory cloud model. Model artifacts may remain local after an explicit download. For every model and data asset:

pin the content digest, tokenizer, format, quantization, and license;
record whether it is used for training, evaluation, runtime, or build;
record whether it can be redistributed; and
select bundled, metadata_only, user_supplied, or out_of_process as the distribution boundary.

Non-redistributable training data cannot be used to justify a distributable artifact in the v3 release gate. Restricted evaluation corpora and vocabularies remain user supplied.

Build release evidence¶

After the migrated target passes local checks:

Run the five-source golden Journey.
Produce aggregate reports for all ten mandatory lanes.
Freeze the scenario, golden output, schemas, policies, reports, and license catalog in the tagged checkout.
Run the v3 Journey release gate.
Verify the packet signature independently.
Keep promotion as a separate authorized action.

A release is blocked by critical leakage, invalid evidence, broken provenance, non-idempotent replay, migration or recovery failures, unreviewed high-risk output, undisclosed interoperability loss, stale or incomplete performance evidence, license violations, or unresolved high/critical security findings.

Rollback¶

Before cutover, define the exact rollback pointer and maximum recovery time. Rollback restores the previously verified application and store view; it does not delete the failed evidence packet or rewrite history. Preserve the packet, aggregate reports, tag, commit, and migration receipt for investigation.

After rollback, confirm:

source and target counts and digests;
no duplicate external side effects;
consent and namespace isolation;
review queues and unresolved conflicts;
model and policy pointer integrity; and
query and export denial behavior.

Known limitations¶

The committed golden journey is synthetic and intentionally narrow.
Migration tooling cannot infer missing consent, provenance, identity, or review decisions safely.
A passing standards fixture does not prove compatibility with every partner system.
Performance evidence applies only to its recorded hardware, dataset, quantization, and concurrency.
Technical release evidence is not clinical validation or a medical-device certification.
High-risk, ambiguous, conflicting, or insufficient-evidence output requires abstention or human review and must not trigger autonomous patient-care action.

Review the v3 Journey threat model before production cutover.