Published specs

The documents an adapter publishes about itself, generated from the contract types it actually returns.

opennvr_adapter_sdk.adapter_asyncapi

adapter_asyncapi(
    name: str,
    version: str,
    *,
    supports_stream: bool = True,
    tasks: tuple[str, ...] = (),
    license_name: str = "",
) -> dict[str, Any]

The AsyncAPI 3.0 document for /infer/stream.

OpenAPI stops at the door of a WebSocket, and streaming is where a real-time adapter earns its keep: one session, one warm model, and backpressure that a request/response spec cannot express. Every message here is a contract type from :mod:~.contract, so this is generated rather than maintained.

Source code in opennvr_adapter_sdk/openapi.py

def adapter_asyncapi(
    name: str,
    version: str,
    *,
    supports_stream: bool = True,
    tasks: tuple[str, ...] = (),
    license_name: str = "",
) -> dict[str, Any]:
    """The **AsyncAPI 3.0** document for ``/infer/stream``.

    OpenAPI stops at the door of a WebSocket, and streaming is where a
    real-time adapter earns its keep: one session, one warm model, and
    backpressure that a request/response spec cannot express. Every
    message here is a contract type from :mod:`~.contract`, so this is
    generated rather than maintained."""
    messages = {
        key: _message(key, model)
        for key, model in {**_CLIENT_MESSAGES, **_ADAPTER_MESSAGES}.items()
    }
    schemas: dict[str, Any] = {}
    for model in {**_CLIENT_MESSAGES, **_ADAPTER_MESSAGES}.values():
        body, defs = _schema(model)
        schemas[model.__name__] = body
        # Nested models (FrameTransport, StreamCloseCode, …) are emitted
        # by Pydantic under ``$defs``. Dropping them left the refs that
        # point at them dangling, so the document did not resolve.
        for ref_name, ref_schema in defs.items():
            schemas.setdefault(ref_name, ref_schema)

    doc: dict[str, Any] = {
        "asyncapi": "3.0.0",
        "info": {
            "title": f"{name} — streaming inference",
            "version": version,
            "description": (
                f"The `/infer/stream` WebSocket protocol for **{name}** (AI "
                f"Adapter Contract v{CONTRACT_VERSION} §6).\n\n"
                "A session opens with a `handshake` naming the camera, the "
                "task and the frame transport; the adapter answers "
                "`handshake_ack`. The client then sends `frame` (or "
                "`frame_ref` for shared memory) and receives `result`. The "
                "adapter may `pause` and `resume` the client as "
                "backpressure, and either side may `close`.\n\n"
                "One session means one warm model and one correlation id for "
                "the whole episode, which is what makes a sequence of frames "
                "traceable as one event rather than N unrelated inferences."
            ),
            **({"license": {"name": license_name}} if license_name else {}),
            "x-opennvr-contract-version": CONTRACT_VERSION,
            "x-opennvr-tasks": list(tasks),
        },
        "servers": {
            "adapter": {
                "host": "{host}:{port}",
                "pathname": "/infer/stream",
                "protocol": "ws",
                "description": "The adapter's own port on the internal network.",
                "variables": {
                    "host": {"default": name},
                    "port": {"default": "9000"},
                },
            }
        },
        "channels": {},
        "operations": {},
        "components": {"messages": messages, "schemas": schemas,
                       "securitySchemes": {"bearerAuth": {
                           "type": "http", "scheme": "bearer",
                           "description": "Sent as an Authorization header on "
                                          "the upgrade request."}}},
    }

    if not supports_stream:
        doc["info"]["description"] = (
            f"**{name}** does not support streaming inference — "
            f"`/infer/stream` answers 501 and callers should use "
            f"`POST /infer`. This document describes the protocol the "
            f"contract defines, for reference only."
        )
        return doc

    doc["channels"] = {
        "stream": {
            "address": "/infer/stream",
            "title": "Streaming inference session",
            "description": "One WebSocket connection = one camera's session.",
            "messages": {key: {"$ref": f"#/components/messages/{key}"}
                         for key in messages},
        }
    }
    doc["operations"] = {
        "send": {
            "action": "send",
            "channel": {"$ref": "#/channels/stream"},
            "title": "What the adapter sends",
            "summary": "Handshake acknowledgement, results, and backpressure.",
            "messages": [{"$ref": f"#/components/messages/{key}"}
                         for key in _ADAPTER_MESSAGES],
        },
        "receive": {
            "action": "receive",
            "channel": {"$ref": "#/channels/stream"},
            "title": "What the adapter receives",
            "summary": "The session handshake, frames, and acknowledgements.",
            "messages": [{"$ref": f"#/components/messages/{key}"}
                         for key in _CLIENT_MESSAGES],
        },
    }
    return doc