Update Raspberry Pi 5 reproduction package

Replace the earlier prototype package with the public runtime layout, converter and Python API; add the patched Ultralytics benchmark workflow, licensed validation dataset integration, fresh Marvik metadata, and verified reference results. The PyTorch checkpoint is no longer redistributed.

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 runtime/arm_yolo26n_pi5_model/bundle/native-runtime.so filter=lfs diff=lfs merge=lfs -text
+runtime/arm_yolo26n_pi5_model/lib/libarm-yolo26n.so.0.1.0 filter=lfs diff=lfs merge=lfs -text

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 reasonable and customary use in 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 choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other 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 [yyyy] [name of copyright owner]
+
+   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.

README.md

@@ -1,57 +1,84 @@
 ---
-license: apache-2.0
+license: other
 ---
 
 # YOLO26n Raspberry Pi 5 benchmark reproduction
 
-This package contains a compiled YOLO26n runtime, its Python API, the model
-exporter, and the integration needed to run it through the Ultralytics benchmark.
-It targets a Raspberry Pi 5 running 64-bit Raspberry Pi OS Trixie.
+This private package contains Arm's compiled YOLO26n runtime, its Python API,
+the model converter, and the integration needed to run the converted model
+through Ultralytics `benchmark()`. It targets a Raspberry Pi 5 running 64-bit
+Raspberry Pi OS Trixie.
 
-## Benchmark the supplied model
+The runtime, converter, Python API, and Ultralytics adapter correspond to
+commit `9056a527deaf2adc6123f43424d07672753a9524` of
+[Arm-Runtime-for-YOLO26-on-Raspberry-Pi-5](https://github.com/arm/Arm-Runtime-for-YOLO26-on-Raspberry-Pi-5).
 
-Internet access is required during setup and while the benchmark downloads the
-licensed validation dataset from Hugging Face. The dataset repository is
-currently private, so authenticate first with `hf auth login` or provide an
-`HF_TOKEN` that can read it.
+## Benchmark the supplied converted model
+
+Internet access is required during setup and while downloading the official
+YOLO26n checkpoint and the validation dataset. Authenticate with `hf auth
+login`, or provide an `HF_TOKEN` that can read the private dataset repository.
 
 ```sh
 python3 repro.py setup
 python3 repro.py benchmark
 ```
 
-`repro.py setup` installs upstream Ultralytics 8.4.108 and then applies the included
-patch that registers this runtime as an Ultralytics export format and inference
-backend. Therefore, this is the real Ultralytics `benchmark()` flow, but it is
-not an unmodified Ultralytics installation. The patch is required because
-upstream Ultralytics does not know how to load this runtime.
+`repro.py setup` installs Ultralytics 8.4.108 and applies the included patch
+that registers this runtime as an Ultralytics export format and inference
+backend. The benchmark therefore uses Ultralytics `benchmark()`, with an
+explicit integration patch because upstream Ultralytics does not natively know
+how to load this runtime.
 
-Before starting, `repro.py benchmark` checks for filesystem and memory conditions
+Before starting, the benchmark checks for filesystem and memory conditions
 that could distort performance, including RAM-backed model or dataset paths,
-low available memory, dirty/writeback pressure, page-cache refaults, reclaim
-scanning, and swap activity.
+low available memory, dirty or writeback pressure, page-cache refaults,
+reclaim scanning, and swap activity.
 
-The benchmark downloads `Arm/coco-128-by-sa` at the pinned revision
-`cb1edb8da4ff3cb54d40ecb12d3efecc116ff3de` into `data/coco-128-by-sa/` and
-uses `data-validation-all.yaml` to validate all 128 images. It does not include
-or redistribute those images in this package. Dataset attribution and the
-per-image CC BY 2.0 or CC BY-SA 2.0 license records remain in the downloaded
-`LICENSE_MANIFEST.csv`.
+The benchmark downloads `Arm/coco-128-by-sa` at revision
+`f8af0a317c0b54c3dbd38c70b9757dccb8b02460` and uses its `data.yaml` file.
+The dataset, its image licenses, and its per-image attribution records remain
+in the dataset repository and are not redistributed here.
 
-The result is written to `results/`. The supplied reference measurement is in
-`results/REFERENCE.md`.
+The benchmark result is written under `results/`. The supplied reference
+measurement is in `results/REFERENCE.md`.
 
-## Export your own model
+## Export your own compatible model
 
-Replace `model/yolo26n.pt` with your own compatible YOLO26n checkpoint, keeping
-that filename, then run:
+After setup, place a compatible YOLO26n checkpoint at `model/yolo26n.pt`, then
+run:
 
 ```sh
 python3 repro.py export
 python3 repro.py benchmark
 ```
 
-`repro.py export` creates a runnable model package under
-`build/arm_yolo26n_pi5_model/` using the supplied model-independent compiled
-runtime. When that directory exists, `repro.py benchmark` automatically benchmarks
-the newly exported model instead of the supplied prebuilt model.
+Export creates a runnable model directory under
+`build/arm_yolo26n_pi5_model/`. Benchmark automatically selects it and checks
+that the source checkpoint matches the converted model. No PyTorch checkpoint
+is distributed in this repository; the stock benchmark downloads and verifies
+the official checkpoint when needed.
+
+## About this version
+
+Original model: YOLO26n by Ultralytics.
+
+Optimization and conversion: Arm converted the original model into the fixed
+model artifact used by a purpose-built native runtime for Raspberry Pi 5. No
+retraining or fine-tuning was performed as part of this conversion.
+
+The runtime software is provided under Apache-2.0 as described in `LICENSE`.
+The original model and converted model artifact are subject to AGPL-3.0 unless
+you have a separate written license agreement with Ultralytics. Third-party
+runtime components retain the licenses included beside the compiled runtime.
+
+For information about the original model, including its development, training
+data, intended uses, and limitations, refer to the Ultralytics repository.
+Information supplied there by Ultralytics or other third parties has not been
+independently verified by Arm unless expressly stated otherwise.
+
+This package is a reference implementation for evaluation on Arm-based
+systems. It is not a production-ready or supported solution. It is provided
+as is, without representations or warranties. You are responsible for
+reviewing the applicable license terms and independently evaluating the model,
+its outputs, and its suitability for your intended use.

compiler/{minimal_runtime/compiler → converter}/checkpoint_decoder.py

@@ -13,7 +13,7 @@ from dataclasses import dataclass
 from pathlib import PurePosixPath
 from typing import Never
 
-from .compiler_io import RejectedInput
+from .converter_io import RejectedInput
 
 # Torch's ZIP format can use several pickle protocols for the same object
 # graph. Accept their passive container and memoization opcodes; find_class

compiler/{minimal_runtime/compiler → converter}/checkpoint_intake.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from .checkpoint_decoder import DecodedModule, decode_checkpoint_archive
-from .compiler_io import RejectedInput
+from .converter_io import RejectedInput
 from .model_contract import ValidatedYolo26n
 from .model_validation import validate_yolo26n_model
 

compiler/{minimal_runtime/compiler/compiler_io.py → converter/converter_io.py}

@@ -1,4 +1,4 @@
-"""Standard-library JSON, hashing, and atomic writes for compiler artifacts."""
+"""Standard-library JSON, hashing, and atomic writes for converted artifacts."""
 
 from __future__ import annotations
 
@@ -14,7 +14,7 @@ type JsonObject = dict[str, JsonValue]
 
 
 class RejectedInput(RuntimeError):
-    """A caller-controlled compiler input failed validation."""
+    """A caller-controlled converter input failed validation."""
 
 
 def sha256_bytes(data: bytes) -> str:

compiler/{minimal_runtime/compiler → converter}/export_yolo26n.py

@@ -14,7 +14,7 @@ from .checkpoint_intake import (
     decode_checkpoint,
     read_checkpoint,
 )
-from .compiler_io import JsonObject, RejectedInput, atomic_write, canonical_bytes, sha256_bytes
+from .converter_io import JsonObject, RejectedInput, atomic_write, canonical_bytes, sha256_bytes
 from .model_contract import ModelResolution
 from .model_format import pack_model
 from .weight_lowering import lower_yolo26n_weights
@@ -77,7 +77,6 @@ def export_model(
             lower_yolo26n_weights(model),
             model_resolution.resolution,
             model.class_count,
-            model.classification_width,
         )
     except ValueError as error:
         raise RejectedInput(f"could not prepare YOLO26n runtime weights: {error}") from error

compiler/{minimal_runtime/compiler → converter}/model_contract.py

@@ -1,13 +1,12 @@
-"""Typed contracts between YOLO26n checkpoint intake and compiler lowering."""
+"""Typed contracts between YOLO26n checkpoint intake and model conversion."""
 
 from __future__ import annotations
 
-import hashlib
 import math
 from dataclasses import dataclass
 from enum import Enum
 
-from .compiler_io import JsonObject
+from .converter_io import JsonObject
 
 # The native schedule accepts these square inputs and derives all intermediate
 # tensor extents from them. Values outside this closed set are rejected by both
@@ -162,11 +161,8 @@ def _runtime_weight_names() -> tuple[str, ...]:
 
 RUNTIME_WEIGHT_NAMES = _runtime_weight_names()
 # Stable slot numbers are assigned by semantic name. The fixed topology above
-# therefore determines both the slot count and schema identity.
+# therefore determines the slot count and order used by both exporter and runtime.
 RUNTIME_WEIGHT_SLOT_COUNT = len(RUNTIME_WEIGHT_NAMES)
-RUNTIME_WEIGHT_SCHEMA_SHA256 = hashlib.sha256(
-    b"\0".join(name.encode("utf-8") for name in RUNTIME_WEIGHT_NAMES)
-).hexdigest()
 
 _RUNTIME_TARGET = "linux-aarch64-raspberry-pi-5"
 _RUNTIME_THREAD_COUNT = 4

compiler/{minimal_runtime/compiler → converter}/model_format.py

@@ -2,19 +2,14 @@
 
 from __future__ import annotations
 
-import hashlib
 import struct
 from dataclasses import dataclass
 
-from .compiler_io import sha256_bytes
 from .model_contract import (
     BOX_COORDINATE_CHANNELS,
     RUNTIME_WEIGHT_NAMES,
-    RUNTIME_WEIGHT_SCHEMA_SHA256,
     RUNTIME_WEIGHT_SLOT_COUNT,
     SUPPORTED_RESOLUTIONS,
-    classification_width_for_classes,
-    detection_output_channels,
 )
 from .weight_contract import LoweredWeight
 
@@ -27,16 +22,18 @@ from .weight_contract import LoweredWeight
 _MAGIC = b"Y26MOD01"
 _VERSION = 1
 
-# XNNPACK uses 64-byte-aligned static buffers. A 128-byte header and 64-byte
-# directory records preserve that alignment while leaving zeroed reserved space
-# for corruption detection. The packed structs describe only the used prefix;
-# bytearray initialization supplies the required zero padding.
+# XNNPACK uses 64-byte-aligned static buffers. The header occupies one aligned
+# block. Directory position identifies the semantic slot, so each entry needs
+# only the payload offset and byte count.
 _ALIGNMENT = 64
-_HEADER_BYTES = 2 * _ALIGNMENT
-_ENTRY_BYTES = _ALIGNMENT
-_HEADER = struct.Struct("<8sIIIIIIQQQ32s")
-_ENTRY = struct.Struct("<IIQQ32sQ")
+_HEADER_BYTES = _ALIGNMENT
+_ENTRY_BYTES = 16
+_HEADER = struct.Struct("<8sIIIIQ")
+_ENTRY = struct.Struct("<QQ")
 _UINT32_MAX = (1 << 32) - 1
+_UINT64_MAX = (1 << 64) - 1
+_FP32_BYTES = 4
+_CLASSIFICATION_CHANNEL_FLOOR = 64
 
 
 @dataclass(frozen=True)
@@ -45,12 +42,8 @@ class RuntimeModelHeader:
 
     resolution: int
     class_count: int
-    classification_width: int
     slot_count: int
-    directory_offset: int
     payload_offset: int
-    file_bytes: int
-    slot_schema_sha256: str
 
 
 @dataclass(frozen=True)
@@ -97,66 +90,46 @@ def _round_up_to_alignment(value: int) -> int:
     return ((value + _ALIGNMENT - 1) // _ALIGNMENT) * _ALIGNMENT
 
 
-def _slot_schema_sha256(names: tuple[str, ...]) -> str:
-    """Identify the ordered semantic names that define runtime slot numbers."""
-    if not names or any(not name or "\0" in name for name in names):
-        raise ValueError("invalid model weight names")
-    payload = b"\0".join(name.encode("utf-8") for name in names)
-    return hashlib.sha256(payload).hexdigest()
+def _class_dependent_weight_bytes_fit(class_count: int) -> bool:
+    """Return whether the target runtime can size its largest learned tensor."""
+    width = max(_CLASSIFICATION_CHANNEL_FLOOR, class_count)
+    return (
+        0 < class_count <= _UINT32_MAX - BOX_COORDINATE_CHANNELS
+        and class_count <= _UINT64_MAX // _FP32_BYTES // width
+    )
 
 
 def read_runtime_model_header(payload: bytes) -> RuntimeModelHeader:
     """Read and validate the fixed header of an exported runtime ``model.bin``."""
     if len(payload) < _HEADER_BYTES:
-        raise ValueError("model file is smaller than its required 128-byte header")
+        raise ValueError("model file is smaller than its required 64-byte header")
     (
         magic,
         version,
-        header_bytes,
         resolution,
         class_count,
         slot_count,
-        classification_width,
-        directory_offset,
         payload_offset,
-        file_bytes,
-        slot_schema,
     ) = _HEADER.unpack_from(payload)
     maximum_directory_entries = (len(payload) - _HEADER_BYTES) // _ENTRY_BYTES
     expected_payload_offset = _round_up_to_alignment(_HEADER_BYTES + _ENTRY_BYTES * slot_count)
     if (
         magic != _MAGIC
         or version != _VERSION
-        or header_bytes != _HEADER_BYTES
         or resolution not in SUPPORTED_RESOLUTIONS
-        or class_count == 0
-        or class_count > _UINT32_MAX - BOX_COORDINATE_CHANNELS
+        or not _class_dependent_weight_bytes_fit(class_count)
         or slot_count == 0
         or slot_count != RUNTIME_WEIGHT_SLOT_COUNT
         or slot_count > maximum_directory_entries
-        or directory_offset != _HEADER_BYTES
         or payload_offset != expected_payload_offset
-        or file_bytes != len(payload)
-        or payload[88:_HEADER_BYTES] != bytes(_HEADER_BYTES - 88)
+        or payload[_HEADER.size : _HEADER_BYTES] != bytes(_HEADER_BYTES - _HEADER.size)
     ):
         raise ValueError("model header does not match the fixed runtime format")
-    if classification_width != classification_width_for_classes(class_count):
-        raise ValueError("model header has incompatible class-head dimensions")
-    schema = slot_schema.hex()
-    if schema != RUNTIME_WEIGHT_SCHEMA_SHA256:
-        raise ValueError(
-            "model header weight schema does not match the fixed runtime: "
-            f"expected {RUNTIME_WEIGHT_SCHEMA_SHA256}, received {schema}"
-        )
     return RuntimeModelHeader(
         resolution=resolution,
         class_count=class_count,
-        classification_width=classification_width,
         slot_count=slot_count,
-        directory_offset=directory_offset,
         payload_offset=payload_offset,
-        file_bytes=file_bytes,
-        slot_schema_sha256=schema,
     )
 
 
@@ -164,7 +137,6 @@ def _pack_model_weights(
     weights: tuple[_ModelWeight, ...],
     resolution: int,
     class_count: int,
-    classification_width: int,
 ) -> bytes:
     """Pack validated slot records into the binary model container."""
     if len(weights) != RUNTIME_WEIGHT_SLOT_COUNT or [weight.slot for weight in weights] != list(
@@ -176,14 +148,9 @@ def _pack_model_weights(
     if (
         resolution not in SUPPORTED_RESOLUTIONS
         or type(class_count) is not int
-        or class_count <= 0
-        or detection_output_channels(class_count) > _UINT32_MAX
-        or type(classification_width) is not int
-        or classification_width > _UINT32_MAX
-        or classification_width != classification_width_for_classes(class_count)
+        or not _class_dependent_weight_bytes_fit(class_count)
     ):
         raise ValueError("invalid model dimensions")
-    slot_schema = bytes.fromhex(_slot_schema_sha256(tuple(weight.name for weight in weights)))
 
     directory_offset = _HEADER_BYTES
     payload_offset = _round_up_to_alignment(directory_offset + _ENTRY_BYTES * len(weights))
@@ -193,16 +160,11 @@ def _pack_model_weights(
             packed.append(0)
         offset = len(packed)
         packed.extend(weight.payload)
-        digest = bytes.fromhex(sha256_bytes(weight.payload))
         _ENTRY.pack_into(
             packed,
             directory_offset + weight.slot * _ENTRY_BYTES,
-            weight.slot,
-            0,
             offset,
             len(weight.payload),
-            digest,
-            0,
         )
 
     _HEADER.pack_into(
@@ -210,15 +172,10 @@ def _pack_model_weights(
         0,
         _MAGIC,
         _VERSION,
-        _HEADER_BYTES,
         resolution,
         class_count,
         len(weights),
-        classification_width,
-        directory_offset,
         payload_offset,
-        len(packed),
-        slot_schema,
     )
     return bytes(packed)
 
@@ -227,12 +184,10 @@ def pack_model(
     lowered_weights: tuple[LoweredWeight, ...],
     resolution: int,
     class_count: int,
-    classification_width: int,
 ) -> bytes:
     """Validate stable weight identities and serialize the runtime model file."""
     return _pack_model_weights(
         _build_model_weight_table(lowered_weights),
         resolution,
         class_count,
-        classification_width,
     )

compiler/{minimal_runtime/compiler → converter}/model_validation.py

@@ -6,7 +6,7 @@ import math
 from dataclasses import dataclass
 
 from .checkpoint_decoder import DecodedModule, DecodedTensor
-from .compiler_io import RejectedInput
+from .converter_io import RejectedInput
 from .model_contract import (
     DETECTION_BRANCH_COUNT,
     DETECTION_STRIDES,

compiler/{minimal_runtime/compiler → converter}/validate.py

@@ -7,7 +7,7 @@ import argparse
 import json
 from pathlib import Path
 
-from .compiler_io import JsonObject, RejectedInput, atomic_write, canonical_bytes, sha256_bytes
+from .converter_io import JsonObject, RejectedInput, atomic_write, canonical_bytes, sha256_bytes
 from .export_yolo26n import ExportedModel, export_model
 
 _VALIDATION_VERSION = 1

compiler/{minimal_runtime/compiler → converter}/weight_lowering.py

@@ -10,7 +10,7 @@ import struct
 from dataclasses import dataclass
 from typing import cast
 
-from .compiler_io import RejectedInput
+from .converter_io import RejectedInput
 from .model_contract import (
     BOX_COORDINATE_CHANNELS,
     DETECTION_BRANCH_COUNT,

compiler/minimal_runtime/__init__.py

@@ -1 +0,0 @@
-"""Purpose-built YOLO26n export and native runtime sources."""

metadata.yaml

@@ -1,16 +1,16 @@
 # Metadata generated by ARM Model Optimization Pipeline
 version: 1.0.0
 task: vision-detection
-created_at: '2026-09-12T01:01:35Z'
+created_at: '2026-09-23T04:33:02Z'
 context:
   model:
     id: yolo26n
     base_model_id: yolo26n
     profile: Arm-Optimized
     weight_dtype: fp32
-    model_size_mb: 11.287
+    model_size_mb: 10.55
     parameter_count: 2572280
-    format: armrt-bundle
+    format: arm-yolo26n-bundle
   target:
     name: Raspberry Pi 5
     hardware_class: Edge Linux
@@ -22,7 +22,7 @@ context:
     os: linux
     os_version: Raspberry Pi OS Bookworm
   runtime:
-    name: armrt
+    name: arm-yolo26n
     execution_backend: cpu
     config:
       optimisations:
@@ -38,6 +38,6 @@ context:
     num_runs: 50
     warmup_runs: 10
 accuracy:
-  mAP_50_95_pct: 46.16
+  mAP_50_95_pct: 46.15
   mAP_50_pct: 49.47
   mAP_75_pct: 42.84

model/README.md

@@ -0,0 +1,6 @@
+# Model input
+
+To export another compatible YOLO26n model, place its checkpoint here as
+`yolo26n.pt`, then run `python3 repro.py export` from the repository root.
+
+No PyTorch checkpoint is distributed in this repository.

model/yolo26n.pt

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:9b09cc8bf347f0fc8a5f7657480587f25db09b34bf33b0652110fb03a8ad4fef
-size 5544453

python-api/__init__.py

@@ -1,10 +0,0 @@
-"""Python access to the native YOLO26n runtime."""
-
-from .errors import Yolo26RuntimeError
-from .yolo26n import Yolo26nRuntime
-
-
-__all__ = [
-    "Yolo26nRuntime",
-    "Yolo26RuntimeError",
-]

python-api/arm_yolo26n/__init__.py

@@ -0,0 +1,23 @@
+"""Tensor and image APIs for the purpose-built YOLO26n runtime."""
+
+from .detector import (
+    Detection,
+    DetectionResult,
+    DetectorConfig,
+    DetectorTimings,
+    PixelFormat,
+    Yolo26Detector,
+)
+from .errors import Yolo26nError
+from .yolo26n import Yolo26nTensorSession
+
+__all__ = [
+    "Detection",
+    "DetectionResult",
+    "DetectorConfig",
+    "DetectorTimings",
+    "PixelFormat",
+    "Yolo26Detector",
+    "Yolo26nTensorSession",
+    "Yolo26nError",
+]

python-api/arm_yolo26n/_model.py

@@ -0,0 +1,174 @@
+"""Load and validate one converted YOLO26n model directory."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from .errors import Yolo26nError
+
+# These values define the converted-model/runtime contract. They describe the
+# only model family and native target this purpose-built runtime accepts.
+_MODEL_KIND = "yolo26n-exported-model"
+_MODEL_VERSION = 1
+_TARGET = "linux-aarch64-raspberry-pi-5"
+
+# The Raspberry Pi 5 runtime owns a fixed four-worker pool, matching its four
+# CPU cores, so the thread count is part of model/runtime compatibility.
+_TARGET_THREAD_COUNT = 4
+_BOX_COORDINATE_CHANNELS = 4
+
+# Graph sizing and memory planning are implemented only for these profiles.
+_SUPPORTED_RESOLUTIONS = (320, 480, 640, 800, 960, 1280)
+
+# YOLO26n predicts at its P3, P4, and P5 feature levels.
+_DETECTION_STRIDES = (8, 16, 32)
+
+
+@dataclass(frozen=True, slots=True)
+class _LoadedModel:
+    """Validated metadata and serialized weights required by a session."""
+
+    input_shape: tuple[int, int, int, int]
+    output_shape: tuple[int, int, int]
+    class_names: tuple[str, ...]
+    model_bytes: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class _ArtifactRecord:
+    relative_path: Path
+    size: int
+    sha256: str
+
+    @classmethod
+    def from_manifest(cls, value: object) -> _ArtifactRecord:
+        """Parse the model artifact without accepting unknown fields."""
+        record = _require_mapping(value, "artifact")
+        if set(record) != {"bytes", "path", "sha256"}:
+            raise Yolo26nError("invalid artifact in YOLO26n model manifest")
+
+        path_value = record["path"]
+        size = record["bytes"]
+        digest = record["sha256"]
+        if (
+            not isinstance(path_value, str)
+            or type(size) is not int
+            or size < 0
+            or not isinstance(digest, str)
+            or len(digest) != 64
+            or any(character not in "0123456789abcdef" for character in digest)
+        ):
+            raise Yolo26nError("invalid artifact in YOLO26n model manifest")
+
+        relative_path = Path(path_value)
+        if relative_path.is_absolute() or ".." in relative_path.parts:
+            raise Yolo26nError("invalid artifact path in YOLO26n model manifest")
+        return cls(relative_path=relative_path, size=size, sha256=digest)
+
+    def load(self, model_directory: Path) -> bytes:
+        """Read the model bytes and verify their manifest record."""
+        path = model_directory / self.relative_path
+        try:
+            model_bytes = path.read_bytes()
+        except OSError as error:
+            raise Yolo26nError(
+                f"YOLO26n model artifact {self.relative_path.as_posix()!r} cannot be read"
+            ) from error
+        if len(model_bytes) != self.size or hashlib.sha256(model_bytes).hexdigest() != self.sha256:
+            raise Yolo26nError(
+                f"YOLO26n model artifact {self.relative_path.as_posix()!r} "
+                "does not match its manifest"
+            )
+        return model_bytes
+
+
+def _load_model(model_directory: str | Path) -> _LoadedModel:
+    """Validate one converted model before native code receives its weights."""
+    directory = Path(model_directory).expanduser().resolve()
+    if not directory.is_dir():
+        raise FileNotFoundError(f"YOLO26n model directory does not exist: {directory}")
+
+    manifest = _read_manifest(directory / "manifest.json")
+    if (manifest.get("kind"), manifest.get("version")) != (_MODEL_KIND, _MODEL_VERSION):
+        raise Yolo26nError("unsupported YOLO26n model manifest kind or version")
+
+    model = _require_mapping(manifest.get("model"), "model record")
+    input_shape = _require_shape(model.get("input_shape"), "input shape")
+    output_shape = _require_shape(model.get("output_shape"), "output shape")
+    resolution = input_shape[2] if len(input_shape) == 4 else None
+    if (
+        len(input_shape) != 4
+        or input_shape[:2] != (1, 3)
+        or input_shape[2] != input_shape[3]
+        or resolution not in _SUPPORTED_RESOLUTIONS
+    ):
+        raise Yolo26nError("unsupported YOLO26n input shape")
+    if (
+        len(output_shape) != 3
+        or output_shape[0] != 1
+        or output_shape[1] <= _BOX_COORDINATE_CHANNELS
+        or output_shape[2] != _detection_positions(resolution)
+    ):
+        raise Yolo26nError("unsupported YOLO26n output shape")
+
+    expected_target = {
+        "version": 1,
+        "target": _TARGET,
+        "input_shape": list(input_shape),
+        "input_dtype": "fp32",
+        "output_dtype": "fp32",
+        "thread_count": _TARGET_THREAD_COUNT,
+    }
+    if model.get("target") != expected_target:
+        raise Yolo26nError("unsupported YOLO26n target contract")
+
+    names = model.get("class_names")
+    if (
+        not isinstance(names, list)
+        or len(names) != output_shape[1] - _BOX_COORDINATE_CHANNELS
+        or any(not isinstance(name, str) or not name for name in names)
+    ):
+        raise Yolo26nError("invalid class names in YOLO26n model manifest")
+
+    artifact = _ArtifactRecord.from_manifest(manifest.get("artifact"))
+    return _LoadedModel(
+        input_shape=input_shape,
+        output_shape=output_shape,
+        class_names=tuple(cast(list[str], names)),
+        model_bytes=artifact.load(directory),
+    )
+
+
+def _read_manifest(path: Path) -> Mapping[str, object]:
+    try:
+        value: object = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise FileNotFoundError(f"YOLO26n model manifest does not exist: {path}") from None
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise Yolo26nError(f"invalid YOLO26n model manifest: {path}") from error
+    return _require_mapping(value, "manifest")
+
+
+def _require_mapping(value: object, name: str) -> Mapping[str, object]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise Yolo26nError(f"invalid {name} in YOLO26n model manifest")
+    return cast(Mapping[str, object], value)
+
+
+def _require_shape(value: object, name: str) -> tuple[int, ...]:
+    if (
+        not isinstance(value, list)
+        or not value
+        or any(type(dimension) is not int or dimension <= 0 for dimension in value)
+    ):
+        raise Yolo26nError(f"invalid {name} in YOLO26n model manifest")
+    return tuple(value)
+
+
+def _detection_positions(resolution: int) -> int:
+    return sum((resolution // stride) ** 2 for stride in _DETECTION_STRIDES)

python-api/arm_yolo26n/detector.py

@@ -0,0 +1,469 @@
+"""High-level YOLO26n detection for uint8 NumPy image frames."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from time import perf_counter
+from types import TracebackType
+from typing import Literal, Protocol, Self, cast
+
+import cv2
+import numpy as np
+from numpy.typing import NDArray
+
+from .errors import Yolo26nError
+from .yolo26n import Yolo26nTensorSession
+
+__all__ = [
+    "Detection",
+    "DetectionResult",
+    "DetectorConfig",
+    "DetectorTimings",
+    "PixelFormat",
+    "Yolo26Detector",
+]
+
+PixelFormat = Literal["BGR", "RGB", "BGRX"]
+_BOX_COORDINATE_CHANNELS = 4
+_LETTERBOX_VALUE = 114
+_MAX_NMS_CANDIDATES = 30_000
+_CLASS_BOX_OFFSET = 7680
+type _FloatArray = NDArray[np.float32]
+type _IndexArray = NDArray[np.int64]
+type _Uint8Array = NDArray[np.uint8]
+
+
+class _TensorSession(Protocol):
+    input_shape: tuple[int, int, int, int]
+    output_shape: tuple[int, int, int]
+    class_names: tuple[str, ...]
+
+    @property
+    def closed(self) -> bool: ...
+
+    def execute(self, tensor: _FloatArray) -> _FloatArray: ...
+
+    def _prepare_image_without_resize(
+        self,
+        frame: _Uint8Array,
+        *,
+        pixel_format: str,
+        output: _FloatArray,
+    ) -> None: ...
+
+    def close(self) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class DetectorConfig:
+    """Postprocessing settings for one detector instance."""
+
+    confidence: float = 0.25
+    iou: float = 0.45
+    max_detections: int = 300
+    multi_label: bool = True
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError("confidence must be between 0 and 1")
+        if not 0.0 <= self.iou <= 1.0:
+            raise ValueError("iou must be between 0 and 1")
+        if self.max_detections <= 0:
+            raise ValueError("max_detections must be positive")
+
+
+@dataclass(frozen=True, slots=True)
+class Detection:
+    """One detection in source-image pixel coordinates (x1, y1, x2, y2)."""
+
+    box: tuple[float, float, float, float]
+    confidence: float
+    class_id: int
+    class_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class DetectorTimings:
+    """Wall-clock time spent in each detector stage."""
+
+    preprocess_ms: float
+    inference_ms: float
+    postprocess_ms: float
+
+    @property
+    def total_ms(self) -> float:
+        return self.preprocess_ms + self.inference_ms + self.postprocess_ms
+
+
+@dataclass(frozen=True, slots=True)
+class DetectionResult:
+    """Detections and timing information for one source frame."""
+
+    detections: tuple[Detection, ...]
+    source_shape: tuple[int, int]
+    timings: DetectorTimings
+
+
+class Yolo26Detector:
+    """Convert image frames into labelled detections in source coordinates.
+
+    The detector applies letterboxing, normalization, native inference,
+    non-maximum suppression, and coordinate scaling. Each result also reports
+    time spent preprocessing, executing the runtime, and postprocessing. One
+    input tensor is reused between calls, so ``detect`` and ``close`` are
+    deliberately non-reentrant; use separate processes for concurrent
+    isolation. The runtime and model paths are keyword-only so callers cannot
+    silently reverse two path-like arguments.
+    """
+
+    def __init__(
+        self,
+        *,
+        runtime: str | Path,
+        model: str | Path,
+        config: DetectorConfig | None = None,
+    ) -> None:
+        self.config = config or DetectorConfig()
+        self._session: _TensorSession = Yolo26nTensorSession(runtime=runtime, model=model)
+        self._lifecycle_lock = threading.Lock()
+        try:
+            class_names = tuple(self._session.class_names)
+            input_shape = tuple(self._session.input_shape)
+            output_shape = tuple(self._session.output_shape)
+            if (
+                len(input_shape) != 4
+                or input_shape[:2] != (1, 3)
+                or input_shape[2] <= 0
+                or input_shape[2] != input_shape[3]
+            ):
+                raise ValueError(
+                    f"detector requires a square [1, 3, S, S] input, got {input_shape}"
+                )
+            if (
+                len(output_shape) != 3
+                or output_shape[0] != 1
+                or output_shape[1] <= _BOX_COORDINATE_CHANNELS
+                or output_shape[2] <= 0
+            ):
+                raise ValueError(
+                    "detector requires output shape [1, 4 + classes, positions], "
+                    f"got {output_shape}"
+                )
+            output_class_count = output_shape[1] - _BOX_COORDINATE_CHANNELS
+            if len(class_names) != output_class_count or any(
+                not isinstance(name, str) or not name for name in class_names
+            ):
+                raise ValueError(
+                    "detector class names must be non-empty strings matching the "
+                    f"{output_class_count} output classes; got {len(class_names)}"
+                )
+        except BaseException:
+            self._session.close()
+            raise
+        self.class_names = class_names
+        self.input_shape = input_shape
+        self.output_shape = output_shape
+        self._input_hw = (input_shape[2], input_shape[3])
+        self._input_tensor = np.empty(input_shape, dtype=np.float32)
+
+    @property
+    def closed(self) -> bool:
+        return self._session.closed
+
+    def detect(
+        self,
+        frame: _Uint8Array,
+        *,
+        pixel_format: PixelFormat,
+        on_frame_consumed: Callable[[], None] | None = None,
+    ) -> DetectionResult:
+        """Detect objects in one uint8 HWC BGR, RGB, or BGRX frame.
+
+        Pixel-order conversion, letterboxing, normalization, native execution,
+        non-maximum suppression, and box scaling are all included. Frames whose
+        longest side already matches the square model input take the native
+        no-resize path: centered value-114 padding, channel conversion,
+        HWC-to-CHW conversion, and FP32 normalization are fused into the reused
+        input tensor. Frames requiring interpolation use centered letterboxing.
+        If provided, ``on_frame_consumed`` is called exactly once after the
+        input tensor no longer refers to the source frame and before inference.
+        """
+        source_shape = self._validate_frame(frame, pixel_format)
+        if not self._lifecycle_lock.acquire(blocking=False):
+            raise Yolo26nError("concurrent detection or close is not supported")
+
+        try:
+            if self.closed:
+                raise Yolo26nError("detector is closed")
+
+            preprocess_started_at = perf_counter()
+            self._prepare_input(frame, source_shape, pixel_format)
+            preprocess_ms = (perf_counter() - preprocess_started_at) * 1000
+            if on_frame_consumed is not None:
+                on_frame_consumed()
+
+            inference_started_at = perf_counter()
+            raw = self._run_inference()
+            inference_ms = (perf_counter() - inference_started_at) * 1000
+
+            postprocess_started_at = perf_counter()
+            detections = self._postprocess(raw, source_shape)
+            postprocess_ms = (perf_counter() - postprocess_started_at) * 1000
+            return DetectionResult(
+                detections=detections,
+                source_shape=source_shape,
+                timings=DetectorTimings(
+                    preprocess_ms=preprocess_ms,
+                    inference_ms=inference_ms,
+                    postprocess_ms=postprocess_ms,
+                ),
+            )
+        finally:
+            self._lifecycle_lock.release()
+
+    @staticmethod
+    def _validate_frame(
+        frame: _Uint8Array,
+        pixel_format: PixelFormat,
+    ) -> tuple[int, int]:
+        if not isinstance(frame, np.ndarray):
+            raise TypeError("frame must be a numpy.ndarray")
+        if frame.dtype != np.uint8:
+            raise TypeError("frame must have dtype uint8")
+        if pixel_format not in ("BGR", "RGB", "BGRX"):
+            raise ValueError("pixel_format must be 'BGR', 'RGB', or 'BGRX'")
+        expected_channels = 4 if pixel_format == "BGRX" else 3
+        if frame.ndim != 3 or frame.shape[2] != expected_channels:
+            raise ValueError(
+                f"{pixel_format} frame must have shape [height, width, {expected_channels}]"
+            )
+        if frame.shape[0] == 0 or frame.shape[1] == 0:
+            raise ValueError("frame dimensions must be positive")
+        return (int(frame.shape[0]), int(frame.shape[1]))
+
+    def _prepare_input(
+        self,
+        frame: _Uint8Array,
+        source_shape: tuple[int, int],
+        pixel_format: PixelFormat,
+    ) -> None:
+        if max(source_shape) == self._input_hw[0]:
+            self._session._prepare_image_without_resize(
+                frame,
+                pixel_format=pixel_format,
+                output=self._input_tensor,
+            )
+            return
+
+        three_channel_frame = frame[..., :3] if pixel_format == "BGRX" else frame
+        image = _letterbox(three_channel_frame, self._input_hw)
+        image_rgb = image[..., ::-1] if pixel_format in ("BGR", "BGRX") else image
+        np.copyto(
+            self._input_tensor[0],
+            image_rgb.transpose(2, 0, 1),
+            casting="unsafe",
+        )
+        np.divide(self._input_tensor, np.float32(255.0), out=self._input_tensor)
+
+    def _run_inference(self) -> _FloatArray:
+        return self._session.execute(self._input_tensor)
+
+    def _postprocess(
+        self,
+        raw: _FloatArray,
+        source_shape: tuple[int, int],
+    ) -> tuple[Detection, ...]:
+        processed = _non_max_suppression(
+            raw[0],
+            confidence=self.config.confidence,
+            iou=self.config.iou,
+            max_detections=self.config.max_detections,
+            multi_label=self.config.multi_label,
+        )
+        _scale_boxes(processed[:, :4], self._input_hw, source_shape)
+        detections = []
+        for row in processed:
+            class_id = int(row[5])
+            if not 0 <= class_id < len(self.class_names):
+                raise Yolo26nError(f"postprocessing returned unknown class ID {class_id}")
+            x1, y1, x2, y2 = (float(value) for value in row[:4])
+            if x2 <= x1 or y2 <= y1:
+                continue
+            detections.append(
+                Detection(
+                    box=(x1, y1, x2, y2),
+                    confidence=float(row[4]),
+                    class_id=class_id,
+                    class_name=self.class_names[class_id],
+                )
+            )
+        return tuple(detections)
+
+    def close(self) -> None:
+        """Release the detector's tensor session; repeated calls are safe."""
+        with self._lifecycle_lock:
+            self._session.close()
+
+    def __enter__(self) -> Self:
+        if self.closed:
+            raise Yolo26nError("detector is closed")
+        return self
+
+    def __exit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        _exc_value: BaseException | None,
+        _traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def _letterbox(image: _Uint8Array, target_shape: tuple[int, int]) -> _Uint8Array:
+    """Resize without distortion, then center the image on a square canvas."""
+    source_height, source_width = image.shape[:2]
+    target_height, target_width = target_shape
+    scale = min(target_height / source_height, target_width / source_width)
+    resized_width = round(source_width * scale)
+    resized_height = round(source_height * scale)
+    if (source_width, source_height) != (resized_width, resized_height):
+        image = cast(
+            _Uint8Array,
+            cv2.resize(
+                image,
+                (resized_width, resized_height),
+                interpolation=cv2.INTER_LINEAR,
+            ),
+        )
+
+    horizontal_padding = (target_width - resized_width) / 2
+    vertical_padding = (target_height - resized_height) / 2
+    left = round(horizontal_padding - 0.1)
+    right = round(horizontal_padding + 0.1)
+    top = round(vertical_padding - 0.1)
+    bottom = round(vertical_padding + 0.1)
+    return cast(
+        _Uint8Array,
+        cv2.copyMakeBorder(
+            image,
+            top,
+            bottom,
+            left,
+            right,
+            cv2.BORDER_CONSTANT,
+            value=(_LETTERBOX_VALUE,) * 3,
+        ),
+    )
+
+
+def _xywh_to_xyxy(boxes: _FloatArray) -> _FloatArray:
+    converted = np.empty_like(boxes)
+    half_size = boxes[:, 2:] / np.float32(2.0)
+    converted[:, :2] = boxes[:, :2] - half_size
+    converted[:, 2:] = boxes[:, :2] + half_size
+    return converted
+
+
+def _candidate_detections(
+    prediction: _FloatArray,
+    confidence: float,
+    multi_label: bool,
+) -> _FloatArray:
+    class_scores = prediction[_BOX_COORDINATE_CHANNELS:].T
+    candidate_positions = np.max(class_scores, axis=1) > confidence
+    if not np.any(candidate_positions):
+        return np.empty((0, 6), dtype=np.float32)
+
+    boxes = _xywh_to_xyxy(prediction[:_BOX_COORDINATE_CHANNELS].T[candidate_positions])
+    scores = class_scores[candidate_positions]
+    if multi_label and scores.shape[1] > 1:
+        box_indices, class_ids = np.nonzero(scores > confidence)
+        return np.column_stack(
+            (boxes[box_indices], scores[box_indices, class_ids], class_ids.astype(np.float32))
+        ).astype(np.float32, copy=False)
+
+    class_ids = np.argmax(scores, axis=1)
+    confidences = scores[np.arange(len(scores)), class_ids]
+    accepted = confidences > confidence
+    return np.column_stack(
+        (boxes[accepted], confidences[accepted], class_ids[accepted].astype(np.float32))
+    ).astype(np.float32, copy=False)
+
+
+def _nms_indices(
+    boxes: _FloatArray,
+    scores: _FloatArray,
+    iou: float,
+) -> _IndexArray:
+    """Return descending-confidence indices after class-aware box suppression."""
+    if not len(boxes):
+        return np.empty(0, dtype=np.int64)
+    x1, y1, x2, y2 = boxes.T
+    areas = (x2 - x1) * (y2 - y1)
+    # Reversing a stable ascending order makes exact score ties deterministic:
+    # the later model candidate takes precedence.
+    order = np.argsort(scores, kind="stable")[::-1]
+    kept: list[int] = []
+    while len(order):
+        current = int(order[0])
+        kept.append(current)
+        if len(order) == 1:
+            break
+        remaining = order[1:]
+        intersection_width = np.maximum(
+            np.minimum(x2[current], x2[remaining]) - np.maximum(x1[current], x1[remaining]),
+            np.float32(0.0),
+        )
+        intersection_height = np.maximum(
+            np.minimum(y2[current], y2[remaining]) - np.maximum(y1[current], y1[remaining]),
+            np.float32(0.0),
+        )
+        intersection = intersection_width * intersection_height
+        overlap = intersection / (areas[current] + areas[remaining] - intersection)
+        order = remaining[overlap <= iou]
+    return np.asarray(kept, dtype=np.int64)
+
+
+def _non_max_suppression(
+    prediction: _FloatArray,
+    *,
+    confidence: float,
+    iou: float,
+    max_detections: int,
+    multi_label: bool,
+) -> _FloatArray:
+    detections = _candidate_detections(prediction, confidence, multi_label)
+    if not len(detections):
+        return detections
+    if len(detections) > _MAX_NMS_CANDIDATES:
+        highest_confidence = np.argsort(detections[:, 4], kind="stable")[::-1][:_MAX_NMS_CANDIDATES]
+        detections = detections[highest_confidence]
+
+    # Offsetting coordinates by class prevents boxes from different classes
+    # suppressing one another while retaining a single vectorized NMS pass.
+    class_offsets = detections[:, 5:6] * np.float32(_CLASS_BOX_OFFSET)
+    boxes = detections[:, :4] + class_offsets
+    kept = _nms_indices(boxes, detections[:, 4], iou)[:max_detections]
+    return detections[kept]
+
+
+def _scale_boxes(
+    boxes: _FloatArray,
+    model_shape: tuple[int, int],
+    source_shape: tuple[int, int],
+) -> None:
+    """Map letterboxed model coordinates back to source-image pixels."""
+    if not len(boxes):
+        return
+    model_height, model_width = model_shape
+    source_height, source_width = source_shape
+    scale = min(model_height / source_height, model_width / source_width)
+    horizontal_padding = round((model_width - round(source_width * scale)) / 2 - 0.1)
+    vertical_padding = round((model_height - round(source_height * scale)) / 2 - 0.1)
+    boxes[:, (0, 2)] -= horizontal_padding
+    boxes[:, (1, 3)] -= vertical_padding
+    boxes /= np.float32(scale)
+    boxes[:, (0, 2)] = boxes[:, (0, 2)].clip(0, source_width)
+    boxes[:, (1, 3)] = boxes[:, (1, 3)].clip(0, source_height)

python-api/arm_yolo26n/errors.py

@@ -0,0 +1,7 @@
+"""Exceptions raised by the YOLO26n Python APIs."""
+
+__all__ = ["Yolo26nError"]
+
+
+class Yolo26nError(RuntimeError):
+    """A YOLO26n operation could not be completed."""

python-api/{yolo26n.py → arm_yolo26n/yolo26n.py}

@@ -1,38 +1,46 @@
-"""Python tensor boundary for an exported YOLO26n runtime bundle."""
+"""Low-level tensor access to the native YOLO26n runtime."""
 
 from __future__ import annotations
 
 import ctypes
-import hashlib
-import json
 import os
 import threading
-from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 from types import TracebackType
-from typing import Self, cast
+from typing import Self
 
 import numpy as np
-import torch
+from numpy.typing import NDArray
 
-from .errors import Yolo26RuntimeError
+from ._model import _load_model
+from .errors import Yolo26nError
 
-__all__ = ["Yolo26nRuntime"]
+__all__ = ["Yolo26nTensorSession"]
 
+# The fixed topology is deliberately partitioned into nineteen XNNPACK
+# subgraphs so the native schedule can run custom work between graph segments.
+_EXPECTED_GRAPH_COUNT = 19
+_NATIVE_STATUS_OK = 0
+type _FloatArray = NDArray[np.float32]
+type _Uint8Array = NDArray[np.uint8]
 
-_BUNDLE_KIND = "yolo26n-native-bundle"
-_BUNDLE_VERSION = 1
-_THREAD_COUNT = 4
-_GRAPH_COUNT = 19
-_OK = 0
-_BOX_COORDINATE_CHANNELS = 4
-_SUPPORTED_RESOLUTIONS = (320, 480, 640, 800, 960, 1280)
-_PIXEL_FORMATS = {"BGR": (0, 3), "RGB": (1, 3), "BGRX": (2, 4)}
+
+@dataclass(frozen=True, slots=True)
+class _PixelFormat:
+    """Python view of one y26_native_pixel_format value."""
+
+    native_value: int
+    channels: int
 
 
-def _detection_positions(resolution: int) -> int:
-    return sum((resolution // stride) ** 2 for stride in (8, 16, 32))
+# Native values must remain synchronized with y26_native_pixel_format in
+# arm_yolo26n.h. Channel counts validate the interleaved source array.
+_PIXEL_FORMATS = {
+    "BGR": _PixelFormat(native_value=0, channels=3),
+    "RGB": _PixelFormat(native_value=1, channels=3),
+    "BGRX": _PixelFormat(native_value=2, channels=4),
+}
 
 
 def _elements(shape: tuple[int, ...]) -> int:
@@ -42,148 +50,10 @@ def _elements(shape: tuple[int, ...]) -> int:
     return result
 
 
-def _sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as stream:
-        for block in iter(lambda: stream.read(1024 * 1024), b""):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def _read_manifest(path: Path) -> Mapping[str, object]:
-    try:
-        value: object = json.loads(path.read_text(encoding="utf-8"))
-    except FileNotFoundError:
-        raise FileNotFoundError(f"YOLO26n runtime manifest does not exist: {path}") from None
-    except (UnicodeDecodeError, json.JSONDecodeError) as error:
-        raise Yolo26RuntimeError(f"invalid YOLO26n runtime manifest: {path}") from error
-    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
-        raise Yolo26RuntimeError("YOLO26n runtime manifest must be an object")
-    return cast(Mapping[str, object], value)
-
-
-def _mapping(value: object, name: str) -> Mapping[str, object]:
-    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
-        raise Yolo26RuntimeError(f"invalid {name} in YOLO26n runtime manifest")
-    return cast(Mapping[str, object], value)
-
-
-def _shape(value: object, name: str) -> tuple[int, ...]:
-    if (
-        not isinstance(value, list)
-        or not value
-        or any(type(dimension) is not int or dimension <= 0 for dimension in value)
-    ):
-        raise Yolo26RuntimeError(f"invalid {name} in YOLO26n runtime manifest")
-    return tuple(value)
-
-
-@dataclass(frozen=True, slots=True)
-class _ArtifactIdentity:
-    relative_path: Path
-    size: int
-    sha256: str
-
-    @classmethod
-    def parse(cls, value: object, name: str) -> Self:
-        record = _mapping(value, f"{name} identity")
-        if set(record) != {"bytes", "path", "sha256"}:
-            raise Yolo26RuntimeError(f"invalid {name} identity in YOLO26n runtime manifest")
-        path_value = record["path"]
-        size = record["bytes"]
-        sha256 = record["sha256"]
-        if (
-            not isinstance(path_value, str)
-            or type(size) is not int
-            or size < 0
-            or not isinstance(sha256, str)
-            or len(sha256) != 64
-            or any(character not in "0123456789abcdef" for character in sha256)
-        ):
-            raise Yolo26RuntimeError(f"invalid {name} identity in YOLO26n runtime manifest")
-        relative_path = Path(path_value)
-        if relative_path.is_absolute() or ".." in relative_path.parts:
-            raise Yolo26RuntimeError(f"invalid {name} path in YOLO26n runtime manifest")
-        return cls(relative_path=relative_path, size=size, sha256=sha256)
-
-    def resolve(self, bundle: Path, name: str) -> Path:
-        path = bundle / self.relative_path
-        if not path.is_file() or path.stat().st_size != self.size or _sha256(path) != self.sha256:
-            raise Yolo26RuntimeError(f"YOLO26n runtime {name} identity mismatch")
-        return path
-
-
-@dataclass(frozen=True, slots=True)
-class _BundleData:
-    input_shape: tuple[int, int, int, int]
-    output_shape: tuple[int, int, int]
-    class_names: tuple[str, ...]
-    library_path: Path
-    model_path: Path
-
-    @classmethod
-    def load(cls, bundle: str | Path) -> Self:
-        directory = Path(bundle).expanduser().resolve()
-        if not directory.is_dir():
-            raise FileNotFoundError(f"YOLO26n runtime bundle does not exist: {directory}")
-        manifest = _read_manifest(directory / "manifest.json")
-        if (manifest.get("kind"), manifest.get("version")) != (
-            _BUNDLE_KIND,
-            _BUNDLE_VERSION,
-        ):
-            raise Yolo26RuntimeError("unsupported YOLO26n runtime bundle kind or version")
-
-        model = _mapping(manifest.get("model"), "model record")
-        input_shape = _shape(model.get("input_shape"), "input shape")
-        output_shape = _shape(model.get("output_shape"), "output shape")
-        resolution = input_shape[2] if len(input_shape) == 4 else None
-        if (
-            len(input_shape) != 4
-            or input_shape[:2] != (1, 3)
-            or input_shape[2] != input_shape[3]
-            or resolution not in _SUPPORTED_RESOLUTIONS
-        ):
-            raise Yolo26RuntimeError("unsupported YOLO26n input shape")
-        if (
-            len(output_shape) != 3
-            or output_shape[0] != 1
-            or output_shape[1] <= _BOX_COORDINATE_CHANNELS
-            or output_shape[2] != _detection_positions(cast(int, resolution))
-        ):
-            raise Yolo26RuntimeError("unsupported YOLO26n output shape")
-
-        expected_target = {
-            "version": 1,
-            "target": "linux-aarch64-raspberry-pi-5",
-            "input_shape": list(input_shape),
-            "input_dtype": "fp32",
-            "output_dtype": "fp32",
-            "thread_count": _THREAD_COUNT,
-        }
-        if manifest.get("target") != expected_target:
-            raise Yolo26RuntimeError("unsupported YOLO26n target contract")
-
-        names = model.get("class_names")
-        if (
-            not isinstance(names, list)
-            or len(names) != output_shape[1] - _BOX_COORDINATE_CHANNELS
-            or any(not isinstance(name, str) or not name for name in names)
-        ):
-            raise Yolo26RuntimeError("invalid class names in YOLO26n runtime manifest")
-        artifacts = _mapping(manifest.get("artifacts"), "artifact records")
-        runtime = _ArtifactIdentity.parse(artifacts.get("runtime"), "runtime")
-        exported_model = _ArtifactIdentity.parse(artifacts.get("model"), "model")
-        return cls(
-            input_shape=cast(tuple[int, int, int, int], input_shape),
-            output_shape=cast(tuple[int, int, int], output_shape),
-            class_names=tuple(cast(list[str], names)),
-            library_path=runtime.resolve(directory, "runtime"),
-            model_path=exported_model.resolve(directory, "model"),
-        )
-
-
 @dataclass(frozen=True, slots=True)
 class _NativeModelContract:
+    """Model facts reported by a newly created native handle."""
+
     graph_count: int
     resolution: int
     class_count: int
@@ -192,12 +62,12 @@ class _NativeModelContract:
     calls: int
 
 
-class _Yolo26nLibrary:
+class _NativeLibrary:
     """Bind the YOLO26n C API and translate calls to Python values."""
 
     def __init__(self, path: Path) -> None:
         self._raw = ctypes.CDLL(str(path), mode=os.RTLD_NOW | os.RTLD_LOCAL)
-        self._raw.y26_native_create.argtypes = [ctypes.c_char_p]
+        self._raw.y26_native_create.argtypes = [ctypes.c_void_p, ctypes.c_size_t]
         self._raw.y26_native_create.restype = ctypes.c_void_p
         self._raw.y26_native_execute.argtypes = [
             ctypes.c_void_p,
@@ -212,6 +82,7 @@ class _Yolo26nLibrary:
             ctypes.c_size_t,
             ctypes.c_size_t,
             ctypes.c_size_t,
+            ctypes.c_size_t,
             ctypes.c_int,
             ctypes.c_void_p,
             ctypes.c_size_t,
@@ -232,8 +103,9 @@ class _Yolo26nLibrary:
             function.argtypes = [ctypes.c_void_p]
             function.restype = ctypes.c_size_t
 
-    def create(self, model: Path) -> ctypes.c_void_p:
-        return ctypes.c_void_p(self._raw.y26_native_create(os.fsencode(model)))
+    def create(self, model: bytes) -> ctypes.c_void_p:
+        model_pointer = ctypes.cast(ctypes.c_char_p(model), ctypes.c_void_p)
+        return ctypes.c_void_p(self._raw.y26_native_create(model_pointer, len(model)))
 
     def model_contract(self, handle: ctypes.c_void_p) -> _NativeModelContract:
         return _NativeModelContract(
@@ -248,34 +120,36 @@ class _Yolo26nLibrary:
     def execute(
         self,
         handle: ctypes.c_void_p,
-        model_input: torch.Tensor,
-        output: torch.Tensor,
+        model_input: _FloatArray,
+        output: _FloatArray,
     ) -> int:
         return int(
             self._raw.y26_native_execute(
                 handle,
-                model_input.data_ptr(),
-                model_input.numel() * model_input.element_size(),
-                output.data_ptr(),
-                output.numel() * output.element_size(),
+                model_input.ctypes.data,
+                model_input.nbytes,
+                output.ctypes.data,
+                output.nbytes,
             )
         )
 
     def preprocess_image_no_resize(
         self,
-        frame: np.ndarray,
+        frame: _Uint8Array,
         pixel_format: int,
-        output: torch.Tensor,
+        output: _FloatArray,
     ) -> int:
+        """Invoke native preprocessing while preserving padded source rows."""
         return int(
             self._raw.y26_native_preprocess_image_no_resize(
                 frame.ctypes.data,
+                _image_span_bytes(frame),
                 frame.shape[0],
                 frame.shape[1],
                 frame.strides[0],
                 pixel_format,
-                output.data_ptr(),
-                output.numel() * output.element_size(),
+                output.ctypes.data,
+                output.nbytes,
             )
         )
 
@@ -283,34 +157,56 @@ class _Yolo26nLibrary:
         self._raw.y26_native_destroy(handle)
 
 
-class Yolo26nRuntime:
-    """Own one validated, fixed-contract YOLO26n native runtime."""
-
-    def __init__(self, bundle: str | Path) -> None:
-        bundle_data = _BundleData.load(bundle)
-        self.input_shape = bundle_data.input_shape
-        self.output_shape = bundle_data.output_shape
-        self.class_names = bundle_data.class_names
+def _image_span_bytes(frame: _Uint8Array) -> int:
+    """Return bytes through the final pixel, including padding between rows."""
+    final_row_offset = (frame.shape[0] - 1) * frame.strides[0]
+    visible_row_bytes = frame.shape[1] * frame.shape[2]
+    return int(final_row_offset + visible_row_bytes)
+
+
+class Yolo26nTensorSession:
+    """Execute raw tensors with the native runtime and converted model.
+
+    This is the low-level Python interface. Use it when the caller already
+    owns preprocessing and postprocessing and needs direct FP32 NCHW tensor
+    execution. `Yolo26Detector` is the image-oriented API.
+
+    A session owns one native model handle and its worker resources. Calls are
+    deliberately non-reentrant; create independent sessions in separate
+    processes when concurrent isolation is required. Prefer using the session
+    as a context manager so the native resources are released deterministically.
+    The runtime and model paths are keyword-only so callers cannot silently
+    reverse two path-like arguments.
+    """
+
+    def __init__(self, *, runtime: str | Path, model: str | Path) -> None:
+        runtime_path = Path(runtime).expanduser().resolve()
+        if not runtime_path.is_file():
+            raise FileNotFoundError(f"YOLO26n runtime library does not exist: {runtime_path}")
+        model_data = _load_model(model)
+        self.input_shape = model_data.input_shape
+        self.output_shape = model_data.output_shape
+        self.class_names = model_data.class_names
         self._lifecycle_lock = threading.Lock()
         self._handle = ctypes.c_void_p()
         try:
-            self._native = _Yolo26nLibrary(bundle_data.library_path)
-            self._handle = self._native.create(bundle_data.model_path)
+            self._native = _NativeLibrary(runtime_path)
+            self._handle = self._native.create(model_data.model_bytes)
             if not self._handle.value:
-                raise Yolo26RuntimeError("YOLO26n runtime rejected its exported model")
+                raise Yolo26nError("YOLO26n runtime rejected its exported model")
             expected_input_bytes = 4 * _elements(self.input_shape)
             expected_output_bytes = 4 * _elements(self.output_shape)
             native_contract = self._native.model_contract(self._handle)
             if (
-                native_contract.graph_count != _GRAPH_COUNT
+                native_contract.graph_count != _EXPECTED_GRAPH_COUNT
                 or native_contract.resolution != self.input_shape[2]
                 or native_contract.class_count != len(self.class_names)
                 or native_contract.input_bytes != expected_input_bytes
                 or native_contract.output_bytes != expected_output_bytes
             ):
-                raise Yolo26RuntimeError("YOLO26n runtime and bundle contracts disagree")
+                raise Yolo26nError("YOLO26n runtime and model contracts disagree")
             if native_contract.calls != 0:
-                raise Yolo26RuntimeError("YOLO26n runtime call counter was not initialized")
+                raise Yolo26nError("YOLO26n runtime call counter was not initialized")
         except BaseException:
             self.close()
             raise
@@ -319,79 +215,90 @@ class Yolo26nRuntime:
     def closed(self) -> bool:
         return not bool(self._handle.value)
 
-    def execute(self, tensor: torch.Tensor) -> torch.Tensor:
+    def execute(self, tensor: _FloatArray) -> _FloatArray:
+        """Execute one FP32 NCHW tensor and return the raw YOLO26n prediction.
+
+        The input must match `input_shape`. A non-contiguous array is copied
+        into contiguous storage before entering native code. The returned FP32
+        array always has `output_shape`.
+        """
         if self.closed:
-            raise Yolo26RuntimeError("YOLO26n runtime is closed")
-        if not isinstance(tensor, torch.Tensor):
-            raise TypeError("input must be a torch.Tensor")
-        if tensor.device.type != "cpu":
-            raise ValueError("input tensor must be on the CPU")
-        if tensor.dtype is not torch.float32:
-            raise TypeError("input tensor must have dtype torch.float32")
+            raise Yolo26nError("YOLO26n runtime is closed")
+        if not isinstance(tensor, np.ndarray):
+            raise TypeError("input must be a numpy.ndarray")
+        if tensor.dtype != np.float32:
+            raise TypeError("input array must have dtype float32")
         if tuple(tensor.shape) != self.input_shape:
             raise ValueError(f"input shape {tuple(tensor.shape)} does not match {self.input_shape}")
-        if not tensor.is_contiguous():
-            tensor = tensor.contiguous()
+        tensor = np.ascontiguousarray(tensor)
         if not self._lifecycle_lock.acquire(blocking=False):
-            raise Yolo26RuntimeError("concurrent execution or close is not supported")
+            raise Yolo26nError("concurrent execution or close is not supported")
         try:
             if self.closed:
-                raise Yolo26RuntimeError("YOLO26n runtime is closed")
-            output = torch.empty(self.output_shape, dtype=torch.float32, device="cpu")
+                raise Yolo26nError("YOLO26n runtime is closed")
+            output = np.empty(self.output_shape, dtype=np.float32)
             status = self._native.execute(self._handle, tensor, output)
-            if status != _OK:
-                raise Yolo26RuntimeError(f"YOLO26n runtime execution failed with status {status}")
+            if status != _NATIVE_STATUS_OK:
+                raise Yolo26nError(f"YOLO26n runtime execution failed with status {status}")
             return output
         finally:
             self._lifecycle_lock.release()
 
-    def preprocess_image_no_resize(
+    def _prepare_image_without_resize(
         self,
-        frame: np.ndarray,
+        frame: _Uint8Array,
         *,
         pixel_format: str,
-        output: torch.Tensor,
+        output: _FloatArray,
     ) -> None:
+        """Fill a model-input tensor from an image that needs padding but no resize.
+
+        The detector uses this package-internal fast path after determining
+        that the source image's longest side already equals the model
+        resolution. Native code fuses centered value-114 padding, BGR/BGRX to
+        RGB conversion, HWC-to-NCHW conversion, and FP32 normalization. Callers
+        of the public tensor API should prepare their own input instead.
+        """
         if self.closed:
-            raise Yolo26RuntimeError("YOLO26n runtime is closed")
+            raise Yolo26nError("YOLO26n runtime is closed")
         if not isinstance(frame, np.ndarray) or frame.dtype != np.uint8:
             raise TypeError("frame must be a uint8 numpy.ndarray")
         try:
-            native_pixel_format, channels = _PIXEL_FORMATS[pixel_format]
+            format_contract = _PIXEL_FORMATS[pixel_format]
         except KeyError as error:
             raise ValueError("pixel_format must be 'BGR', 'RGB', or 'BGRX'") from error
-        if frame.ndim != 3 or frame.shape[2] != channels:
-            raise ValueError(f"{pixel_format} frame must have shape [height, width, {channels}]")
-        if frame.strides[1:] != (channels, 1) or frame.strides[0] <= 0:
+        if frame.ndim != 3 or frame.shape[2] != format_contract.channels:
+            raise ValueError(
+                f"{pixel_format} frame must have shape [height, width, {format_contract.channels}]"
+            )
+        if frame.strides[1:] != (format_contract.channels, 1) or frame.strides[0] <= 0:
             raise ValueError("frame must have interleaved, forward uint8 pixels")
         if (
-            not isinstance(output, torch.Tensor)
-            or output.device.type != "cpu"
-            or output.dtype is not torch.float32
+            not isinstance(output, np.ndarray)
+            or output.dtype != np.float32
             or tuple(output.shape) != self.input_shape
-            or not output.is_contiguous()
+            or not output.flags.c_contiguous
         ):
             raise ValueError(
-                f"output must be a contiguous CPU FP32 tensor with shape {self.input_shape}"
+                f"output must be a contiguous FP32 array with shape {self.input_shape}"
             )
         if not self._lifecycle_lock.acquire(blocking=False):
-            raise Yolo26RuntimeError("concurrent execution or close is not supported")
+            raise Yolo26nError("concurrent execution or close is not supported")
         try:
             if self.closed:
-                raise Yolo26RuntimeError("YOLO26n runtime is closed")
+                raise Yolo26nError("YOLO26n runtime is closed")
             status = self._native.preprocess_image_no_resize(
                 frame,
-                native_pixel_format,
+                format_contract.native_value,
                 output,
             )
-            if status != _OK:
-                raise Yolo26RuntimeError(
-                    f"YOLO26n runtime preprocessing failed with status {status}"
-                )
+            if status != _NATIVE_STATUS_OK:
+                raise Yolo26nError(f"YOLO26n runtime preprocessing failed with status {status}")
         finally:
             self._lifecycle_lock.release()
 
     def close(self) -> None:
+        """Release the native model handle; repeated calls are safe."""
         lock = getattr(self, "_lifecycle_lock", None)
         if lock is None:
             return
@@ -404,7 +311,7 @@ class Yolo26nRuntime:
 
     def __enter__(self) -> Self:
         if self.closed:
-            raise Yolo26RuntimeError("YOLO26n runtime is closed")
+            raise Yolo26nError("YOLO26n runtime is closed")
         return self
 
     def __exit__(

python-api/errors.py

@@ -1,7 +0,0 @@
-"""Errors shared by the native YOLO26 runtime wrappers."""
-
-__all__ = ["Yolo26RuntimeError"]
-
-
-class Yolo26RuntimeError(RuntimeError):
-    """A native YOLO26 runtime rejected an operation."""

repro.py

@@ -14,14 +14,24 @@ import subprocess
 import sys
 import tempfile
 import time
+from urllib.request import urlopen
 
 
 ROOT = Path(__file__).resolve().parent
 VENV = ROOT / ".venv"
 MIB = 1024 * 1024
 DATASET_REPO = "Arm/coco-128-by-sa"
-DATASET_REVISION = "cb1edb8da4ff3cb54d40ecb12d3efecc116ff3de"
+DATASET_REVISION = "f8af0a317c0b54c3dbd38c70b9757dccb8b02460"
 DATASET_DIR = ROOT / "data/coco-128-by-sa"
+STOCK_CHECKPOINT_URL = (
+    "https://github.com/ultralytics/assets/releases/download/v8.4.0/yolo26n.pt"
+)
+STOCK_CHECKPOINT_SHA256 = (
+    "9b09cc8bf347f0fc8a5f7657480587f25db09b34bf33b0652110fb03a8ad4fef"
+)
+STOCK_CHECKPOINT = ROOT / "downloads/yolo26n.pt"
+SUPPLIED_MODEL = ROOT / "runtime/arm_yolo26n_pi5_model"
+EXPORTED_MODEL = ROOT / "build/arm_yolo26n_pi5_model"
 
 
 def run(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
@@ -34,6 +44,9 @@ def setup() -> None:
     model_path = Path("/proc/device-tree/model")
     if not model_path.is_file() or "Raspberry Pi 5" not in model_path.read_text():
         raise SystemExit("this package is for Raspberry Pi 5")
+    os_release = Path("/etc/os-release").read_text(encoding="utf-8")
+    if "VERSION_CODENAME=trixie" not in os_release:
+        raise SystemExit("this package is validated on Raspberry Pi OS Trixie")
 
     run([sys.executable, "-m", "venv", str(VENV)])
     python = VENV / "bin/python"
@@ -49,7 +62,7 @@ def setup() -> None:
             "torch==2.12.1+cpu",
             "torchvision==0.27.1+cpu",
             "ultralytics==8.4.108",
-            "numpy==2.3.5",
+            "numpy==2.2.4",
             "opencv-python==5.0.0.93",
             "pillow==12.3.0",
             "PyYAML==6.0.3",
@@ -63,17 +76,15 @@ def setup() -> None:
         capture_output=True,
     )
     site = Path(site_result.stdout.strip())
-    api_destination = site / "yolo26_runtime"
-    api_destination.mkdir(parents=True, exist_ok=True)
-    for source in (ROOT / "python-api").glob("*.py"):
-        shutil.copy2(source, api_destination / source.name)
+    api_destination = site / "arm_yolo26n"
+    shutil.copytree(ROOT / "python-api/arm_yolo26n", api_destination, dirs_exist_ok=True)
     shutil.copy2(
-        ROOT / "ultralytics/arm_yolo26_pi5_backend.py",
-        site / "ultralytics/nn/backends/arm_yolo26_pi5.py",
+        ROOT / "ultralytics/arm_yolo26n_pi5_backend.py",
+        site / "ultralytics/nn/backends/arm_yolo26n_pi5.py",
     )
 
     patch_path = ROOT / "ultralytics/ultralytics-8.4.108-arm-yolo26-pi5.patch"
-    patch_data = patch_path.read_text()
+    patch_data = patch_path.read_text(encoding="utf-8")
     patch_command = ["patch", "--forward", "-p1", "-d", str(site)]
     forward = subprocess.run(
         [*patch_command, "--dry-run"],
@@ -100,8 +111,8 @@ def setup() -> None:
             str(python),
             "-c",
             "import ultralytics; "
-            "from ultralytics.nn.backends import ArmYolo26Pi5Backend; "
-            "from yolo26_runtime import Yolo26nRuntime; "
+            "from arm_yolo26n import Yolo26nTensorSession; "
+            "from ultralytics.nn.backends import ArmYolo26nPi5Backend; "
             "assert ultralytics.__version__ == '8.4.108'",
         ]
     )
@@ -117,81 +128,61 @@ def sha256(path: Path) -> str:
     return digest.hexdigest()
 
 
-def assemble_bundle(exported_dir: Path, reference_bundle: Path, output: Path) -> None:
-    exported_manifest = json.loads((exported_dir / "manifest.json").read_text())
-    reference_manifest = json.loads((reference_bundle / "manifest.json").read_text())
-    if (exported_manifest.get("kind"), exported_manifest.get("version")) != (
-        "yolo26n-exported-model",
-        1,
-    ):
-        raise SystemExit("unsupported exported model")
-
-    exported_artifact = exported_manifest["artifact"]
-    exported_model = exported_dir / exported_artifact["path"]
-    if (
-        not exported_model.is_file()
-        or exported_model.stat().st_size != exported_artifact["bytes"]
-        or sha256(exported_model) != exported_artifact["sha256"]
-    ):
-        raise SystemExit("exported model identity mismatch")
-
-    model_record = dict(exported_manifest["model"])
-    target_record = model_record.pop("target")
-    bundle_manifest = {
-        "version": 1,
-        "kind": "yolo26n-native-bundle",
-        "model": model_record,
-        "target": target_record,
-        "artifacts": {
-            "runtime": reference_manifest["artifacts"]["runtime"],
-            "model": exported_artifact,
-        },
-        "notices": reference_manifest["notices"],
-    }
-
-    output.parent.mkdir(parents=True, exist_ok=True)
-    temporary = Path(tempfile.mkdtemp(prefix=f".{output.name}.", dir=output.parent))
+def ensure_stock_checkpoint() -> Path:
+    if STOCK_CHECKPOINT.is_file() and sha256(STOCK_CHECKPOINT) == STOCK_CHECKPOINT_SHA256:
+        return STOCK_CHECKPOINT
+    STOCK_CHECKPOINT.parent.mkdir(parents=True, exist_ok=True)
+    temporary = STOCK_CHECKPOINT.with_suffix(".pt.download")
     try:
-        bundle = temporary / "bundle"
-        shutil.copytree(reference_bundle, bundle)
-        shutil.copy2(exported_model, bundle / "model.bin")
-        (bundle / "manifest.json").write_text(
-            json.dumps(bundle_manifest, indent=2) + "\n", encoding="utf-8"
-        )
-        os.rename(temporary, output)
-    except BaseException:
-        shutil.rmtree(temporary, ignore_errors=True)
-        raise
+        with urlopen(STOCK_CHECKPOINT_URL) as response, temporary.open("wb") as output:
+            shutil.copyfileobj(response, output)
+        if sha256(temporary) != STOCK_CHECKPOINT_SHA256:
+            raise SystemExit("downloaded stock checkpoint failed SHA-256 verification")
+        temporary.replace(STOCK_CHECKPOINT)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return STOCK_CHECKPOINT
 
 
 def export_model() -> None:
-    exported = ROOT / "build/exported-model"
-    output = ROOT / "build/arm_yolo26n_pi5_model"
-    if exported.exists() or output.exists():
-        raise SystemExit(f"export output already exists under {ROOT / 'build'}")
-
-    environment = os.environ.copy()
-    environment["PYTHONPATH"] = str(ROOT / "compiler")
-    run(
-        [
-            sys.executable,
-            "-m",
-            "minimal_runtime.compiler.export_yolo26n",
-            "--checkpoint",
-            str(ROOT / "model/yolo26n.pt"),
-            "--resolution",
-            "640",
-            "--output-dir",
-            str(exported),
-        ],
-        env=environment,
-    )
-    assemble_bundle(
-        exported,
-        ROOT / "runtime/arm_yolo26n_pi5_model/bundle",
-        output,
-    )
-    print(f"exported runnable model to {output}")
+    python = VENV / "bin/python"
+    checkpoint = ROOT / "model/yolo26n.pt"
+    if not python.is_file():
+        raise SystemExit("run 'python3 repro.py setup' first")
+    if not checkpoint.is_file():
+        raise SystemExit("place a compatible checkpoint at model/yolo26n.pt")
+    if EXPORTED_MODEL.exists():
+        raise SystemExit(f"export output already exists: {EXPORTED_MODEL}")
+
+    build = ROOT / "build"
+    build.mkdir(exist_ok=True)
+    temporary = Path(tempfile.mkdtemp(prefix=".arm-yolo26n-export.", dir=build))
+    try:
+        converted_model = temporary / "model"
+        environment = os.environ.copy()
+        environment["PYTHONPATH"] = str(ROOT / "compiler")
+        run(
+            [
+                str(python),
+                "-m",
+                "converter.export_yolo26n",
+                "--checkpoint",
+                str(checkpoint),
+                "--resolution",
+                "640",
+                "--output-dir",
+                str(converted_model),
+            ],
+            env=environment,
+        )
+        assembled = temporary / EXPORTED_MODEL.name
+        shutil.copytree(SUPPLIED_MODEL, assembled)
+        shutil.rmtree(assembled / "model")
+        shutil.copytree(converted_model, assembled / "model")
+        assembled.rename(EXPORTED_MODEL)
+    finally:
+        shutil.rmtree(temporary, ignore_errors=True)
+    print(f"exported runnable model to {EXPORTED_MODEL}")
 
 
 def read_key_values(path: Path, multiplier: int = 1) -> dict[str, int]:
@@ -267,7 +258,7 @@ def preflight(paths: tuple[Path, ...]) -> None:
 
 
 def ensure_dataset(python: Path) -> Path:
-    dataset_yaml = DATASET_DIR / "data-validation-all.yaml"
+    source_yaml = DATASET_DIR / "data.yaml"
     run(
         [
             str(python),
@@ -279,8 +270,19 @@ def ensure_dataset(python: Path) -> Path:
             % (DATASET_REPO, DATASET_REVISION, str(DATASET_DIR)),
         ]
     )
-    if not dataset_yaml.is_file():
-        raise SystemExit(f"dataset download did not produce {dataset_yaml}")
+    if not source_yaml.is_file():
+        raise SystemExit(f"dataset download did not produce {source_yaml}")
+
+    dataset_yaml = DATASET_DIR / ".benchmark-data.yaml"
+    source_text = source_yaml.read_text(encoding="utf-8")
+    if "path: .\n" not in source_text:
+        raise SystemExit(f"unexpected dataset path in {source_yaml}")
+    dataset_yaml.write_text(
+        source_text.replace(
+            "path: .\n", f"path: {json.dumps(str(DATASET_DIR.resolve()))}\n", 1
+        ),
+        encoding="utf-8",
+    )
     run(["sync", "-f", str(DATASET_DIR)])
     return dataset_yaml.resolve()
 
@@ -289,12 +291,12 @@ def benchmark() -> None:
     python = VENV / "bin/python"
     if not python.is_file():
         raise SystemExit("run 'python3 repro.py setup' first")
-
     dataset_yaml = ensure_dataset(python)
 
-    model = ROOT / "build/arm_yolo26n_pi5_model"
-    if not model.is_dir():
-        model = ROOT / "runtime/arm_yolo26n_pi5_model"
+    model = EXPORTED_MODEL if EXPORTED_MODEL.is_dir() else SUPPLIED_MODEL
+    checkpoint = ROOT / "model/yolo26n.pt" if model == EXPORTED_MODEL else ensure_stock_checkpoint()
+    if not checkpoint.is_file():
+        raise SystemExit("the exported model requires its source checkpoint at model/yolo26n.pt")
     preflight((model.resolve(), DATASET_DIR.resolve()))
 
     governor = Path("/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor")
@@ -308,7 +310,7 @@ def benchmark() -> None:
             str(python),
             str(ROOT / "ultralytics/benchmark.py"),
             "--checkpoint",
-            str(ROOT / "model/yolo26n.pt"),
+            str(checkpoint),
             "--model",
             str(model),
             "--data",

results/REFERENCE.md

@@ -1,14 +1,26 @@
-# Reference result
+# Reference benchmark
 
-Measured from a fresh extraction of this package on Raspberry Pi 5:
+Measured on a Raspberry Pi 5 with Raspberry Pi OS Trixie using the packaged
+workflow:
 
-- Dataset: `Arm/coco-128-by-sa` (128 images)
-- Dataset revision: `cb1edb8da4ff3cb54d40ecb12d3efecc116ff3de`
-- Validation definition: `data-validation-all.yaml`
-- Image size: 640
-- Device and batch: CPU, batch 1
-- CPU governor: `ondemand`
-- mAP50-95: 0.4678
-- Inference: 38.54 ms/image
+```sh
+python3 repro.py setup
+python3 repro.py benchmark
+```
 
-Running the included exporter produced a byte-identical `model.bin`.
+| Metric | Result |
+| --- | ---: |
+| Dataset | `Arm/coco-128-by-sa` (128 images, 1,050 instances) |
+| Input | 640 x 640, batch 1 |
+| mAP50-95 | 0.4866 |
+| Inference time | 39.29 ms/image |
+| Model size | 10.6 MB |
+
+The page-cache preflight reported 7,054 MiB available memory, no dirty or
+writeback data, no refaults or reclaim scans, and no swap activity. The model
+and dataset were on ext4. The CPU governor was `ondemand`, and the device
+reported no throttling (`0x0`).
+
+The export path was also verified with the same stock checkpoint. It reproduced
+the packaged `model.bin` byte-for-byte and completed the benchmark with the same
+0.4866 mAP50-95 result.

runtime/arm_yolo26n_pi5_model/arm-yolo26n-pi5.yaml

@@ -0,0 +1,3 @@
+backend: arm_yolo26n_pi5
+runtime: lib/libarm-yolo26n.so.0.1.0
+model: model

runtime/arm_yolo26n_pi5_model/bundle/licenses/libmd/COPYRIGHT.debian

@@ -1,177 +0,0 @@
-Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-
-Files:
- *
-Copyright:
- Copyright © 2009, 2011, 2016 Guillem Jover <guillem@hadrons.org>
-License: BSD-3-clause
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
- 3. The name of the author may not be used to endorse or promote products
-    derived from this software without specific prior written permission.
- .
- THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
- INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
- THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
- WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
- OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
- ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-Files:
- include/sha2.h
- src/sha2.c
-Copyright:
- Copyright © 2000-2001, Aaron D. Gifford
- All rights reserved.
-License: BSD-3-clause-Aaron-D-Gifford
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
- 3. Neither the name of the copyright holder nor the names of contributors
-    may be used to endorse or promote products derived from this software
-    without specific prior written permission.
- .
- THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTOR(S) ``AS IS'' AND
- ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTOR(S) BE LIABLE
- FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGE.
-
-Files:
- include/rmd160.h
- src/rmd160.c
-Copyright:
- Copyright © 2001 Markus Friedl.  All rights reserved.
-License: BSD-2-clause
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
- .
- THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-Files:
- src/md2.c
-Copyright:
- Copyright (c) 2001 The NetBSD Foundation, Inc.
- All rights reserved.
- .
- This code is derived from software contributed to The NetBSD Foundation
- by Andrew Brown.
-License: BSD-2-clause-NetBSD
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
- .
- THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
- ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
- TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
- BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
-
-Files:
- man/rmd160.3
- man/sha1.3
- man/sha2.3
-Copyright:
- Copyright © 1997, 2003, 2004 Todd C. Miller <Todd.Miller@courtesan.com>
-License: ISC
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
- .
- THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
-Files:
- man/mdX.3
- src/helper.c
-Copyright:
- Poul-Henning Kamp <phk@login.dkuug.dk>
-License: Beerware
- "THE BEER-WARE LICENSE" (Revision 42):
- <phk@login.dkuug.dk> wrote this file.  As long as you retain this notice you
- can do whatever you want with this stuff. If we meet some day, and you think
- this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
-
-Files:
- include/md4.h
- src/md4.c
-Copyright:
- Colin Plumb
- Todd C. Miller
-License: public-domain-md4
- This code implements the MD4 message-digest algorithm.
- The algorithm is due to Ron Rivest.  This code was
- written by Colin Plumb in 1993, no copyright is claimed.
- This code is in the public domain; do with it what you wish.
- Todd C. Miller modified the MD5 code to do MD4 based on RFC 1186.
-
-Files:
- include/md5.h
- src/md5.c
-Copyright:
- Colin Plumb
-License: public-domain-md5
- This code implements the MD5 message-digest algorithm.
- The algorithm is due to Ron Rivest.  This code was
- written by Colin Plumb in 1993, no copyright is claimed.
- This code is in the public domain; do with it what you wish.
-
-Files:
- include/sha1.h
- src/sha1.c
-Copyright:
- Steve Reid <steve@edmweb.com>
-License: public-domain-sha1
- 100% Public Domain

runtime/arm_yolo26n_pi5_model/bundle/manifest.json

@@ -1,104 +0,0 @@
-{
-  "version": 1,
-  "kind": "yolo26n-native-bundle",
-  "model": {
-    "checkpoint_sha256": "9b09cc8bf347f0fc8a5f7657480587f25db09b34bf33b0652110fb03a8ad4fef",
-    "class_names": [
-  "person",
-  "bicycle",
-  "car",
-  "motorcycle",
-  "airplane",
-  "bus",
-  "train",
-  "truck",
-  "boat",
-  "traffic light",
-  "fire hydrant",
-  "stop sign",
-  "parking meter",
-  "bench",
-  "bird",
-  "cat",
-  "dog",
-  "horse",
-  "sheep",
-  "cow",
-  "elephant",
-  "bear",
-  "zebra",
-  "giraffe",
-  "backpack",
-  "umbrella",
-  "handbag",
-  "tie",
-  "suitcase",
-  "frisbee",
-  "skis",
-  "snowboard",
-  "sports ball",
-  "kite",
-  "baseball bat",
-  "baseball glove",
-  "skateboard",
-  "surfboard",
-  "tennis racket",
-  "bottle",
-  "wine glass",
-  "cup",
-  "fork",
-  "knife",
-  "spoon",
-  "bowl",
-  "banana",
-  "apple",
-  "sandwich",
-  "orange",
-  "broccoli",
-  "carrot",
-  "hot dog",
-  "pizza",
-  "donut",
-  "cake",
-  "chair",
-  "couch",
-  "potted plant",
-  "bed",
-  "dining table",
-  "toilet",
-  "tv",
-  "laptop",
-  "mouse",
-  "remote",
-  "keyboard",
-  "cell phone",
-  "microwave",
-  "oven",
-  "toaster",
-  "sink",
-  "refrigerator",
-  "book",
-  "clock",
-  "vase",
-  "scissors",
-  "teddy bear",
-  "hair drier",
-  "toothbrush"
-],
-    "input_shape": [ 1, 3, 640, 640 ],
-    "output_shape": [ 1, 84, 8400 ]
-  },
-  "target": {
-  "input_dtype" : "fp32",
-  "input_shape" : [ 1, 3, 640, 640 ],
-  "output_dtype" : "fp32",
-  "target" : "linux-aarch64-raspberry-pi-5",
-  "thread_count" : 4,
-  "version" : 1
-},
-  "artifacts": {
-    "runtime": {"path":"native-runtime.so","bytes":1398048,"sha256":"8e48d898de082780b6ebadaffda0e04cb942a80be5911a2621651b30f7bd453b"},
-    "model": {"path":"model.bin","bytes":9650112,"sha256":"8d5a617332cdd1bab070f6d60a02e4cb1cd00a5da10381469d2cd613988f895b"}
-  },
-  "notices": [{"path":"licenses/cpuinfo/LICENSE","bytes":1424,"sha256":"8e7e60636c3aa0cb03571a1a841ce5697f9551ff92b3c426c2561613d15ade70"},{"path":"licenses/fxdiv/LICENSE","bytes":1117,"sha256":"2c511c2ad0f207cefa6d8c1a20a5b6fa1d12c15db96031a608e5bad92ae4053d"},{"path":"licenses/libmd/COPYRIGHT.debian","bytes":8018,"sha256":"4365ef6255ad553fce69dd4bc0e093472c5d0e41b8ea493a545cc926ce171aa6"},{"path":"licenses/pthreadpool/LICENSE","bytes":1377,"sha256":"955604be43dc2c71940b5285e59ba60bd5132953ada8ca2292042817349d9399"},{"path":"licenses/xnnpack/LICENSE","bytes":1560,"sha256":"63f519e15726f4c4f830bd958f694c84fecb4e0a4cacc527d2696bb71ef95ada"}]
-}

runtime/arm_yolo26n_pi5_model/{bundle/native-runtime.so → lib/libarm-yolo26n.so.0.1.0}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:8e48d898de082780b6ebadaffda0e04cb942a80be5911a2621651b30f7bd453b
-size 1398048
+oid sha256:6b9978243ed1fd325e5b7b6a2bc616280862ed01edc1f653ee55b088658b60b2
+size 1421264

runtime/arm_yolo26n_pi5_model/model/manifest.json

@@ -0,0 +1 @@
+{"artifact":{"bytes":9640064,"path":"model.bin","sha256":"031991352d4c1bcca4ad5b6f7023b6e3d66bdf896b476c66b851b1a29c5bdaff"},"kind":"yolo26n-exported-model","model":{"checkpoint_sha256":"9b09cc8bf347f0fc8a5f7657480587f25db09b34bf33b0652110fb03a8ad4fef","class_names":["person","bicycle","car","motorcycle","airplane","bus","train","truck","boat","traffic light","fire hydrant","stop sign","parking meter","bench","bird","cat","dog","horse","sheep","cow","elephant","bear","zebra","giraffe","backpack","umbrella","handbag","tie","suitcase","frisbee","skis","snowboard","sports ball","kite","baseball bat","baseball glove","skateboard","surfboard","tennis racket","bottle","wine glass","cup","fork","knife","spoon","bowl","banana","apple","sandwich","orange","broccoli","carrot","hot dog","pizza","donut","cake","chair","couch","potted plant","bed","dining table","toilet","tv","laptop","mouse","remote","keyboard","cell phone","microwave","oven","toaster","sink","refrigerator","book","clock","vase","scissors","teddy bear","hair drier","toothbrush"],"input_shape":[1,3,640,640],"output_shape":[1,84,8400],"target":{"input_dtype":"fp32","input_shape":[1,3,640,640],"output_dtype":"fp32","target":"linux-aarch64-raspberry-pi-5","thread_count":4,"version":1}},"version":1}

runtime/arm_yolo26n_pi5_model/{bundle → model}/model.bin

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:8d5a617332cdd1bab070f6d60a02e4cb1cd00a5da10381469d2cd613988f895b
-size 9650112
+oid sha256:031991352d4c1bcca4ad5b6f7023b6e3d66bdf896b476c66b851b1a29c5bdaff
+size 9640064

ultralytics/arm_yolo26_pi5_backend.py

@@ -1,51 +0,0 @@
-"""Ultralytics backend for the native YOLO26n Raspberry Pi 5 runtime."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import torch
-from ultralytics.nn.backends.base import BaseBackend
-from ultralytics.utils import LOGGER
-from yolo26_runtime import Yolo26nRuntime
-
-_YOLO26N_SUFFIX = "arm_yolo26n_pi5_model"
-
-
-class ArmYolo26Pi5Backend(BaseBackend):
-    """Run a YOLO26n package through its native runtime."""
-
-    def load_model(self, weight: str | Path) -> None:
-        model_directory = Path(weight).expanduser().resolve()
-        if not model_directory.is_dir():
-            raise ValueError(
-                f"Arm YOLO26 Pi 5 model must be a package directory: {model_directory}"
-            )
-        if not model_directory.name.endswith(_YOLO26N_SUFFIX):
-            raise ValueError(
-                "YOLO26n Pi 5 model directory must end with "
-                f"{_YOLO26N_SUFFIX}: {model_directory}"
-            )
-        self._load_yolo26n(model_directory)
-
-    def _load_yolo26n(self, model_directory: Path) -> None:
-        bundle_path = model_directory / "bundle"
-        LOGGER.info(f"Loading {model_directory} with ArmYolo26Pi5Backend...")
-        self.model = Yolo26nRuntime(bundle_path)
-        height, width = self.model.input_shape[2:]
-        self.apply_metadata(
-            {
-                "task": "detect",
-                "stride": 32,
-                "batch": 1,
-                "imgsz": [height, width],
-                "names": dict(enumerate(self.model.class_names)),
-            }
-        )
-
-    def forward(self, im: torch.Tensor) -> list[torch.Tensor]:
-        return [self.model.execute(im)]
-
-    def close(self) -> None:
-        if self.model is not None:
-            self.model.close()

ultralytics/arm_yolo26n_pi5_backend.py

@@ -0,0 +1,81 @@
+"""Ultralytics backend for the Arm-optimized YOLO26n Raspberry Pi 5 runtime."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+import torch
+from arm_yolo26n import Yolo26nTensorSession
+from ultralytics.nn.backends.base import BaseBackend
+from ultralytics.utils import LOGGER, YAML
+
+_YOLO26N_SUFFIX = "arm_yolo26n_pi5_model"
+
+
+class ArmYolo26nPi5Backend(BaseBackend):
+    """Run a converted YOLO26n model through the native tensor session."""
+
+    def load_model(self, weight: str | Path) -> None:
+        model_directory = Path(weight).expanduser().resolve()
+        if not model_directory.is_dir():
+            raise ValueError(f"Arm YOLO26n Pi 5 model must be a directory: {model_directory}")
+        if not model_directory.name.endswith(_YOLO26N_SUFFIX):
+            raise ValueError(
+                f"Arm YOLO26n Pi 5 model directory must end with {_YOLO26N_SUFFIX}: "
+                f"{model_directory}"
+            )
+        self._load_yolo26n(model_directory)
+
+    @staticmethod
+    def _descriptor(model_directory: Path, filename: str) -> tuple[Path, Mapping[str, object]]:
+        descriptor_path = model_directory / filename
+        if not descriptor_path.is_file():
+            raise FileNotFoundError(f"missing model descriptor: {descriptor_path}")
+        descriptor = YAML.load(descriptor_path)
+        if not isinstance(descriptor, Mapping):
+            raise ValueError(f"model descriptor must be a mapping: {descriptor_path}")
+        return descriptor_path, descriptor
+
+    def _load_yolo26n(self, model_directory: Path) -> None:
+        descriptor_path, descriptor = self._descriptor(model_directory, "arm-yolo26n-pi5.yaml")
+        if descriptor.get("backend") != "arm_yolo26n_pi5" or set(descriptor) != {
+            "backend",
+            "model",
+            "runtime",
+        }:
+            raise ValueError(f"invalid YOLO26n runtime descriptor: {descriptor_path}")
+        model_path = _descriptor_path(model_directory, descriptor.get("model"), "model")
+        runtime_path = _descriptor_path(model_directory, descriptor.get("runtime"), "runtime")
+        LOGGER.info(f"Loading {model_directory} with ArmYolo26nPi5Backend...")
+        self.model = Yolo26nTensorSession(runtime=runtime_path, model=model_path)
+        height, width = self.model.input_shape[2:]
+        self.apply_metadata(
+            {
+                "task": "detect",
+                "stride": 32,
+                "batch": 1,
+                "imgsz": [height, width],
+                "names": dict(enumerate(self.model.class_names)),
+            }
+        )
+
+    def forward(self, im: torch.Tensor) -> list[torch.Tensor]:
+        if im.device.type != "cpu":
+            raise ValueError("ArmYolo26nPi5Backend requires a CPU input tensor")
+        if im.dtype is not torch.float32:
+            raise TypeError("ArmYolo26nPi5Backend requires an FP32 input tensor")
+        model_input = im.detach().numpy()
+        prediction = self.model.execute(model_input)
+        return [torch.from_numpy(prediction)]
+
+    def close(self) -> None:
+        if self.model is not None:
+            self.model.close()
+
+
+def _descriptor_path(directory: Path, value: object, name: str) -> Path:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"YOLO26n descriptor {name} must be a non-empty path")
+    path = Path(value).expanduser()
+    return path.resolve() if path.is_absolute() else (directory / path).resolve()

ultralytics/benchmark.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Run Ultralytics benchmark() against the native YOLO26n model package."""
+"""Run Ultralytics benchmark() against the Arm YOLO26n model directory."""
 
 from __future__ import annotations
 
@@ -18,15 +18,15 @@ MODEL_SUFFIX = "arm_yolo26n_pi5_model"
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description=(
-            "Inject the native model package at Ultralytics benchmark()'s export step, "
-            "then run its unmodified prediction, validation, timing, and reporting path."
+            "Inject the converted Arm model at Ultralytics benchmark()'s export "
+            "step, then run its normal prediction, validation, timing, and reporting path."
         )
     )
-    parser.add_argument("--checkpoint", type=Path, required=True, help="Source YOLO26n .pt checkpoint")
-    parser.add_argument("--model", type=Path, required=True, help="Native model package directory")
-    parser.add_argument("--data", default="coco128.yaml", help="Ultralytics validation dataset")
-    parser.add_argument("--imgsz", type=int, default=640, help="Square validation image size")
-    parser.add_argument("--device", default="cpu", help="Ultralytics validation device")
+    parser.add_argument("--checkpoint", type=Path, required=True)
+    parser.add_argument("--model", type=Path, required=True)
+    parser.add_argument("--data", default="coco128.yaml")
+    parser.add_argument("--imgsz", type=int, default=640)
+    parser.add_argument("--device", default="cpu")
     parser.add_argument("--output-dir", type=Path, default=Path("results"))
     return parser.parse_args()
 
@@ -45,13 +45,17 @@ def validate_inputs(checkpoint: Path, model: Path) -> None:
     if not model.is_dir() or model.name != MODEL_SUFFIX:
         raise ValueError(f"model must be a directory named {MODEL_SUFFIX}: {model}")
 
-    manifest_path = model / "bundle" / "manifest.json"
+    descriptor = model / "arm-yolo26n-pi5.yaml"
+    runtime = model / "lib/libarm-yolo26n.so.0.1.0"
+    manifest_path = model / "model/manifest.json"
+    if not descriptor.is_file() or not runtime.is_file() or not manifest_path.is_file():
+        raise FileNotFoundError(f"incomplete Arm YOLO26n model directory: {model}")
     manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
     expected = manifest["model"]["checkpoint_sha256"]
     actual = sha256(checkpoint)
     if actual != expected:
         raise ValueError(
-            "checkpoint does not match the weights used to build the native package: "
+            "checkpoint does not match the converted model: "
             f"expected {expected}, got {actual}"
         )
 
@@ -71,7 +75,8 @@ def main() -> None:
     registered = dict(zip(formats["Argument"], formats["Suffix"]))
     if registered.get(NATIVE_FORMAT) != MODEL_SUFFIX:
         raise RuntimeError(
-            f"installed Ultralytics does not register {NATIVE_FORMAT!r} with suffix {MODEL_SUFFIX!r}"
+            f"installed Ultralytics does not register {NATIVE_FORMAT!r} "
+            f"with suffix {MODEL_SUFFIX!r}"
         )
 
     def use_native_model(_self: YOLO, **kwargs: object) -> str:

ultralytics/ultralytics-8.4.108-arm-yolo26-pi5.patch

@@ -1,13 +1,13 @@
 --- a/ultralytics/nn/backends/__init__.py
 +++ b/ultralytics/nn/backends/__init__.py
 @@ -9,3 +9,4 @@
-+from .arm_yolo26_pi5 import ArmYolo26Pi5Backend
++from .arm_yolo26n_pi5 import ArmYolo26nPi5Backend
  from .ascend import AscendBackend
  from .axelera import AxeleraBackend
  from .base import BaseBackend
 @@ -28,4 +29,5 @@
  __all__ = [
-+    "ArmYolo26Pi5Backend",
++    "ArmYolo26nPi5Backend",
      "AscendBackend",
      "AxeleraBackend",
      "BaseBackend",
@@ -15,13 +15,13 @@
 +++ b/ultralytics/nn/autobackend.py
 @@ -5,4 +5,5 @@
  from .backends import (
-+    ArmYolo26Pi5Backend,
++    ArmYolo26nPi5Backend,
      AscendBackend,
      AxeleraBackend,
      CoreMLBackend,
 @@ -145,4 +146,5 @@
      _BACKEND_MAP = {
-+        "arm_yolo26n_pi5": ArmYolo26Pi5Backend,
++        "arm_yolo26n_pi5": ArmYolo26nPi5Backend,
          "pt": PyTorchBackend,
          "torchscript": TorchScriptBackend,
          "onnx": ONNXBackend,