opennvr-adapter-sdk 1.0.0__tar.gz

opennvr_adapter_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `opennvr-adapter-sdk` are documented here.
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+the SDK uses semantic versioning aligned with the AI Adapter Contract major version (SDK v1.x targets contract v1).
+
+## [1.0.0] — 2026-05
+
+First public release. Extracted from the three reference adapters
+(Piper TTS, YOLOv8 object detection, Whisper ASR) shipped in
+`open-nvr/ai-adapter`. All §3 endpoints, §5 result conventions,
+§6 WebSocket streaming protocol, §7 failure envelope, and §11.3
+fingerprint drift detection are exercised by the three references.
+
+### Added
+
+- `AdapterService` ABC with four required abstract methods
+  (`load`, `is_ready`, `fingerprint`, `model_info`,
+  `hardware_evaluation`, `infer`) plus optional `handle_stream`
+  for streaming adapters.
+- `AdapterApp` builder that wraps an `AdapterService` in a
+  FastAPI app implementing all six mandatory contract endpoints
+  (`/health`, `/capabilities`, `/hardware/evaluation`,
+  `/metrics`, `/infer`, `/infer/stream`), plus auth +
+  correlation_id middleware, Prometheus metrics, lifespan
+  startup, and body parsing for `BodyShape.{TEXT, IMAGE, AUDIO, GENERIC}`.
+- `ServiceError` exception that translates to the §7 failure
+  envelope.
+- `BODY_BYTES_KEY` constant for the binary body payload key;
+  caller-supplied params that shadow it are rejected with
+  `malformed_input` rather than being silently overwritten.
+- `opennvr_adapter_sdk.contract` submodule with every Pydantic
+  wire type the contract defines; commonly-used types are
+  re-exported at the package root.
+- Oversize bodies (`max_body_bytes`) return HTTP 413, not 400.
+- Streaming adapters automatically get `inc/dec_stream_connection`
+  metrics; per-frame metrics via `self.metrics`.
+- `service_factory` constructor parameter for lazy service
+  construction at lifespan startup — useful for test fixtures
+  that monkey-patch `__init__`.
+
+### Notes
+
+- Apache-2.0 licensed so third parties can write closed-source
+  production adapters. The reference adapters and the ai-adapter
+  app are AGPL-3.0; the SDK boundary stays permissive.
+- Pinned to FastAPI ≥0.115 / Pydantic ≥2.7 / Python ≥3.10. Loosen
+  the upper bounds in your fork if you need wider compatibility.
+
+[1.0.0]: https://github.com/open-nvr/ai-adapter/releases/tag/sdk-v1.0.0

opennvr_adapter_sdk-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for, or grant indemnities for, additional or similar liability
+      obligations and/or rights consistent with this License. However,
+      in accepting such obligations, You may act only on Your own behalf
+      and on Your sole responsibility, not on behalf of any other
+      Contributor, and only if You agree to indemnify, defend, and hold
+      each Contributor harmless for any liability incurred by, or claims
+      asserted against, such Contributor by reason of your accepting any
+      such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 OpenNVR
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opennvr_adapter_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,30 @@
+# sdist-only inclusions. The wheel picks these up via
+# [tool.setuptools.package-data] in pyproject.toml; setuptools' default
+# sdist heuristics skip non-Python files at the package root unless we
+# spell them out here.
+#
+# Why every file is listed explicitly:
+#   - README.md is referenced via ``readme = "README.md"`` in
+#     pyproject.toml and setuptools auto-includes it. Listing it again
+#     here makes sdist contents independent of that backend behavior.
+#   - LICENSE is NOT auto-included by ``license = { text = "Apache-2.0" }``
+#     in modern setuptools — that key only sets metadata, it doesn't
+#     copy a file. (PEP 639 ``license-files = ["LICENSE"]`` would, but
+#     we're not on that yet.) So LICENSE ships ONLY because it's
+#     listed here (sdist) and in package-data (wheel).
+#   - CHANGELOG.md and RELEASING.md have no auto-include path; listed
+#     here is the only way they make it into the sdist.
+#
+# If you remove any of these lines, ``twine check`` will still pass
+# but ``tar tzf dist/*.tar.gz`` will be silently missing files.
+include LICENSE
+include README.md
+include CHANGELOG.md
+include RELEASING.md
+
+# Belt-and-suspenders: keep build leftovers and old sdist extractions
+# out of the next sdist build.
+prune dist
+prune build
+prune *.egg-info
+prune opennvr_adapter_sdk-*

opennvr_adapter_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: opennvr-adapter-sdk
+Version: 1.0.0
+Summary: Boilerplate-free SDK for writing AI Adapter Contract v1 services for OpenNVR.
+Author-email: OpenNVR <contact@open-nvr.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/open-nvr/ai-adapter
+Project-URL: Documentation, https://github.com/open-nvr/ai-adapter/tree/main/opennvr_adapter_sdk
+Project-URL: Repository, https://github.com/open-nvr/ai-adapter
+Project-URL: Issues, https://github.com/open-nvr/ai-adapter/issues
+Project-URL: Changelog, https://github.com/open-nvr/ai-adapter/blob/main/opennvr_adapter_sdk/CHANGELOG.md
+Keywords: ai,inference,adapter,sdk,fastapi,websocket,computer-vision,nvr,object-detection,asr,tts
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: python-multipart>=0.0.18
+Provides-Extra: serve
+Requires-Dist: uvicorn[standard]<1.0,>=0.30; extra == "serve"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# opennvr-adapter-sdk
+
+The boilerplate-free way to write an [AI Adapter Contract v1](https://github.com/open-nvr/open-nvr/blob/main/docs/AI_ADAPTER_CONTRACT.md) service.
+
+A minimal adapter is around thirty lines of FastAPI. The SDK gives you `AdapterService` — the ABC every adapter implements with four abstract methods — and `AdapterApp`, the builder that wraps your service in a FastAPI app with the six mandatory endpoints, auth, correlation-ID propagation, Prometheus metrics, and multipart plus JSON body parsing. `ServiceError` is the typed failure envelope from §7 of the contract. Every contract Pydantic type is re-exported from the package root, so adapter authors get one import line.
+
+## Install
+
+```bash
+uv add opennvr-adapter-sdk
+# with the uvicorn server bundled too:
+uv add 'opennvr-adapter-sdk[serve]'
+```
+
+If you're not on [uv](https://docs.astral.sh/uv/) yet, `pip install opennvr-adapter-sdk` works the same — the package is a single wheel with FastAPI, Pydantic, and python-multipart as its only runtime dependencies. We recommend `uv` because adapter projects tend to grow heavy ML deps fast, and `uv sync` keeps resolve time and the lockfile manageable as they do.
+
+## The minimum viable adapter
+
+```python
+# my_adapter/main.py
+from datetime import datetime, timezone
+
+from opennvr_adapter_sdk import (
+    AdapterApp, AdapterService, BodyShape, ErrorCategory,
+    HardwareEvaluationResponse, HardwareVerdict, InferResponse,
+    ModelInfo, ServiceError,
+)
+
+class MyService(AdapterService):
+    def __init__(self):
+        self._ready = False
+
+    def load(self):
+        # Heavy lifting goes here.
+        self._ready = True
+
+    def is_ready(self): return self._ready
+
+    def fingerprint(self):
+        return "sha256:..."
+
+    def model_info(self):
+        return ModelInfo(
+            name="my-model", version="1.0",
+            framework="numpy", modalities_in=["text"],
+            modalities_out=["text"], fingerprint=self.fingerprint(),
+        )
+
+    def hardware_evaluation(self):
+        return HardwareEvaluationResponse(
+            verdict=HardwareVerdict.OK, reasoning="ready",
+            checked_at=datetime.now(timezone.utc), details={},
+        )
+
+    def infer(self, payload):
+        if "text" not in payload:
+            raise ServiceError(
+                ErrorCategory.TRANSPORT_ERROR, code="malformed_input",
+                message="'text' required", transient=False, http_status=400,
+            )
+        return InferResponse(
+            model_name="my-model", model_version="1.0",
+            inference_ms=1, result={"echoed": payload["text"]},
+        )
+
+app = AdapterApp(
+    service=MyService(),
+    name="my-adapter", version="1.0.0",
+    vendor="me", license="MIT",
+    tasks_advertised=["echo"],
+    body_shape=BodyShape.TEXT,
+).fastapi_app
+```
+
+Run it:
+
+```bash
+OPENNVR_ADAPTER_TOKEN=dev-token \
+  uvicorn my_adapter.main:app --host 0.0.0.0 --port 9001
+```
+
+Verify conformance:
+
+```bash
+python -m conformance http://localhost:9001 --token dev-token
+```
+
+That's a complete contract-compliant adapter. The SDK handles `/health`, `/capabilities`, `/hardware/evaluation`, `/metrics`, `/infer`, `/infer/stream` (HTTP 501 refusal), auth, correlation_id, multipart + JSON body parsing, Prometheus metrics, lifespan startup. You write only the model wrapper.
+
+## Body shapes
+
+| Shape | Wire | Use for |
+|---|---|---|
+| `BodyShape.TEXT` | JSON + multipart (text-only fields) | TTS, LLM chat, any text-only adapter |
+| `BodyShape.IMAGE` | multipart `frame` file + JSON `frame_b64` | Vision detection, classification, OCR |
+| `BodyShape.AUDIO` | multipart `audio` file + JSON `audio_b64` | ASR, audio classification, TTS post-process |
+| `BodyShape.GENERIC` | multipart `data` file + JSON `data_b64` | Anything else with binary input |
+
+For non-TEXT shapes, the SDK puts the binary content at `payload[BODY_BYTES_KEY]` (bytes) and merges any `params` JSON into the dict. `BODY_BYTES_KEY` is re-exported from the SDK root — import it rather than hard-coding the literal so future renames don't silently break adapters. Caller-supplied params that shadow this key are rejected with `malformed_input` so collisions surface at the wire, not as silently-overwritten values.
+
+## Streaming adapters
+
+Add `supports_stream=True` to `AdapterApp(...)` and override `AdapterService.handle_stream(websocket)`:
+
+```python
+class MyDetector(AdapterService):
+    async def handle_stream(self, websocket):
+        await websocket.accept()
+        # ... §6 protocol ...
+
+app = AdapterApp(
+    service=MyDetector(),
+    ...
+    supports_stream=True,
+    stream_max_concurrent=16,
+    stream_supports_shared_memory=False,
+).fastapi_app
+```
+
+The SDK handles auth on the WebSocket upgrade (§6.5 close code 4001 on auth failure) and delegates to your handler. The §6 protocol itself — handshake → frame_meta + binary → result_message — is the adapter's responsibility (YOLOv8 has the reference implementation under `adapters/yolov8/`).
+
+## Constructor reference
+
+```python
+AdapterApp(
+    # Service — exactly one required:
+    service: AdapterService | None,           # eager construction
+    service_factory: Callable[[], AdapterService] | None,  # lazy (lifespan startup)
+
+    # Adapter identity (required):
+    name: str, version: str,
+    vendor: str, license: str,
+    tasks_advertised: Sequence[str],
+
+    # Body shape + size cap:
+    body_shape: BodyShape = BodyShape.TEXT,
+    max_body_bytes: int = 32 * 1024 * 1024,
+
+    # Capabilities metadata (optional, with defaults):
+    permissions: Permissions = Permissions(),
+    scheduling: Scheduling = Scheduling(),  # default max_inflight=1
+    cost: Cost = Cost(),
+    model_card_url: str | None = None,
+    supported_contract_versions: Sequence[str] = ("1",),
+
+    # Streaming (default off):
+    supports_stream: bool = False,
+    stream_max_concurrent: int = 0,
+    stream_supports_shared_memory: bool = False,
+
+    # Tuning:
+    latency_buckets_seconds: tuple[float, ...] = (...),  # Prometheus buckets
+    cors_origins: Sequence[str] = ("*",),
+)
+```
+
+## Real-world examples
+
+`opennvr-adapter-sdk` is the production runtime for the eight adapters shipped in this repo: `adapters/yolov8/` for object detection (`BodyShape.IMAGE` with WebSocket streaming); `adapters/piper/` for text-to-speech (`BodyShape.TEXT` with a custom `/voices` route and inline-audio response); `adapters/whisper/` for speech-to-text (`BodyShape.AUDIO`, multipart decode); `adapters/fast_plate_ocr/` for license-plate text recognition on a pre-cropped plate image (`BodyShape.IMAGE`, designed to chain downstream of YOLOv8); `adapters/insightface/` for face detection plus recognition with a REST face DB; `adapters/blip/` for scene captioning, used by the OpenNVR camera-agent; `adapters/vlm/` for open-vocabulary detection (OWL-ViT v2, detects free-text queries like "red truck"); and `adapters/bytetrack/` for stateful multi-object tracking as a post-processor over an upstream detector's results. Their `main.py` files are non-trivial reference implementations worth reading before authoring your own.
+
+## Versioning
+
+SDK ships with the same major version as the contract. SDK v1.x targets contract v1; a future contract v2 ships SDK v2.x. `AdapterApp.supported_contract_versions` defaults to `["1"]` — bump when you implement multi-version support.
+
+## Why this isn't a "framework"
+
+`AdapterService` is an ABC, not a metaclass. `AdapterApp` is a builder, not a base class. The SDK lives between you and FastAPI — your service code never imports FastAPI directly, but you can still drop down to `app.add_route(...)` for adapter-specific endpoints (see Piper's `/voices` route).
+
+The contract is the source of truth. The SDK is a convenience layer on top of it. If the SDK gets in your way, write the service hand-rolled the way the early reference adapters did before the SDK was extracted — the contract is implementable without it, just more boilerplate.

opennvr_adapter_sdk-1.0.0/README.md

@@ -0,0 +1,169 @@
+# opennvr-adapter-sdk
+
+The boilerplate-free way to write an [AI Adapter Contract v1](https://github.com/open-nvr/open-nvr/blob/main/docs/AI_ADAPTER_CONTRACT.md) service.
+
+A minimal adapter is around thirty lines of FastAPI. The SDK gives you `AdapterService` — the ABC every adapter implements with four abstract methods — and `AdapterApp`, the builder that wraps your service in a FastAPI app with the six mandatory endpoints, auth, correlation-ID propagation, Prometheus metrics, and multipart plus JSON body parsing. `ServiceError` is the typed failure envelope from §7 of the contract. Every contract Pydantic type is re-exported from the package root, so adapter authors get one import line.
+
+## Install
+
+```bash
+uv add opennvr-adapter-sdk
+# with the uvicorn server bundled too:
+uv add 'opennvr-adapter-sdk[serve]'
+```
+
+If you're not on [uv](https://docs.astral.sh/uv/) yet, `pip install opennvr-adapter-sdk` works the same — the package is a single wheel with FastAPI, Pydantic, and python-multipart as its only runtime dependencies. We recommend `uv` because adapter projects tend to grow heavy ML deps fast, and `uv sync` keeps resolve time and the lockfile manageable as they do.
+
+## The minimum viable adapter
+
+```python
+# my_adapter/main.py
+from datetime import datetime, timezone
+
+from opennvr_adapter_sdk import (
+    AdapterApp, AdapterService, BodyShape, ErrorCategory,
+    HardwareEvaluationResponse, HardwareVerdict, InferResponse,
+    ModelInfo, ServiceError,
+)
+
+class MyService(AdapterService):
+    def __init__(self):
+        self._ready = False
+
+    def load(self):
+        # Heavy lifting goes here.
+        self._ready = True
+
+    def is_ready(self): return self._ready
+
+    def fingerprint(self):
+        return "sha256:..."
+
+    def model_info(self):
+        return ModelInfo(
+            name="my-model", version="1.0",
+            framework="numpy", modalities_in=["text"],
+            modalities_out=["text"], fingerprint=self.fingerprint(),
+        )
+
+    def hardware_evaluation(self):
+        return HardwareEvaluationResponse(
+            verdict=HardwareVerdict.OK, reasoning="ready",
+            checked_at=datetime.now(timezone.utc), details={},
+        )
+
+    def infer(self, payload):
+        if "text" not in payload:
+            raise ServiceError(
+                ErrorCategory.TRANSPORT_ERROR, code="malformed_input",
+                message="'text' required", transient=False, http_status=400,
+            )
+        return InferResponse(
+            model_name="my-model", model_version="1.0",
+            inference_ms=1, result={"echoed": payload["text"]},
+        )
+
+app = AdapterApp(
+    service=MyService(),
+    name="my-adapter", version="1.0.0",
+    vendor="me", license="MIT",
+    tasks_advertised=["echo"],
+    body_shape=BodyShape.TEXT,
+).fastapi_app
+```
+
+Run it:
+
+```bash
+OPENNVR_ADAPTER_TOKEN=dev-token \
+  uvicorn my_adapter.main:app --host 0.0.0.0 --port 9001
+```
+
+Verify conformance:
+
+```bash
+python -m conformance http://localhost:9001 --token dev-token
+```
+
+That's a complete contract-compliant adapter. The SDK handles `/health`, `/capabilities`, `/hardware/evaluation`, `/metrics`, `/infer`, `/infer/stream` (HTTP 501 refusal), auth, correlation_id, multipart + JSON body parsing, Prometheus metrics, lifespan startup. You write only the model wrapper.
+
+## Body shapes
+
+| Shape | Wire | Use for |
+|---|---|---|
+| `BodyShape.TEXT` | JSON + multipart (text-only fields) | TTS, LLM chat, any text-only adapter |
+| `BodyShape.IMAGE` | multipart `frame` file + JSON `frame_b64` | Vision detection, classification, OCR |
+| `BodyShape.AUDIO` | multipart `audio` file + JSON `audio_b64` | ASR, audio classification, TTS post-process |
+| `BodyShape.GENERIC` | multipart `data` file + JSON `data_b64` | Anything else with binary input |
+
+For non-TEXT shapes, the SDK puts the binary content at `payload[BODY_BYTES_KEY]` (bytes) and merges any `params` JSON into the dict. `BODY_BYTES_KEY` is re-exported from the SDK root — import it rather than hard-coding the literal so future renames don't silently break adapters. Caller-supplied params that shadow this key are rejected with `malformed_input` so collisions surface at the wire, not as silently-overwritten values.
+
+## Streaming adapters
+
+Add `supports_stream=True` to `AdapterApp(...)` and override `AdapterService.handle_stream(websocket)`:
+
+```python
+class MyDetector(AdapterService):
+    async def handle_stream(self, websocket):
+        await websocket.accept()
+        # ... §6 protocol ...
+
+app = AdapterApp(
+    service=MyDetector(),
+    ...
+    supports_stream=True,
+    stream_max_concurrent=16,
+    stream_supports_shared_memory=False,
+).fastapi_app
+```
+
+The SDK handles auth on the WebSocket upgrade (§6.5 close code 4001 on auth failure) and delegates to your handler. The §6 protocol itself — handshake → frame_meta + binary → result_message — is the adapter's responsibility (YOLOv8 has the reference implementation under `adapters/yolov8/`).
+
+## Constructor reference
+
+```python
+AdapterApp(
+    # Service — exactly one required:
+    service: AdapterService | None,           # eager construction
+    service_factory: Callable[[], AdapterService] | None,  # lazy (lifespan startup)
+
+    # Adapter identity (required):
+    name: str, version: str,
+    vendor: str, license: str,
+    tasks_advertised: Sequence[str],
+
+    # Body shape + size cap:
+    body_shape: BodyShape = BodyShape.TEXT,
+    max_body_bytes: int = 32 * 1024 * 1024,
+
+    # Capabilities metadata (optional, with defaults):
+    permissions: Permissions = Permissions(),
+    scheduling: Scheduling = Scheduling(),  # default max_inflight=1
+    cost: Cost = Cost(),
+    model_card_url: str | None = None,
+    supported_contract_versions: Sequence[str] = ("1",),
+
+    # Streaming (default off):
+    supports_stream: bool = False,
+    stream_max_concurrent: int = 0,
+    stream_supports_shared_memory: bool = False,
+
+    # Tuning:
+    latency_buckets_seconds: tuple[float, ...] = (...),  # Prometheus buckets
+    cors_origins: Sequence[str] = ("*",),
+)
+```
+
+## Real-world examples
+
+`opennvr-adapter-sdk` is the production runtime for the eight adapters shipped in this repo: `adapters/yolov8/` for object detection (`BodyShape.IMAGE` with WebSocket streaming); `adapters/piper/` for text-to-speech (`BodyShape.TEXT` with a custom `/voices` route and inline-audio response); `adapters/whisper/` for speech-to-text (`BodyShape.AUDIO`, multipart decode); `adapters/fast_plate_ocr/` for license-plate text recognition on a pre-cropped plate image (`BodyShape.IMAGE`, designed to chain downstream of YOLOv8); `adapters/insightface/` for face detection plus recognition with a REST face DB; `adapters/blip/` for scene captioning, used by the OpenNVR camera-agent; `adapters/vlm/` for open-vocabulary detection (OWL-ViT v2, detects free-text queries like "red truck"); and `adapters/bytetrack/` for stateful multi-object tracking as a post-processor over an upstream detector's results. Their `main.py` files are non-trivial reference implementations worth reading before authoring your own.
+
+## Versioning
+
+SDK ships with the same major version as the contract. SDK v1.x targets contract v1; a future contract v2 ships SDK v2.x. `AdapterApp.supported_contract_versions` defaults to `["1"]` — bump when you implement multi-version support.
+
+## Why this isn't a "framework"
+
+`AdapterService` is an ABC, not a metaclass. `AdapterApp` is a builder, not a base class. The SDK lives between you and FastAPI — your service code never imports FastAPI directly, but you can still drop down to `app.add_route(...)` for adapter-specific endpoints (see Piper's `/voices` route).
+
+The contract is the source of truth. The SDK is a convenience layer on top of it. If the SDK gets in your way, write the service hand-rolled the way the early reference adapters did before the SDK was extracted — the contract is implementable without it, just more boilerplate.