Skip to content

Answering

The successful shape, and the failure taxonomy. The error category is not paperwork: KAI-C routes on it, so the difference between a transport_error and a model_error is the difference between one dropped frame and a retry storm.

opennvr_adapter_sdk.InferResponse

Bases: BaseModel

Successful response shape for POST /infer.

opennvr_adapter_sdk.ErrorCategory

Bases: str, Enum

Failure envelope category. Consumers use this to decide retry policy.

opennvr_adapter_sdk.ErrorDetail

Bases: BaseModel

The error block inside the failure envelope.

opennvr_adapter_sdk.FailureEnvelope

Bases: BaseModel

Standard error response used by every endpoint.

opennvr_adapter_sdk.FairQueuing

Bases: str, Enum

How KAI-C should schedule traffic across cameras into this adapter.

opennvr_adapter_sdk.accelerator_available

accelerator_available(available=None) -> bool

Does this build carry an accelerator provider at all (CUDA, OpenVINO, TensorRT, ROCm, a registered plugin …)? The §8 gpu permission declares exactly this.

Source code in opennvr_adapter_sdk/providers.py
637
638
639
640
641
642
def accelerator_available(available=None) -> bool:
    """Does this *build* carry an accelerator provider at all (CUDA, OpenVINO,
    TensorRT, ROCm, a registered plugin …)? The §8 ``gpu`` permission declares
    exactly this."""
    provs = list(available) if available is not None else available_providers()
    return any(p not in _NOT_ACCELERATORS for p in provs)

opennvr_adapter_sdk.build_with_fallback

build_with_fallback(
    build, requested, *, adapter: str = "adapter"
)

Run build(providers) with the requested providers; if that raises and an accelerator was requested, log the error and build again on CPU.

Returns (obj, providers_used, fallback_error): fallback_error is None when the first attempt succeeded, else the error text (hand it to :func:effective_providers). An accelerator that cannot even start — device missing from the container, driver absent, plugin crash — must never take the adapter down with it: the adapter serves on CPU and /hardware/evaluation says why. A failure with no accelerator requested is a real error and propagates.

Source code in opennvr_adapter_sdk/providers.py
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
def build_with_fallback(build, requested, *, adapter: str = "adapter"):
    """Run ``build(providers)`` with the requested providers; if that raises
    and an accelerator was requested, log the error and build again on CPU.

    Returns ``(obj, providers_used, fallback_error)``: ``fallback_error`` is
    ``None`` when the first attempt succeeded, else the error text (hand it
    to :func:`effective_providers`). An accelerator that cannot even start
    — device missing from the container, driver absent, plugin crash —
    must never take the adapter down with it: the adapter serves on CPU
    and ``/hardware/evaluation`` says why. A failure with no accelerator
    requested is a real error and propagates.
    """
    req = list(requested) if requested else [CPU_EP]
    try:
        return build(req), req, None
    except Exception as exc:  # noqa: BLE001 — any failure of the accelerated path
        wanted = provider_name(req[0]) if req else CPU_EP
        if wanted in _NOT_ACCELERATORS:
            raise
        error = f"{type(exc).__name__}: {exc}"[:400]
        log.error(
            "%s: could not start on %s — %s. Falling back to CPU; the adapter works "
            "but is not accelerated. Check the device is passed through to the "
            "container and the image flavour matches the host.",
            adapter, describe_providers(req[:1]), error,
        )
        return build([CPU_EP]), [CPU_EP], error

opennvr_adapter_sdk.describe_providers

describe_providers(entries) -> str

OpenVINOExecutionProvider(NPU), CPUExecutionProvider — for logs and the UI.

Source code in opennvr_adapter_sdk/providers.py
230
231
232
233
234
235
236
237
238
239
240
def describe_providers(entries) -> str:
    """``OpenVINOExecutionProvider(NPU), CPUExecutionProvider`` — for logs and the UI."""
    parts = []
    for e in entries or []:
        if isinstance(e, tuple):
            name, opts = e
            dev = next(iter((opts or {}).values()), None)
            parts.append(f"{name}({dev})" if dev else name)
        else:
            parts.append(str(e))
    return ", ".join(parts)

opennvr_adapter_sdk.effective_providers

effective_providers(
    session,
    requested=None,
    *,
    adapter: str = "adapter",
    fallback_error: str | None = None,
) -> dict[str, Any]

Compare the request with what session really runs on.

Returns the hardware-evaluation payload fragment::

{"onnxruntime_providers": [...available...],
 "requested_providers": "OpenVINOExecutionProvider(NPU), CPUExecutionProvider",
 "effective_providers": ["OpenVINOExecutionProvider", "CPUExecutionProvider"],
 "accelerator_in_use": True,
 "accelerator_requested": True}

and logs ONE warning when the first requested provider is not the one the session runs on — ORT's silent fallback, made loud.

Source code in opennvr_adapter_sdk/providers.py
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
def effective_providers(session, requested=None, *, adapter: str = "adapter",
                        fallback_error: str | None = None) -> dict[str, Any]:
    """Compare the request with what ``session`` really runs on.

    Returns the hardware-evaluation payload fragment::

        {"onnxruntime_providers": [...available...],
         "requested_providers": "OpenVINOExecutionProvider(NPU), CPUExecutionProvider",
         "effective_providers": ["OpenVINOExecutionProvider", "CPUExecutionProvider"],
         "accelerator_in_use": True,
         "accelerator_requested": True}

    and logs ONE warning when the first requested provider is not the one the
    session runs on — ORT's silent fallback, made loud.
    """
    try:
        effective = list(session.get_providers())
    except Exception:
        effective = []
    if getattr(session, "_opennvr_plugin_compiled", None) is False:
        # The plugin's device never came up and every node is on CPU, yet
        # the session still lists it (see plugin_session).
        effective = [p for p in effective if p not in PLUGIN_EPS]
    req = list(requested) if requested else []
    wanted = provider_name(req[0]) if req else None
    in_use = bool(effective) and effective[0] not in _NOT_ACCELERATORS
    if wanted and wanted not in _NOT_ACCELERATORS and (not effective or effective[0] != wanted):
        log.warning(
            "%s: ONNX Runtime could not use %s — running on %s. Check the accelerator's "
            "user-space driver is in the image (the matching image flavour) and its "
            "device is passed through to the container.",
            adapter, describe_providers(req[:1]), ", ".join(effective) or "nothing",
        )
    elif wanted:
        log.info("%s: ONNX Runtime running on %s", adapter, describe_providers(req[:1]))
    report = {
        "onnxruntime_providers": available_providers(),
        "requested_providers": describe_providers(req),
        "effective_providers": effective,
        "accelerator_in_use": in_use,
        "accelerator_requested": bool(wanted) and wanted not in _NOT_ACCELERATORS,
    }
    if fallback_error:
        # build_with_fallback() rebuilt on CPU: the request is what the
        # operator asked for, the session is CPU, and here is why.
        report["accelerator_requested"] = True
        report["accelerator_fallback_error"] = fallback_error
    return report

opennvr_adapter_sdk.plugin_device_missing

plugin_device_missing(
    name: str, entry: ProviderEntry
) -> str | None

Why entry cannot run on its accelerator from THIS container, or None.

Measured on a Ventuno Q, 2026-11-01: a container recreated without the Qualcomm overlay — no /dev/fastrpc-cdsp — still got an HTP device from get_ep_devices(), built the session, listed QNN as effective, reported accelerator_in_use: true on /hardware/evaluation, and ran every node on CPU: 468 ms an inference against 15 on the HTP. The runtime never says. The device node does: an HTP backend without it is CPU, and this says so before the session is built.

Source code in opennvr_adapter_sdk/providers.py
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
def plugin_device_missing(name: str, entry: ProviderEntry) -> str | None:
    """Why ``entry`` cannot run on its accelerator from THIS container, or None.

    Measured on a Ventuno Q, 2026-11-01: a container recreated without the
    Qualcomm overlay — no ``/dev/fastrpc-cdsp`` — still got an HTP device
    from ``get_ep_devices()``, built the session, listed QNN as effective,
    reported ``accelerator_in_use: true`` on ``/hardware/evaluation``, and
    ran every node on CPU: 468 ms an inference against 15 on the HTP. The
    runtime never says. The device node does: an HTP backend without it is
    CPU, and this says so before the session is built.
    """
    if name != QNN_EP:
        return None
    opts = entry[1] if isinstance(entry, tuple) and isinstance(entry[1], dict) else {}
    backend = str(opts.get("backend_type", "htp")).strip().lower()
    if backend != "htp":
        return None   # QNN's own CPU (or GPU) backend needs no DSP
    dev = QNN_HTP_DEVICE
    if not os.path.exists(dev):
        return (f"{name}(htp) requested but {dev} is not in this container — the "
                "Qualcomm overlay (docker-compose.accel-qualcomm.yml, applied by "
                "./start.sh up) lends it; running on CPU")
    if not os.access(dev, os.R_OK | os.W_OK):
        return (f"{name}(htp) requested but {dev} is not accessible from this "
                "container — check FASTRPC_GID / DMAHEAP_GID in .env match the host's "
                "fastrpc and dmaheap groups; running on CPU")
    return None

opennvr_adapter_sdk.resolve_providers

resolve_providers(
    requested, available
) -> list[ProviderEntry]

requested ∩ available in the requested order, CPU always last.

requested may be a comma string, a list, or None ("let ORT pick from what it has"). A requested provider this build does not have is skipped with a warning rather than failing the adapter.

Source code in opennvr_adapter_sdk/providers.py
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
def resolve_providers(requested, available) -> list[ProviderEntry]:
    """``requested ∩ available`` in the requested order, CPU always last.

    ``requested`` may be a comma string, a list, or ``None`` ("let ORT pick
    from what it has"). A requested provider this build does not have is
    skipped with a warning rather than failing the adapter.
    """
    available = list(available) if available else []
    specs = parse_provider_specs(requested)
    if not specs:
        provs: list[ProviderEntry] = list(available) if available else [CPU_EP]
    else:
        provs = []
        for name, device in specs:
            if available and name not in available:
                log.warning("ORT provider %s not available in this build; skipping", name)
                continue
            provs.append(provider_entry(name, device))
    if CPU_EP not in [provider_name(p) for p in provs]:
        provs.append(CPU_EP)
    return provs

opennvr_adapter_sdk.session_providers

session_providers(requested=None) -> list[ProviderEntry]

What to pass as providers= for an InferenceSession: the env setting (or requested) resolved against this build's providers. A plugin provider in the request is registered here (and the constructor shim installed), so the list works in a library's providers= too.

Source code in opennvr_adapter_sdk/providers.py
645
646
647
648
649
650
651
652
def session_providers(requested=None) -> list[ProviderEntry]:
    """What to pass as ``providers=`` for an ``InferenceSession``: the env
    setting (or ``requested``) resolved against this build's providers. A
    plugin provider in the request is registered here (and the constructor
    shim installed), so the list works in a library's ``providers=`` too."""
    req = requested if requested is not None else requested_providers()
    register_plugin_providers(req)
    return resolve_providers(req, available_providers())

opennvr_adapter_sdk.static_shapes

static_shapes(entries, shapes) -> list[ProviderEntry]

Pin a dynamic-shape graph for OpenVINO: shapes maps each input name to its full shape, e.g. {"images": [1, 3, 448, 448]}.

Returns a new provider list in which every OpenVINO entry carries reshape_input (the plugin reshapes the graph once, before compiling) and non-OpenVINO entries are untouched. The session then accepts ONLY those shapes — the adapter must size its frames to match. Needed for the NPU, which has no dynamic-shape support, and the safe choice on an iGPU.

Source code in opennvr_adapter_sdk/providers.py
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def static_shapes(entries, shapes) -> list[ProviderEntry]:
    """Pin a dynamic-shape graph for OpenVINO: ``shapes`` maps each input name
    to its full shape, e.g. ``{"images": [1, 3, 448, 448]}``.

    Returns a new provider list in which every OpenVINO entry carries
    ``reshape_input`` (the plugin reshapes the graph once, before compiling)
    and non-OpenVINO entries are untouched. The session then accepts ONLY
    those shapes — the adapter must size its frames to match. Needed for
    the NPU, which has no dynamic-shape support, and the safe choice on an
    iGPU.
    """
    spec = ",".join(
        f"{name}[{','.join(str(int(d)) for d in dims)}]" for name, dims in dict(shapes).items()
    )
    out: list[ProviderEntry] = []
    for entry in entries or []:
        name = provider_name(entry)
        if name == QNN_EP:
            # QNN has no reshape option: plugin_session writes a fixed-shape
            # copy of the model before compiling (FIXED_SHAPES_KEY).
            options = dict(entry[1]) if isinstance(entry, tuple) else {}
            options[FIXED_SHAPES_KEY] = spec
            out.append((QNN_EP, options))
            continue
        if name != OPENVINO_EP:
            out.append(entry)
            continue
        options = dict(entry[1]) if isinstance(entry, tuple) else {}
        options.pop("disable_dynamic_shapes", None)
        options["reshape_input"] = spec
        out.append((OPENVINO_EP, options))
    return out

opennvr_adapter_sdk.wants_static_shapes

wants_static_shapes(entries) -> bool

True when the first provider is an accelerator that compiles the graph for fixed shapes — an OpenVINO device other than CPU, or the QNN HTP — so a dynamic-shape graph should be pinned with :func:static_shapes before the session is built.

Source code in opennvr_adapter_sdk/providers.py
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def wants_static_shapes(entries) -> bool:
    """True when the first provider is an accelerator that compiles the graph
    for fixed shapes — an OpenVINO device other than ``CPU``, or the QNN HTP
    — so a dynamic-shape graph should be pinned with :func:`static_shapes`
    before the session is built."""
    for entry in entries or []:
        name = provider_name(entry)
        opts = entry[1] if isinstance(entry, tuple) and isinstance(entry[1], dict) else {}
        if name == OPENVINO_EP:
            device = opts.get("device_type", "")
            return bool(device) and device.upper() != "CPU"
        if name == QNN_EP:
            return opts.get("backend_type", "htp").lower() != "cpu"
        return False
    return False