inference-artifact-lab 0.1.0.dev0__tar.gz

inference_artifact_lab-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ray Carter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

inference_artifact_lab-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: inference-artifact-lab
+Version: 0.1.0.dev0
+Summary: Reproducible validation gates for machine-learning inference artifacts
+Author: Ray Carter
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Provides-Extra: runtime-cpu
+Requires-Dist: numpy>=1.26; extra == "runtime-cpu"
+Requires-Dist: onnxruntime==1.30.0; extra == "runtime-cpu"
+Dynamic: license-file
+
+# Inference Artifact Lab
+
+Inference Artifact Lab is a clean-room, public-by-design project for validating
+machine-learning deployment artifacts before release. Its first product increment
+is the **Model Release Gate**: a reproducible gate for artifact integrity,
+input/output contracts, runtime correctness, and environment compatibility.
+
+The project uses public models, public datasets, and generated fixtures. It does
+not train models, provide a general model-serving gateway, or claim model quality
+beyond the declared validation evidence.
+
+## Current status
+
+Development preview: public SqueezeNet CPU and TensorRT smoke runs are recorded.
+Phase 1 acceptance remains incomplete; report delivery and clean reproduction
+need further work. See [publication review](docs/publication-review.md) for
+known limitations. The commands below are development examples, not a verified
+from-scratch reproduction procedure.
+
+## Planned flow
+
+```text
+public model
+  -> source and artifact manifest
+  -> export/build
+  -> integrity and contract checks
+  -> reference/runtime equivalence checks
+  -> environment compatibility checks
+  -> resource benchmark
+  -> machine-readable release report
+```
+
+Run the public-reference smoke gate with:
+
+```text
+uv run --with torch --with torchvision --with onnx --with onnxruntime python scripts/run_torchvision_gate.py
+```
+
+It writes `reports/phase-1/squeezenet11-torchvision-onnx-cpu.json`.
+
+Build and verify the TensorRT profile after pulling the pinned public image:
+
+```text
+pwsh scripts/build_tensorrt_engine.ps1
+pwsh scripts/benchmark_tensorrt_engine.ps1
+docker run --rm --gpus all -v "${PWD}:/workspace" -w /workspace `
+  -e MODEL_RELEASE_GATE_CONTAINER_DIGEST=sha256:814325e2b8a653f354c30bbcf5ecc8d4c780cf878a88a320ae648fbfdd9dd82d `
+  nvcr.io/nvidia/tensorrt:25.02-py3 bash -lc `
+  "python -m pip install --quiet --index-url https://pypi.org/simple cuda-python==12.8.0; `
+   PYTHONPATH=/workspace/src python scripts/run_tensorrt_in_container.py `
+   --engine artifacts/squeezenet1.1-fp32.engine `
+   --fixture artifacts/squeezenet11-fixture.npy `
+   --output artifacts/squeezenet11-tensorrt-output.json"
+uv run --with numpy==2.4.6 python scripts/compose_tensorrt_report.py `
+  --trtexec-log reports/phase-1/tensorrt-trtexec-benchmark.log
+```
+
+The generated TensorRT report includes the contract, engine digest, fixture
+equivalence, declared GPU/container fingerprint, and `trtexec` benchmark scope.
+
+Render any JSON report for review with:
+
+```text
+uv run python scripts/render_report.py reports/phase-1/squeezenet11-tensorrt.json
+```
+
+The report contract is defined by
+`schemas/release-report.schema.json`. A clean CPU reproduction starts with
+`pwsh scripts/clean_reproduction.ps1` in a fresh checkout.
+
+After generating the public fixture and reference output, the package CLI can
+execute the ONNX CPU adapter directly:
+
+```text
+python -m inference_artifact_lab examples/squeezenet11-torchvision.manifest.json `
+  --runtime onnx-cpu --inputs-npy artifacts/squeezenet11-fixture.npy `
+  --reference-output reference-output.json --environment environment.json `
+  --report reports/phase-1/cli-onnx-cpu.json
+```
+
+The authoritative development documentation follows the same phase/stage model
+used by the other portfolio repositories. Start at the [Codex document index](docs/codex/README.md), then read the [product contract](docs/codex/product-contract.md) and [Phase 1 plan](docs/codex/phases/phase-1-model-release-gate/README.md).
+
+For the human-readable brief and clean-room record, see [Product Requirements](docs/product-requirements.md), [Acceptance Contract](docs/acceptance-contract.md), and [Clean-room Record](docs/clean-room-record.md).

inference_artifact_lab-0.1.0.dev0/README.md

@@ -0,0 +1,84 @@
+# Inference Artifact Lab
+
+Inference Artifact Lab is a clean-room, public-by-design project for validating
+machine-learning deployment artifacts before release. Its first product increment
+is the **Model Release Gate**: a reproducible gate for artifact integrity,
+input/output contracts, runtime correctness, and environment compatibility.
+
+The project uses public models, public datasets, and generated fixtures. It does
+not train models, provide a general model-serving gateway, or claim model quality
+beyond the declared validation evidence.
+
+## Current status
+
+Development preview: public SqueezeNet CPU and TensorRT smoke runs are recorded.
+Phase 1 acceptance remains incomplete; report delivery and clean reproduction
+need further work. See [publication review](docs/publication-review.md) for
+known limitations. The commands below are development examples, not a verified
+from-scratch reproduction procedure.
+
+## Planned flow
+
+```text
+public model
+  -> source and artifact manifest
+  -> export/build
+  -> integrity and contract checks
+  -> reference/runtime equivalence checks
+  -> environment compatibility checks
+  -> resource benchmark
+  -> machine-readable release report
+```
+
+Run the public-reference smoke gate with:
+
+```text
+uv run --with torch --with torchvision --with onnx --with onnxruntime python scripts/run_torchvision_gate.py
+```
+
+It writes `reports/phase-1/squeezenet11-torchvision-onnx-cpu.json`.
+
+Build and verify the TensorRT profile after pulling the pinned public image:
+
+```text
+pwsh scripts/build_tensorrt_engine.ps1
+pwsh scripts/benchmark_tensorrt_engine.ps1
+docker run --rm --gpus all -v "${PWD}:/workspace" -w /workspace `
+  -e MODEL_RELEASE_GATE_CONTAINER_DIGEST=sha256:814325e2b8a653f354c30bbcf5ecc8d4c780cf878a88a320ae648fbfdd9dd82d `
+  nvcr.io/nvidia/tensorrt:25.02-py3 bash -lc `
+  "python -m pip install --quiet --index-url https://pypi.org/simple cuda-python==12.8.0; `
+   PYTHONPATH=/workspace/src python scripts/run_tensorrt_in_container.py `
+   --engine artifacts/squeezenet1.1-fp32.engine `
+   --fixture artifacts/squeezenet11-fixture.npy `
+   --output artifacts/squeezenet11-tensorrt-output.json"
+uv run --with numpy==2.4.6 python scripts/compose_tensorrt_report.py `
+  --trtexec-log reports/phase-1/tensorrt-trtexec-benchmark.log
+```
+
+The generated TensorRT report includes the contract, engine digest, fixture
+equivalence, declared GPU/container fingerprint, and `trtexec` benchmark scope.
+
+Render any JSON report for review with:
+
+```text
+uv run python scripts/render_report.py reports/phase-1/squeezenet11-tensorrt.json
+```
+
+The report contract is defined by
+`schemas/release-report.schema.json`. A clean CPU reproduction starts with
+`pwsh scripts/clean_reproduction.ps1` in a fresh checkout.
+
+After generating the public fixture and reference output, the package CLI can
+execute the ONNX CPU adapter directly:
+
+```text
+python -m inference_artifact_lab examples/squeezenet11-torchvision.manifest.json `
+  --runtime onnx-cpu --inputs-npy artifacts/squeezenet11-fixture.npy `
+  --reference-output reference-output.json --environment environment.json `
+  --report reports/phase-1/cli-onnx-cpu.json
+```
+
+The authoritative development documentation follows the same phase/stage model
+used by the other portfolio repositories. Start at the [Codex document index](docs/codex/README.md), then read the [product contract](docs/codex/product-contract.md) and [Phase 1 plan](docs/codex/phases/phase-1-model-release-gate/README.md).
+
+For the human-readable brief and clean-room record, see [Product Requirements](docs/product-requirements.md), [Acceptance Contract](docs/acceptance-contract.md), and [Clean-room Record](docs/clean-room-record.md).

inference_artifact_lab-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "inference-artifact-lab"
+version = "0.1.0.dev0"
+description = "Reproducible validation gates for machine-learning inference artifacts"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "Ray Carter"}]
+dependencies = []
+
+[project.scripts]
+model-release-gate = "inference_artifact_lab.__main__:main"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+runtime-cpu = ["numpy>=1.26", "onnxruntime==1.30.0"]
+
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

inference_artifact_lab-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

inference_artifact_lab-0.1.0.dev0/src/inference_artifact_lab/__init__.py

@@ -0,0 +1,14 @@
+"""Inference Artifact Lab package."""
+
+from .gate import canonical_manifest_digest, current_environment, load_manifest, run_gate, run_gate_from_file, sha256_file
+from .adapters import OnnxRuntimeAdapter, RuntimeUnavailable, TensorRTAdapter
+from .models import ArtifactSpec, CheckResult, GateReport, GateStatus, Manifest, ManifestError, TensorSpec
+from .release import run_release_gate
+from .runtime import BenchmarkResult, benchmark, compare_outputs
+
+__all__ = [
+    "__version__", "ArtifactSpec", "CheckResult", "GateReport", "GateStatus", "Manifest", "ManifestError", "TensorSpec",
+    "canonical_manifest_digest", "current_environment", "load_manifest", "run_gate", "run_gate_from_file", "run_release_gate", "sha256_file",
+    "BenchmarkResult", "benchmark", "compare_outputs", "OnnxRuntimeAdapter", "TensorRTAdapter", "RuntimeUnavailable",
+]
+__version__ = "0.1.0.dev0"

inference_artifact_lab-0.1.0.dev0/src/inference_artifact_lab/__main__.py

@@ -0,0 +1,85 @@
+"""Command line entry point: ``python -m inference_artifact_lab``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .gate import run_gate_from_file
+from .release import run_release_gate
+from .runtime import benchmark
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run core Model Release Gate checks")
+    parser.add_argument("manifest", help="path to a JSON manifest")
+    parser.add_argument("--artifact", help="artifact path (defaults to manifest artifact.path)")
+    parser.add_argument("--observed-contract", help="JSON file containing observed inputs and outputs")
+    parser.add_argument("--environment", help="JSON file containing the observed environment fingerprint")
+    parser.add_argument("--reference-output", help="JSON file containing reference runtime output")
+    parser.add_argument("--target-output", help="JSON file containing target runtime output")
+    parser.add_argument("--benchmark-evidence", help="JSON file containing benchmark evidence")
+    parser.add_argument("--report", help="write the release report JSON to this path")
+    parser.add_argument("--runtime", choices=["onnx-cpu"], help="run a real package adapter before composing the release report")
+    parser.add_argument("--inputs-npy", help="NumPy .npy input for the selected runtime adapter")
+    args = parser.parse_args(argv)
+    observed = None
+    if args.observed_contract:
+        with open(args.observed_contract, encoding="utf-8") as handle:
+            observed = json.load(handle)
+    environment = None
+    if args.environment:
+        with open(args.environment, encoding="utf-8") as handle:
+            environment = json.load(handle)
+    def load_json(path: str | None):
+        if not path:
+            return None
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle)
+    try:
+        reference = load_json(args.reference_output)
+        target = load_json(args.target_output)
+        benchmark_evidence = load_json(args.benchmark_evidence)
+        if args.runtime:
+            if not args.inputs_npy or reference is None or environment is None:
+                raise ValueError("--runtime requires --inputs-npy, --reference-output, and --environment")
+            if args.runtime != "onnx-cpu":  # argparse currently prevents this; retain an explicit guard.
+                raise ValueError(f"unsupported runtime {args.runtime}")
+            import numpy as np
+            from .adapters import OnnxRuntimeAdapter
+            from .gate import load_manifest
+            manifest = load_manifest(args.manifest)
+            manifest_file = Path(args.manifest)
+            artifact = Path(args.artifact) if args.artifact else Path(manifest.artifact.path)
+            if not artifact.is_absolute():
+                artifact = Path(os.path.normpath(str(manifest_file.parent / artifact)))
+            values = np.load(args.inputs_npy, allow_pickle=False)
+            adapter = OnnxRuntimeAdapter(artifact, providers=["CPUExecutionProvider"])
+            output_name = adapter.contract()["outputs"][0]["name"]
+            input_name = adapter.contract()["inputs"][0]["name"]
+            target = adapter.run({input_name: values})[output_name]
+            reference_value = reference.get(output_name) if isinstance(reference, dict) else reference
+            measured = benchmark(lambda: adapter.run({input_name: values}), warmup_runs=1, measured_runs=5)
+            report = run_release_gate(manifest, artifact, observed_contract=adapter.contract(), observed_environment=environment, reference_outputs=reference_value, target_outputs=target, benchmark_evidence=measured.to_dict())
+        elif reference is not None or target is not None or benchmark_evidence is not None:
+            from .gate import load_manifest
+            manifest = load_manifest(args.manifest)
+            report = run_release_gate(manifest, args.artifact, observed_contract=observed, observed_environment=environment, reference_outputs=reference, target_outputs=target, benchmark_evidence=benchmark_evidence)
+        else:
+            report = run_gate_from_file(args.manifest, args.artifact, observed_contract=observed, observed_environment=environment)
+    except (OSError, ValueError) as exc:
+        print(json.dumps({"status": "fail", "error": str(exc)}), file=sys.stdout)
+        return 2
+    rendered = json.dumps(report.to_dict(), indent=2, sort_keys=True)
+    if args.report:
+        with open(args.report, "w", encoding="utf-8") as handle:
+            handle.write(rendered + "\n")
+    print(rendered)
+    return 0 if report.status.value == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inference_artifact_lab-0.1.0.dev0/src/inference_artifact_lab/adapters.py

@@ -0,0 +1,296 @@
+"""Optional runtime adapters used by the Phase 1 evidence harness."""
+
+from __future__ import annotations
+
+import ctypes
+import platform
+from pathlib import Path
+from typing import Any, Mapping
+
+
+class RuntimeUnavailable(RuntimeError):
+    """Raised when a declared runtime dependency is not installed."""
+
+
+class OnnxRuntimeAdapter:
+    """Small ONNX Runtime adapter with no dependency on the gate domain."""
+
+    def __init__(self, artifact: str | Path, *, providers: list[str] | None = None) -> None:
+        try:
+            import onnxruntime as ort
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeUnavailable("install the runtime-cpu extra for ONNX Runtime") from exc
+        self._session = ort.InferenceSession(str(artifact), providers=providers)
+        self._ort_version = ort.__version__
+        self._requested_providers = tuple(providers) if providers is not None else None
+
+    def contract(self) -> dict[str, list[dict[str, Any]]]:
+        def describe(value: Any) -> dict[str, Any]:
+            return {"name": value.name, "dtype": value.type, "shape": list(value.shape)}
+
+        return {
+            "artifact_format": "onnx",
+            "inputs": [describe(value) for value in self._session.get_inputs()],
+            "outputs": [describe(value) for value in self._session.get_outputs()],
+        }
+
+    def runtime_info(self) -> dict[str, Any]:
+        """Return selected providers, including an explicit fallback provider."""
+
+        return {
+            "runtime": "onnxruntime",
+            "version": self._ort_version,
+            "requested_providers": list(self._requested_providers) if self._requested_providers is not None else None,
+            "providers": list(self._session.get_providers()),
+            "python": platform.python_version(),
+            "system": platform.system(),
+            "machine": platform.machine(),
+        }
+
+    def run(self, inputs: Mapping[str, Any]) -> dict[str, Any]:
+        values = self._session.run(None, dict(inputs))
+        return {
+            spec["name"]: value.tolist() if hasattr(value, "tolist") else value
+            for spec, value in zip(self.contract()["outputs"], values)
+        }
+
+
+class _CtypesCudaRuntime:
+    """Minimal libcudart binding used when the optional cuda-python is absent."""
+
+    binding_name = "ctypes-libcudart"
+
+    class _MemcpyKind:
+        cudaMemcpyHostToDevice = 1
+        cudaMemcpyDeviceToHost = 2
+
+    cudaMemcpyKind = _MemcpyKind
+
+    def __init__(self) -> None:
+        last_error: OSError | None = None
+        for name in ("libcudart.so", "libcudart.so.12", "cudart64_*.dll"):
+            try:
+                self._lib = ctypes.CDLL(name)
+                break
+            except OSError as exc:
+                last_error = exc
+        else:
+            raise RuntimeUnavailable("TensorRTAdapter requires libcudart or cuda-python") from last_error
+        self._configure()
+
+    def _configure(self) -> None:
+        ptr, size = ctypes.c_void_p, ctypes.c_size_t
+        self._lib.cudaStreamCreate.argtypes = [ctypes.POINTER(ptr)]
+        self._lib.cudaStreamCreate.restype = ctypes.c_int
+        self._lib.cudaStreamDestroy.argtypes = [ptr]
+        self._lib.cudaStreamDestroy.restype = ctypes.c_int
+        self._lib.cudaStreamSynchronize.argtypes = [ptr]
+        self._lib.cudaStreamSynchronize.restype = ctypes.c_int
+        self._lib.cudaMalloc.argtypes = [ctypes.POINTER(ptr), size]
+        self._lib.cudaMalloc.restype = ctypes.c_int
+        self._lib.cudaFree.argtypes = [ptr]
+        self._lib.cudaFree.restype = ctypes.c_int
+        self._lib.cudaMemcpyAsync.argtypes = [ptr, ptr, size, ctypes.c_int, ptr]
+        self._lib.cudaMemcpyAsync.restype = ctypes.c_int
+
+    def cudaStreamCreate(self) -> tuple[int, int | None]:
+        value = ctypes.c_void_p()
+        return self._lib.cudaStreamCreate(ctypes.byref(value)), value.value
+
+    def cudaStreamDestroy(self, stream: int | None) -> int:
+        return self._lib.cudaStreamDestroy(ctypes.c_void_p(stream))
+
+    def cudaStreamSynchronize(self, stream: int | None) -> int:
+        return self._lib.cudaStreamSynchronize(ctypes.c_void_p(stream))
+
+    def cudaMalloc(self, size: int) -> tuple[int, int | None]:
+        value = ctypes.c_void_p()
+        return self._lib.cudaMalloc(ctypes.byref(value), ctypes.c_size_t(size)), value.value
+
+    def cudaFree(self, device: int | None) -> int:
+        return self._lib.cudaFree(ctypes.c_void_p(device))
+
+    def cudaMemcpyAsync(self, destination: int, source: int, size: int, kind: int, stream: int | None) -> int:
+        return self._lib.cudaMemcpyAsync(ctypes.c_void_p(destination), ctypes.c_void_p(source), ctypes.c_size_t(size), int(kind), ctypes.c_void_p(stream))
+
+
+def _load_cuda_runtime() -> Any:
+    try:
+        from cuda import cudart  # type: ignore[import-not-found]
+    except ImportError:
+        return _CtypesCudaRuntime()
+    # Kept as evidence in runtime_info; provider selection is never implicit.
+    try:
+        cudart.binding_name = "cuda-python"  # type: ignore[attr-defined]
+    except AttributeError:
+        pass
+    return cudart
+
+
+def _status_is_success(status: Any) -> bool:
+    value = getattr(status, "value", status)
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value == 0
+    name = str(getattr(status, "name", status)).lower()
+    return name in {"success", "cudasuccess", "cuda_success"}
+
+
+def _check_cuda(result: Any, operation: str) -> Any:
+    """Check cuda-python/libcudart status and return an optional payload."""
+
+    if isinstance(result, tuple):
+        status, payload = result[0], result[1] if len(result) > 1 else None
+    else:
+        status, payload = result, None
+    if not _status_is_success(status):
+        raise RuntimeError(f"{operation} failed with CUDA status {status!r}")
+    return payload
+
+
+class TensorRTAdapter:
+    """TensorRT engine adapter with explicit CUDA ownership and validation."""
+
+    def __init__(self, artifact: str | Path, *, trt_module: Any | None = None, cuda_runtime: Any | None = None, numpy_module: Any | None = None) -> None:
+        try:
+            trt = trt_module or __import__("tensorrt")
+            np = numpy_module or __import__("numpy")
+        except ImportError as exc:  # pragma: no cover - optional container dependency
+            raise RuntimeUnavailable("TensorRTAdapter requires the pinned NVIDIA TensorRT container") from exc
+        self._trt, self._np = trt, np
+        self._cuda = cuda_runtime or _load_cuda_runtime()
+        self._logger = trt.Logger(trt.Logger.ERROR)
+        with Path(artifact).open("rb") as handle:
+            self._runtime = trt.Runtime(self._logger)
+            self._engine = self._runtime.deserialize_cuda_engine(handle.read())
+        if self._engine is None:
+            raise RuntimeError("TensorRT engine deserialization failed")
+        self._context = self._engine.create_execution_context()
+        if self._context is None:
+            raise RuntimeError("TensorRT execution context creation failed")
+
+    @staticmethod
+    def _dtype_name(dtype: Any, *, np: Any, trt: Any) -> str:
+        try:
+            value = np.dtype(trt.nptype(dtype))
+        except (TypeError, ValueError, AttributeError) as exc:
+            raise RuntimeError(f"unsupported TensorRT tensor dtype {dtype!r}") from exc
+        names = {"float32": "float", "float16": "float16", "float64": "double", "int8": "int8", "int16": "int16", "int32": "int32", "int64": "int64", "uint8": "uint8", "uint16": "uint16", "uint32": "uint32", "uint64": "uint64", "bool": "bool"}
+        try:
+            return f"tensor({names[value.name]})"
+        except KeyError as exc:
+            raise RuntimeError(f"unsupported TensorRT tensor dtype {value}") from exc
+
+    def _tensor_shape(self, name: str) -> list[int | None]:
+        return [None if int(dimension) < 0 else int(dimension) for dimension in self._engine.get_tensor_shape(name)]
+
+    def contract(self) -> dict[str, list[dict[str, Any]]]:
+        inputs: list[dict[str, Any]] = []
+        outputs: list[dict[str, Any]] = []
+        for index in range(self._engine.num_io_tensors):
+            name = self._engine.get_tensor_name(index)
+            value = {"name": name, "dtype": self._dtype_name(self._engine.get_tensor_dtype(name), np=self._np, trt=self._trt), "shape": self._tensor_shape(name)}
+            target = inputs if self._engine.get_tensor_mode(name) == self._trt.TensorIOMode.INPUT else outputs
+            target.append(value)
+        return {"artifact_format": "tensorrt-engine", "inputs": inputs, "outputs": outputs}
+
+    def optimization_profiles(self) -> list[dict[str, Any]]:
+        """Return engine profile bounds without inventing a manifest schema."""
+        count = int(getattr(self._engine, "num_optimization_profiles", 0) or 0)
+        profiles: list[dict[str, Any]] = []
+        for profile_index in range(count):
+            tensors: dict[str, dict[str, list[int]]] = {}
+            for index in range(self._engine.num_io_tensors):
+                name = self._engine.get_tensor_name(index)
+                if self._engine.get_tensor_mode(name) != self._trt.TensorIOMode.INPUT:
+                    continue
+                try:
+                    minimum, optimum, maximum = self._engine.get_tensor_profile_shape(name, profile_index)
+                except (AttributeError, RuntimeError):
+                    continue
+                tensors[name] = {"min": list(minimum), "opt": list(optimum), "max": list(maximum)}
+            profiles.append({"index": profile_index, "inputs": tensors})
+        return profiles
+
+    def runtime_info(self) -> dict[str, Any]:
+        return {"runtime": "tensorrt", "tensorrt_version": getattr(self._trt, "__version__", None), "cuda_binding": getattr(self._cuda, "binding_name", type(self._cuda).__name__), "optimization_profiles": self.optimization_profiles(), "python": platform.python_version(), "system": platform.system(), "machine": platform.machine()}
+
+    def _names(self, mode: Any) -> list[str]:
+        return [self._engine.get_tensor_name(index) for index in range(self._engine.num_io_tensors) if self._engine.get_tensor_mode(self._engine.get_tensor_name(index)) == mode]
+
+    def run(self, inputs: Mapping[str, Any]) -> dict[str, Any]:
+        expected_inputs, expected_outputs = self._names(self._trt.TensorIOMode.INPUT), self._names(self._trt.TensorIOMode.OUTPUT)
+        missing, extra = [name for name in expected_inputs if name not in inputs], [name for name in inputs if name not in expected_inputs]
+        if missing or extra:
+            raise ValueError(f"TensorRT inputs do not match engine (missing={missing}, extra={extra})")
+        prepared: dict[str, Any] = {}
+        for name in expected_inputs:
+            value = self._np.asarray(inputs[name])
+            expected_dtype = self._np.dtype(self._trt.nptype(self._engine.get_tensor_dtype(name)))
+            if value.dtype != expected_dtype:
+                raise TypeError(f"input {name!r} has dtype {value.dtype}, expected {expected_dtype}")
+            if not value.flags.c_contiguous:
+                raise ValueError(f"input {name!r} must be C-contiguous")
+            engine_shape = self._engine.get_tensor_shape(name)
+            if len(value.shape) != len(engine_shape) or any(int(want) >= 0 and int(want) != got for want, got in zip(engine_shape, value.shape)):
+                raise ValueError(f"input {name!r} shape {tuple(value.shape)} does not satisfy engine shape {tuple(engine_shape)}")
+            prepared[name] = value
+            if self._context.set_input_shape(name, tuple(value.shape)) is False:
+                raise ValueError(f"TensorRT rejected input shape for {name!r}: {tuple(value.shape)}")
+
+        allocations: list[tuple[str, int, Any]] = []
+        stream: Any = None
+        synchronized, active_error = False, None
+        try:
+            stream = _check_cuda(self._cuda.cudaStreamCreate(), "cudaStreamCreate")
+            if stream is None:
+                raise RuntimeError("cudaStreamCreate returned a null stream")
+            for name in expected_inputs + expected_outputs:
+                if name in prepared:
+                    value = prepared[name]
+                else:
+                    shape = tuple(int(dimension) for dimension in self._context.get_tensor_shape(name))
+                    if any(dimension < 0 for dimension in shape):
+                        raise ValueError(f"TensorRT output {name!r} has unresolved dynamic shape {shape}")
+                    value = self._np.empty(shape, dtype=self._np.dtype(self._trt.nptype(self._engine.get_tensor_dtype(name))))
+                if value.nbytes <= 0:
+                    raise ValueError(f"TensorRT tensor {name!r} has an empty buffer")
+                device = _check_cuda(self._cuda.cudaMalloc(value.nbytes), f"cudaMalloc({name})")
+                if not device:
+                    raise RuntimeError(f"cudaMalloc({name}) returned a null pointer")
+                allocations.append((name, int(device), value))
+                self._context.set_tensor_address(name, int(device))
+                if name in prepared:
+                    _check_cuda(self._cuda.cudaMemcpyAsync(int(device), int(value.ctypes.data), value.nbytes, self._cuda.cudaMemcpyKind.cudaMemcpyHostToDevice, stream), f"cudaMemcpyAsync(HtoD:{name})")
+            if self._context.execute_async_v3(stream_handle=stream) is False:
+                raise RuntimeError("TensorRT execution failed")
+            for name, device, value in allocations:
+                if name not in expected_outputs:
+                    continue
+                _check_cuda(self._cuda.cudaMemcpyAsync(int(value.ctypes.data), device, value.nbytes, self._cuda.cudaMemcpyKind.cudaMemcpyDeviceToHost, stream), f"cudaMemcpyAsync(DtoH:{name})")
+            _check_cuda(self._cuda.cudaStreamSynchronize(stream), "cudaStreamSynchronize")
+            synchronized = True
+            return {name: value.tolist() for name, _, value in allocations if name in expected_outputs}
+        except BaseException as exc:
+            active_error = exc
+            raise
+        finally:
+            cleanup_errors: list[str] = []
+            if stream is not None and not synchronized:
+                try:
+                    _check_cuda(self._cuda.cudaStreamSynchronize(stream), "cudaStreamSynchronize(cleanup)")
+                except Exception as exc:
+                    cleanup_errors.append(str(exc))
+            for name, device, _ in reversed(allocations):
+                try:
+                    _check_cuda(self._cuda.cudaFree(device), f"cudaFree({name})")
+                except Exception as exc:
+                    cleanup_errors.append(str(exc))
+            if stream is not None:
+                try:
+                    _check_cuda(self._cuda.cudaStreamDestroy(stream), "cudaStreamDestroy")
+                except Exception as exc:
+                    cleanup_errors.append(str(exc))
+            if active_error is None and cleanup_errors:
+                raise RuntimeError("TensorRT CUDA cleanup failed: " + "; ".join(cleanup_errors))