Device Capability Resolution¶
Resolver contract version 1 (OpenMed v4.0). OpenMedKit for Swift, OpenMedKit for Android, the openmed web package, and the Python package choose a model artifact the same way. Each kit keeps its own native probe and maps the result into one normalized device-capability profile. One resolver then combines that profile with a verified signed portable bundle and the caller's constraints. The output is an ordered execution plan, or an explicit unsupported result with a reason code.
Resolution is local, deterministic, and offline. It opens no network connection, loads no model, and runs no inference. A plan names only (runtime, provider) steps that the signed bundle declares. It never names a cloud service, a remote endpoint, or a model the bundle does not contain.
| Surface | Profile | Resolver |
|---|---|---|
| Python | openmed.core.device_capabilities.DeviceCapabilityProfile | openmed.core.execution_plan.resolve_execution_plan |
| Swift | DeviceCapabilityProfile.apple(...), .currentApple(...) | ExecutionPlanResolver.resolve(...) |
| Kotlin | AndroidCapabilityProbe.profile(...), .current(...) | ExecutionPlanResolver.resolve(...) |
| TypeScript | webDeviceCapabilityProfile(...), probeWebDeviceCapabilities(...) | resolveExecutionPlan(...) |
The JSON Schemas ship in openmed/core/schemas/json/: device_capability_profile, execution_constraints, execution_extension, and execution_plan.
Normalized profile¶
A profile is a closed JSON document. Every member is required, unknown members fail with profile_invalid, and lists are sets (sorted, without duplicates), so equivalent profiles always encode to the same canonical bytes.
| Field | Values | Unknown behavior |
|---|---|---|
platform | android, ios, linux, macos, visionos, watchos, web, windows | Required |
sdk_name, sdk_version | Reading SDK, matched against the bundle's compatibility.sdks | Required |
os_version | MAJOR or MAJOR.MINOR; Android uses the API level | null. A runtime with an OS range is then refused (os_version_unknown) |
cpu_architecture | arm64, armv7, wasm32, x86_64, unknown | unknown |
providers | Execution providers available on the device (see below) | Absent means unavailable |
accelerators | cpu, gpu, npu, derived from providers | Derived, never supplied |
runtimes | Bundle formats the SDK can load on this platform | Absent means unsupported |
precisions | fp32, fp16, bf16, int8, int4, int2 | Absent means unsupported |
features | cpu_neon, cpu_avx2, cpu_fp16, wasm_simd, wasm_threads, webgpu_shader_f16 | Absent means unavailable |
operator_sets | Highest operator-set version per format, such as ONNX opset | Missing format: a runtime that needs one is refused (operator_set_unknown) |
memory_budget_bytes | Memory the runtime may use, on the budget ladder | null: not enforced, reported as memory_budget_unknown |
storage_budget_bytes | Storage the model cache may use, on the budget ladder | null: not enforced, reported as storage_budget_unknown |
max_sequence_length | Longest token sequence the platform accepts | null: not enforced, reported as device_sequence_limit_unknown |
max_model_tier | nano, tiny, base | null: no tier ceiling, reported as model_tier_limit_unknown |
network | offline, online, unknown | Informational only. It never changes a plan and is excluded from the profile digest |
The rule for unknown values: a missing capability is unavailable, and a requirement checked against an unknown capability fails closed. A missing budget or limit is not enforced, but the plan lists it under assumptions so the caller can refuse the plan.
Budget ladder. Budgets are rounded down to 0 or a power of two from 16 MiB to 1 TiB. For example, Apple's 150 MB watchOS ceiling becomes 128 MiB, and 3 GB of browser memory becomes 2 GiB. Rounding down is conservative and keeps exact memory sizes out of profiles.
Privacy. A profile has no place for a device name, hardware model, serial number, vendor or adapter string, user agent, or build fingerprint. Adapters never read those values. The golden vectors plant such values in the probe inputs, and every kit asserts that none of them reaches a profile or a plan.
Providers and accelerators¶
| Provider | Accelerator | Platforms | Formats |
|---|---|---|---|
cpu | cpu | android, ios, macos, watchos, visionos, linux, windows | onnx, ort, coreml (CPU-only compute units), mlx, pytorch |
wasm | cpu | web | onnx, transformersjs |
webgpu | gpu | web | onnx, transformersjs |
metal | gpu | ios, macos | mlx |
coreml | npu | ios, macos, watchos, visionos | coreml, onnx, ort (Core ML may dispatch to the Neural Engine, GPU, or CPU) |
nnapi | npu | android | onnx, ort |
qnn | npu | android | onnx, ort |
Kit probes¶
Each adapter is a pure mapping from the kit's existing probe. Unit tests drive it with fake probes, and the Python reference normalizers (profile_from_web_probe, profile_from_android_probe, profile_from_apple_probe) define the expected output for the shared vectors.
| Kit | Probe | Normalized as |
|---|---|---|
| Web | detectOrtWebCapabilities / probeOrtWebCapabilities (runtime/capability.ts) | webgpu adds the webgpu provider and fp16; wasm adds the wasm provider; WebAssembly SIMD adds wasm_simd; SIMD plus SharedArrayBuffer, cross-origin isolation, and at least two hardware threads adds wasm_threads, the same rule as selectOrtWebBackend; any provider adds fp32, int8, and int4; the adapter's shader-f16 feature bit adds webgpu_shader_f16; navigator.onLine sets network. The architecture is wasm32 and there is no OS version or tier ceiling |
| Web | Caller options | sdkVersion, runtimes (default onnx), memoryBudgetBytes, storageFreeBytes, maxSequenceLength, operatorSets |
| Android | AcceleratorSession provider discovery | CPU always becomes cpu, QNN becomes qnn, and NNAPI becomes nnapi only from API 27, as in the session |
| Android | Build.VERSION.SDK_INT, Build.SUPPORTED_ABIS[0] | The API level is os_version. arm64-v8a becomes arm64 and adds cpu_neon; armeabi-v7a becomes armv7; x86_64 stays x86_64; anything else is unknown |
| Android | Caller inputs | memoryClassMb (from ActivityManager.getMemoryClass()) becomes the memory budget. deviceTier maps ENTRY to nano, MID_RANGE to tiny, FLAGSHIP to base, and DEVICE_FARM_STUB to no ceiling. Runtimes are onnx and ort; precisions are fp32, fp16, int8, and int4 |
| Apple | PlatformModelConfiguration | maximumResidentMemoryMB becomes the memory budget, maximumSequenceLength the sequence limit, and maximumTier the tier ceiling. requiresINT8 (watchOS, visionOS) limits precisions to int8 |
| Apple | Compile-time platform, ProcessInfo OS version, CPU architecture, MLX linkage | coreml and cpu are always available. metal, the mlx runtime, bf16, and int2 are added only on iOS and macOS when MLX is linked and not on the Simulator. arm64 adds cpu_neon |
Execution extension¶
Provider choice, required features, and qualification are part of the signed manifest. They live in the org.openmed.execution extension, keyed by runtime id:
{
"runtimes": {
"onnx-webgpu-fp16": {
"evidence": ["webgpu_parity"],
"features": ["webgpu_shader_f16"],
"max_sequence_length": 512,
"min_operator_set": 17,
"providers": ["webgpu"],
"tier": null
}
},
"schema_version": 1
}
providers: ordered attempts for this artifact. Each provider must be able to execute the runtime format.features: profile features the runtime needs.min_operator_set: lowest operator-set version the runtime needs.max_sequence_length: longest sequence the artifact accepts.tier: model tier, checked againstmax_model_tier.evidence: evidence kinds from the manifestevidencelist that qualify this runtime.
A runtime the extension does not describe gets its format's baseline provider for the profile's platform: wasm for ONNX on the web, cpu for ONNX and ORT elsewhere, coreml for Core ML, metal for MLX, wasm for Transformers.js, and cpu for PyTorch. It declares no features, sequence limit, tier, or evidence. A default never adds an accelerator or a fallback step.
A malformed extension makes the whole bundle execution_metadata_invalid. That covers a missing member, an undeclared runtime id, an unknown provider such as a remote service, a provider that cannot run the format, or evidence the manifest does not contain. Bundles may list the extension in critical_extensions, and the resolver accepts that. Pass org.openmed.execution in the verifier's understood extensions as well.
Caller constraints¶
| Member | Default | Effect |
|---|---|---|
local_only | true | Must be true. false returns remote_execution_unsupported, because there is no remote step to fall back to |
require_verified_files | true | The verification must cover the file tree, not only the manifest and signatures |
allowed_precisions | null (any) | Steps must use one of these precisions |
disallowed_providers | [] | Steps may not use these providers |
max_memory_bytes | null | Memory ceiling, combined with the profile budget (the lower one wins) |
min_sequence_length | null | Every step must support at least this many tokens |
energy | balanced | low_power excludes GPU providers (webgpu, metal) |
required_evidence | [] | Every step's runtime must declare these evidence kinds |
revoked_artifacts | [] | sha256: file digests no step may use |
max_steps | 4 | Upper bound on plan steps, from 1 to 16 |
deadline_ms | null | Recorded in the plan for the executor to enforce across steps. The resolver does not benchmark |
Fallback rules¶
- The caller verifies the bundle. The plan uses only runtimes in the verification's
eligible_runtimes, and only a verification withoktrue for these exact manifest bytes. - A root runtime is one that no other runtime names as its
fallback. Roots are tried in manifest order. - A root's chain is the root followed by its declared
fallbacklinks. The plan follows the first chain that contains at least one qualified step, and only that chain. Runtimes on other chains are reported asnot_declared_fallback. - Within one runtime, steps follow the extension's provider order. A later provider is a
provider_fallbackstep, and the next runtime in the chain is anartifact_fallbackstep. - Steps beyond
max_stepsare reported asfallback_bound_reached.
In practice:
- WebGPU to WASM happens only when the WebGPU runtime declares the WASM runtime as its
fallback. A bundle without that link has no WASM step. - Android accelerator to CPU happens only when the runtime lists
cpuafterqnnornnapi. A runtime that lists onlynnapiis unsupported on a device without NNAPI. - Apple tier fallback (base to tiny to nano) follows declared
fallbacklinks. A runtime that is too large for the tier ceiling or memory budget is skipped, and the plan moves down the declared chain.
Reason codes¶
Checks run in this order. The plan-level reason is the first failure. Each skipped runtime or pair reports its own first failure.
| Scope | Codes |
|---|---|
| Plan | remote_execution_unsupported, bundle_revoked, bundle_unverified, bundle_files_unverified, sdk_incompatible, execution_metadata_invalid, no_eligible_runtime |
| Runtime | runtime_not_eligible, artifact_revoked, format_unsupported, platform_unsupported, os_version_unknown, os_version_unsupported, precision_unsupported, precision_disallowed, memory_insufficient, storage_insufficient, model_tier_exceeded, sequence_limit_exceeded, sequence_limit_undeclared, operator_set_unknown, operator_set_unsupported, feature_unavailable, evidence_missing |
| Provider | provider_unavailable, provider_disallowed, energy_policy_excluded |
| Unused step | not_declared_fallback, fallback_bound_reached |
Malformed caller inputs raise errors rather than returning a plan: profile_invalid, probe_invalid, and constraints_invalid.
Plan document¶
A plan holds status (planned or unsupported), reason, root_runtime, steps, skipped, assumptions, bounds (max_steps, deadline_ms, and the effective max_memory_bytes), local_only: true, and the invalidation digests. Each step names runtime_id, runtime_index, format, precision, provider, accelerator, artifact_sha256 (the entrypoint file digest), min_memory_bytes, max_sequence_length, tier, evidence, and role. A plan contains no file paths, device identifiers, or model inputs.
Invalidation¶
A plan records bundle_content_id, profile_digest, constraints_digest, verification_digest, and plan_key, the digest of all four plus the resolver version. Before reusing a cached plan, re-probe the device, re-verify the bundle, and call plan_invalidation (Python), ExecutionPlanResolver.invalidation (Swift, Kotlin), or executionPlanInvalidation (TypeScript). The result lists the components that changed:
bundle: different manifest bytes.profile: an OS update, a new or lost provider, or a changed budget, feature, or limit.networkis not included.constraints: different caller policy.verification: a revocation, expiry, eligibility, or file-tree change.resolver: the plan came from another resolver version.
An empty list means the cached plan is still current.
Golden vectors¶
tests/fixtures/device_capabilities/vectors.json holds the shared corpus: synthetic probes with planted identity sentinels and their expected profiles, every named profile and constraint set with its digest, nine manifest variants, 57 resolution cases with the exact expected plan, and the invalidation cases. Every reason code and assumption has at least one case. Python, Swift, Kotlin, and TypeScript tests all consume the file.