pixtreme-infer 0.14.4__tar.gz

pixtreme_infer-0.14.4/.gitignore

@@ -0,0 +1,167 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.coveragerc
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintainted in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Development
+.ruff_cache/
+.serena/
+.claude/
+.kiro/
+cache/
+examples/
+models/
+sandbox/
+.vscode
+.clinerules
+
+.python-version

pixtreme_infer-0.14.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minamik
+
+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.

pixtreme_infer-0.14.4/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: pixtreme-infer
+Version: 0.14.4
+Summary: Inference companion for pixtreme: architecture-independent inference contracts and verification
+Project-URL: repository, https://github.com/sync-dev-org/pixtreme-infer
+Project-URL: issues, https://github.com/sync-dev-org/pixtreme-infer/issues
+Author-email: minamik <mia@sync.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: GPU :: NVIDIA CUDA :: 13
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: pixtreme>=1.3.0
+Provides-Extra: ort
+Requires-Dist: onnxruntime-gpu>=1.20; extra == 'ort'
+Provides-Extra: verify
+Requires-Dist: nvidia-ml-py; extra == 'verify'
+Description-Content-Type: text/markdown
+
+# pixtreme.infer
+
+This repository owns the pure-Python distribution `pixtreme-infer` and its import package
+`pixtreme.infer`. It provides the architecture-independent Frame boundary, shared inference
+contracts, ONNX verification, recipe identity, and static dispatch used by architecture
+distributions.
+
+The wheel owns only the `pixtreme/infer/` subtree. The namespace root
+`pixtreme/__init__.py` remains owned by
+[pixtreme](https://github.com/sync-dev-org/pixtreme). Architecture implementations are
+maintained and distributed separately as architecture distributions.
+
+## Capabilities
+
+The base dependency is `pixtreme>=1.3.0`. Optional capabilities are separated by extra:
+
+- `ort`: ONNX Runtime verification.
+- `verify`: device telemetry for the shared verification tools.
+
+The core does not depend on TensorRT or torch. Architecture distributions build and run
+TensorRT engines through tensoracle and declare TensorRT and tensoracle as their own
+dependencies.
+
+Core-only installation exposes the shared contracts and gives an actionable error when a
+known architecture distribution is absent. The core does not eagerly import architecture
+implementations.
+
+## Development
+
+Run development commands from the repository root:
+
+```console
+uv sync --all-extras
+uv lock --check
+CUDA_VISIBLE_DEVICES='' uv run --no-sync python -m pytest -q
+uv run --no-sync mypy
+uv run --no-sync ruff check src tests
+uv run --no-sync ruff format --check src tests
+uv build --wheel
+```
+
+The normal test suite does not require a GPU. Tests that require unavailable optional
+dependencies skip with a reason.
+
+## Version and release
+
+Versions come from tags named `vX.Y.Z`. Each version is published to PyPI as
+`pixtreme-infer`; there is no corresponding GitHub Release or Release asset.
+
+## CUDA Graph components for module authors
+
+`pixtreme.infer.cuda_graph` exports `CudaGraphSession` and `CudaGraphBuffers`.
+The core captures backend operations that enqueue work using fixed GPU storage.
+A module still validates every request, selects an operation, handles its temporal
+history and reset, and builds output metadata on every call. The core does not
+capture the module's public Frame call or import an inference backend.
+
+A module can implement the optional
+`CudaGraphFactoryProvider[StatelessInferenceFactory[ArtifactIdentity]]` or
+`CudaGraphFactoryProvider[TemporalInferenceFactory[ArtifactIdentity]]` protocol
+from `pixtreme.infer.contracts`. Its `graph_factory()` returns a separate factory
+with the original inference form. Factory selection and `query_contract` allocate
+no GPU memory. `open` repeats configuration validation and prepares all graphs
+before returning an instance whose contract equals the query result. The normal
+factory keeps its existing operations and accepted settings; there is no new
+required setting on existing factories.
+
+Open a graph instance inside its device and an explicit non-default CUDA stream.
+One instance handles one fixed input configuration on that device and stream,
+with sequential host calls. Modules can prepare several named operations, with
+shared fixed storage and separate backend execution units where their backend
+requires them. The following fragment shows the integration inside a module;
+the backend callables, fixed Frames, GPU parameters, history, and execution units
+are prepared and owned by that module:
+
+```python
+from pixtreme.infer.cuda_graph import CudaGraphBuffers, CudaGraphSession
+
+buffers = CudaGraphBuffers(
+    fixed_input_frame, fixed_output_frame, params=fixed_gpu_params,
+)
+graphs = CudaGraphSession(
+    {"route-a": enqueue_a, "route-b": enqueue_b},
+    resources=(buffers, *history, *execution_units),
+    after_prepare=restore_initial_history_and_controls,
+)
+```
+
+Each callable must enqueue on the current stream, use only fixed GPU addresses,
+and be safe for CUDA stream capture. Preparation calls each callable once for
+warm-up, waits for that stream, and captures it once. Keep every buffer and
+backend workspace used inside capture alive for the whole session, using the
+callable's owners or `resources`. Allocating an unretained temporary inside
+capture is invalid. Preparation can write history; `after_prepare` restores both
+GPU history and host controls to their open state without consuming requests.
+If any operation or this callback fails, preparation releases all captured graphs
+and retained references and propagates the error. The module's `open` must also
+release its own partially prepared resources. No partial instance or automatic
+normal-path fallback is returned.
+
+For each request, the module first checks its Frame metadata, reset control, and
+parameter contract. It calls `graphs.check_context()` **before** copying inputs
+or resetting history. Then it can perform these steps:
+
+```python
+# Module request validation and graph selection have already completed.
+graphs.check_context()
+buffers.copy_inputs(frame, **gpu_params)
+if reset:
+    reset_history_on_current_stream()
+graphs.replay(selected_name)
+result = buffers.copy_output(
+    channels=output_channels,
+    colorspace=output_colorspace,
+    gamma=output_gamma,
+    matrix=output_matrix,
+)
+```
+
+`copy_inputs` validates every source before the first copy and requires exact
+shape, dtype, device, and auxiliary names. It imports Frame storage through
+DLPack and accepts CUDA auxiliary arrays, including CAI v3 and CUDA DLPack
+producers. Sources must already be ready on the current stream and remain alive
+until its copies complete. Copying performs no casting, broadcasting, or host
+transfer, and the graph retains no caller input address. Modules validate reset
+before calling this method, so a structurally rejected request does not clear
+history or modify fixed storage. Auxiliary inputs are distinct from module-owned
+temporal history; reset and graph selection remain module responsibilities.
+
+`copy_output` allocates independent GPU storage outside capture and uses the
+metadata supplied for that request. Returned Frames remain unchanged by later
+replays, resets, and close. Requests enqueue without a host wait. Callers use
+CUDA events for another stream to consume results, and finish outstanding work
+before the module closes `graphs`, `buffers`, and its backend resources. Both
+component `close()` methods are idempotent and perform no synchronization; later
+operations on closed components fail before GPU work. Changing settings, device,
+or stream requires opening another instance; there is no automatic recapture or
+graph cache.
+
+For common verification, supply `CudaGraphContractSuite(module, replay_equivalence)`
+to `verify_cuda_graph_contract` in `pixtreme.infer.verification`. `module` is the
+existing `StatelessContractSuite` or `TemporalContractSuite`, populated from the
+graph factory and its instances. This runs `FactoryContractCases` unchanged and,
+for temporal modules, the existing reset, startup, instance isolation, and
+persistent state footprint checks. `replay_equivalence` supplies `SequenceFacts`
+from separate normal and graph instances with the same settings, including the
+first call, continuation, changed input values and metadata, and resets. Missing
+evidence stays unverified. Modules retain ownership of their fixtures, correctness
+thresholds, support declarations, and evidence. Performance measurements do not
+determine support status.
+
+The opt-in synthetic GPU tests use no TensorRT or tensoracle. Run correctness with
+`uv run --no-sync python -m pytest -m 'gpu and not performance' tests/test_cuda_graph_gpu.py`,
+selecting the GPU with `CUDA_VISIBLE_DEVICES` when the machine has several.
+The `performance` cases record video-sized copy latency with CUDA events and print
+median and p90 values; they apply no speed threshold.
+
+## License
+
+The core distribution `pixtreme-infer` is licensed under the MIT License; see
+[LICENSE](LICENSE). Architecture distributions are separate distributions, each with its own
+license. The core license does not apply to them, and installing one does not change the core
+license.

pixtreme_infer-0.14.4/README.md

@@ -0,0 +1,163 @@
+# pixtreme.infer
+
+This repository owns the pure-Python distribution `pixtreme-infer` and its import package
+`pixtreme.infer`. It provides the architecture-independent Frame boundary, shared inference
+contracts, ONNX verification, recipe identity, and static dispatch used by architecture
+distributions.
+
+The wheel owns only the `pixtreme/infer/` subtree. The namespace root
+`pixtreme/__init__.py` remains owned by
+[pixtreme](https://github.com/sync-dev-org/pixtreme). Architecture implementations are
+maintained and distributed separately as architecture distributions.
+
+## Capabilities
+
+The base dependency is `pixtreme>=1.3.0`. Optional capabilities are separated by extra:
+
+- `ort`: ONNX Runtime verification.
+- `verify`: device telemetry for the shared verification tools.
+
+The core does not depend on TensorRT or torch. Architecture distributions build and run
+TensorRT engines through tensoracle and declare TensorRT and tensoracle as their own
+dependencies.
+
+Core-only installation exposes the shared contracts and gives an actionable error when a
+known architecture distribution is absent. The core does not eagerly import architecture
+implementations.
+
+## Development
+
+Run development commands from the repository root:
+
+```console
+uv sync --all-extras
+uv lock --check
+CUDA_VISIBLE_DEVICES='' uv run --no-sync python -m pytest -q
+uv run --no-sync mypy
+uv run --no-sync ruff check src tests
+uv run --no-sync ruff format --check src tests
+uv build --wheel
+```
+
+The normal test suite does not require a GPU. Tests that require unavailable optional
+dependencies skip with a reason.
+
+## Version and release
+
+Versions come from tags named `vX.Y.Z`. Each version is published to PyPI as
+`pixtreme-infer`; there is no corresponding GitHub Release or Release asset.
+
+## CUDA Graph components for module authors
+
+`pixtreme.infer.cuda_graph` exports `CudaGraphSession` and `CudaGraphBuffers`.
+The core captures backend operations that enqueue work using fixed GPU storage.
+A module still validates every request, selects an operation, handles its temporal
+history and reset, and builds output metadata on every call. The core does not
+capture the module's public Frame call or import an inference backend.
+
+A module can implement the optional
+`CudaGraphFactoryProvider[StatelessInferenceFactory[ArtifactIdentity]]` or
+`CudaGraphFactoryProvider[TemporalInferenceFactory[ArtifactIdentity]]` protocol
+from `pixtreme.infer.contracts`. Its `graph_factory()` returns a separate factory
+with the original inference form. Factory selection and `query_contract` allocate
+no GPU memory. `open` repeats configuration validation and prepares all graphs
+before returning an instance whose contract equals the query result. The normal
+factory keeps its existing operations and accepted settings; there is no new
+required setting on existing factories.
+
+Open a graph instance inside its device and an explicit non-default CUDA stream.
+One instance handles one fixed input configuration on that device and stream,
+with sequential host calls. Modules can prepare several named operations, with
+shared fixed storage and separate backend execution units where their backend
+requires them. The following fragment shows the integration inside a module;
+the backend callables, fixed Frames, GPU parameters, history, and execution units
+are prepared and owned by that module:
+
+```python
+from pixtreme.infer.cuda_graph import CudaGraphBuffers, CudaGraphSession
+
+buffers = CudaGraphBuffers(
+    fixed_input_frame, fixed_output_frame, params=fixed_gpu_params,
+)
+graphs = CudaGraphSession(
+    {"route-a": enqueue_a, "route-b": enqueue_b},
+    resources=(buffers, *history, *execution_units),
+    after_prepare=restore_initial_history_and_controls,
+)
+```
+
+Each callable must enqueue on the current stream, use only fixed GPU addresses,
+and be safe for CUDA stream capture. Preparation calls each callable once for
+warm-up, waits for that stream, and captures it once. Keep every buffer and
+backend workspace used inside capture alive for the whole session, using the
+callable's owners or `resources`. Allocating an unretained temporary inside
+capture is invalid. Preparation can write history; `after_prepare` restores both
+GPU history and host controls to their open state without consuming requests.
+If any operation or this callback fails, preparation releases all captured graphs
+and retained references and propagates the error. The module's `open` must also
+release its own partially prepared resources. No partial instance or automatic
+normal-path fallback is returned.
+
+For each request, the module first checks its Frame metadata, reset control, and
+parameter contract. It calls `graphs.check_context()` **before** copying inputs
+or resetting history. Then it can perform these steps:
+
+```python
+# Module request validation and graph selection have already completed.
+graphs.check_context()
+buffers.copy_inputs(frame, **gpu_params)
+if reset:
+    reset_history_on_current_stream()
+graphs.replay(selected_name)
+result = buffers.copy_output(
+    channels=output_channels,
+    colorspace=output_colorspace,
+    gamma=output_gamma,
+    matrix=output_matrix,
+)
+```
+
+`copy_inputs` validates every source before the first copy and requires exact
+shape, dtype, device, and auxiliary names. It imports Frame storage through
+DLPack and accepts CUDA auxiliary arrays, including CAI v3 and CUDA DLPack
+producers. Sources must already be ready on the current stream and remain alive
+until its copies complete. Copying performs no casting, broadcasting, or host
+transfer, and the graph retains no caller input address. Modules validate reset
+before calling this method, so a structurally rejected request does not clear
+history or modify fixed storage. Auxiliary inputs are distinct from module-owned
+temporal history; reset and graph selection remain module responsibilities.
+
+`copy_output` allocates independent GPU storage outside capture and uses the
+metadata supplied for that request. Returned Frames remain unchanged by later
+replays, resets, and close. Requests enqueue without a host wait. Callers use
+CUDA events for another stream to consume results, and finish outstanding work
+before the module closes `graphs`, `buffers`, and its backend resources. Both
+component `close()` methods are idempotent and perform no synchronization; later
+operations on closed components fail before GPU work. Changing settings, device,
+or stream requires opening another instance; there is no automatic recapture or
+graph cache.
+
+For common verification, supply `CudaGraphContractSuite(module, replay_equivalence)`
+to `verify_cuda_graph_contract` in `pixtreme.infer.verification`. `module` is the
+existing `StatelessContractSuite` or `TemporalContractSuite`, populated from the
+graph factory and its instances. This runs `FactoryContractCases` unchanged and,
+for temporal modules, the existing reset, startup, instance isolation, and
+persistent state footprint checks. `replay_equivalence` supplies `SequenceFacts`
+from separate normal and graph instances with the same settings, including the
+first call, continuation, changed input values and metadata, and resets. Missing
+evidence stays unverified. Modules retain ownership of their fixtures, correctness
+thresholds, support declarations, and evidence. Performance measurements do not
+determine support status.
+
+The opt-in synthetic GPU tests use no TensorRT or tensoracle. Run correctness with
+`uv run --no-sync python -m pytest -m 'gpu and not performance' tests/test_cuda_graph_gpu.py`,
+selecting the GPU with `CUDA_VISIBLE_DEVICES` when the machine has several.
+The `performance` cases record video-sized copy latency with CUDA events and print
+median and p90 values; they apply no speed threshold.
+
+## License
+
+The core distribution `pixtreme-infer` is licensed under the MIT License; see
+[LICENSE](LICENSE). Architecture distributions are separate distributions, each with its own
+license. The core license does not apply to them, and installing one does not change the core
+license.

pixtreme_infer-0.14.4/pyproject.toml

@@ -0,0 +1,123 @@
+[project]
+name = "pixtreme-infer"
+dynamic = ["version"]
+description = "Inference companion for pixtreme: architecture-independent inference contracts and verification"
+authors = [
+    { name = "minamik", email = "mia@sync.dev" },
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: GPU :: NVIDIA CUDA :: 13",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pixtreme>=1.3.0",
+]
+
+[project.optional-dependencies]
+ort = [
+    "onnxruntime-gpu>=1.20",
+]
+verify = [
+    "nvidia-ml-py",
+]
+
+[project.urls]
+repository = "https://github.com/sync-dev-org/pixtreme-infer"
+issues = "https://github.com/sync-dev-org/pixtreme-infer/issues"
+
+[dependency-groups]
+dev = [
+    "packaging>=24",
+    "pytest>=8.3.5",
+    "ruff>=0.15.22",
+    "mypy>=1.0.0",
+    "pillow>=11",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["--strict-markers", "-m", "not performance and not gpu"]
+markers = [
+    "req(id): ID of the spec item the test verifies",
+    "performance: opt-in performance/timing tests (excluded by default)",
+    "extras: tests that import an optional extra (onnxruntime / nvidia-ml-py) and skip when it is absent",
+    "gpu: tests that need a real NVIDIA GPU and the matching extras (skipped when absent)",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = [
+    "E501",  # Line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+# The namespace root is supplied by the external pixtreme distribution even
+# though the companion subtree lives under the configured local source root.
+known-third-party = ["pixtreme"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+warn_unused_configs = true
+files = [
+    "src/pixtreme",
+]
+mypy_path = [
+    "src",
+]
+explicit_package_bases = true
+namespace_packages = true
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "."
+# Releases are tagged vX.Y.Z; published pixtreme-infer/vX.Y.Z tags remain valid history.
+tag_regex = "^(?:pixtreme-infer/)?v(?P<version>[0-9].*)$"
+git_describe_command = 'git describe --dirty --tags --long --match "v[0-9]*" --match "pixtreme-infer/v[0-9]*"'
+fallback_version = "0.0.0.dev0"
+
+[tool.hatch.build.targets.wheel]
+# The companion owns only pixtreme/infer; pixtreme/__init__.py remains owned by pixtreme.
+only-include = [
+    "src/pixtreme/infer",
+]
+sources = ["src"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+exclude = [
+    "/__pycache__",
+]
+
+[build-system]
+requires = [
+    "hatchling",
+    "hatch-vcs",
+]
+build-backend = "hatchling.build"