ml-pipes-tensor 0.1.0rc2__tar.gz

ml_pipes_tensor-0.1.0rc2/.gitignore

@@ -0,0 +1,44 @@
+# macOS / editor noise
+.DS_Store
+.idea/
+/tmp/
+
+# Python caches
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Test and tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+
+# Packaging / build artifacts
+build/
+dist/
+packages/*/dist-noiso/
+*.whl
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+# Downloaded demo assets and runtime outputs
+.example_assets/
+examples/.example_assets/
+*.onnx
+*.pt
+*.jpg
+*.png
+*.mp4
+*.pkl
+
+# Tracked GitHub-facing promo/docs assets
+!.github/assets/**

ml_pipes_tensor-0.1.0rc2/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.

ml_pipes_tensor-0.1.0rc2/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: ml-pipes-tensor
+Version: 0.1.0rc2
+Summary: Tensor payloads and tensor registry operators for ml-pipes
+Project-URL: Homepage, https://github.com/trained-by-humans/ml-pipes
+Project-URL: Documentation, https://github.com/trained-by-humans/ml-pipes/blob/main/packages/tensor/docs/INDEX.md
+Project-URL: Repository, https://github.com/trained-by-humans/ml-pipes
+Project-URL: Issues, https://github.com/trained-by-humans/ml-pipes/issues
+Project-URL: Changelog, https://github.com/trained-by-humans/ml-pipes/releases
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: machine-learning,numpy,pipelines,postprocess,tensor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: ml-pipes-core==0.1.0rc2
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# ml-pipes-tensor
+
+`ml-pipes-tensor` is the shared tensor workbench for `ml-pipes`.
+
+Use this package when a pipeline needs NumPy-side tensor shaping, ranking,
+masking, filtering, collation, or light arithmetic between a runtime boundary
+and a typed task result. In practice, it often carries the reusable tensor
+postprocess that sits after ONNX or Torch output extraction and before a task
+package such as vision finalizes the result.
+
+Operators can be used as plain callables, but this package is best used inside
+an `ml-pipes` pipeline.
+
+## Package Reference
+
+| Field          | Value                                                                                                            |
+|----------------|------------------------------------------------------------------------------------------------------------------|
+| Package        | `ml-pipes-tensor`                                                                                                |
+| Guide          | [`docs/README.md`](https://github.com/trained-by-humans/ml-pipes/blob/main/packages/tensor/docs/README.md)       |
+| Reference      | [`docs/INDEX.md`](https://github.com/trained-by-humans/ml-pipes/blob/main/packages/tensor/docs/INDEX.md)         |
+| Depends on     | `ml-pipes-core`                                                                                                  |
+| Public modules | `ml_pipes.tensor`                                                                                                |
+| Content        | shared tensor values; NumPy-side tensor shaping and selection; masking, ranking, collation, and light arithmetic |
+
+See [`docs/PACKAGES.md`](https://github.com/trained-by-humans/ml-pipes/blob/main/docs/PACKAGES.md)
+for direct package installs, umbrella profiles, and the full package matrix.

ml_pipes_tensor-0.1.0rc2/README.md

@@ -0,0 +1,26 @@
+# ml-pipes-tensor
+
+`ml-pipes-tensor` is the shared tensor workbench for `ml-pipes`.
+
+Use this package when a pipeline needs NumPy-side tensor shaping, ranking,
+masking, filtering, collation, or light arithmetic between a runtime boundary
+and a typed task result. In practice, it often carries the reusable tensor
+postprocess that sits after ONNX or Torch output extraction and before a task
+package such as vision finalizes the result.
+
+Operators can be used as plain callables, but this package is best used inside
+an `ml-pipes` pipeline.
+
+## Package Reference
+
+| Field          | Value                                                                                                            |
+|----------------|------------------------------------------------------------------------------------------------------------------|
+| Package        | `ml-pipes-tensor`                                                                                                |
+| Guide          | [`docs/README.md`](https://github.com/trained-by-humans/ml-pipes/blob/main/packages/tensor/docs/README.md)       |
+| Reference      | [`docs/INDEX.md`](https://github.com/trained-by-humans/ml-pipes/blob/main/packages/tensor/docs/INDEX.md)         |
+| Depends on     | `ml-pipes-core`                                                                                                  |
+| Public modules | `ml_pipes.tensor`                                                                                                |
+| Content        | shared tensor values; NumPy-side tensor shaping and selection; masking, ranking, collation, and light arithmetic |
+
+See [`docs/PACKAGES.md`](https://github.com/trained-by-humans/ml-pipes/blob/main/docs/PACKAGES.md)
+for direct package installs, umbrella profiles, and the full package matrix.

ml_pipes_tensor-0.1.0rc2/docs/README.md

@@ -0,0 +1,196 @@
+# Tensor Postprocess Domain
+
+`ml_pipes.tensor` is the shared NumPy-side tensor workbench between runtime
+packages and task packages.
+
+For the full package surface, aliases, and operator catalog, see
+[`INDEX.md`](./INDEX.md).
+
+## Package Profile
+
+| Dimension       | Classification                                                          |
+|-----------------|-------------------------------------------------------------------------|
+| Role / Function | `Inference (Scaffold)`                                                  |
+| Task Type       | Mostly `Vision`; reusable across other tensor-returning inference flows |
+| Data Type       | `Tensors`                                                               |
+
+## Scope And Use Cases
+
+`ml_pipes.tensor` owns the small, explicit, generic NumPy-side tensor
+operators and value types that sit around runtime handoff and shared
+postprocess. It does not own runtime execution, model-specific decode logic,
+task finalization, or image/media preparation.
+
+Use this package when a pipeline needs a reusable NumPy-side tensor segment
+between runtime output handoff and task finalization, especially during model
+scaffolding or shared postprocess.
+
+## Design Principles
+
+Every operator in this package is designed to uphold the following properties.
+They are not style guidelines; they are what makes operators safe to compose
+and swap without side effects.
+
+- **Model-agnostic.** No operator knows which model produced the tensors it
+  processes. `Softmax`, `ArgMax`, and `Slice` are generic. Model-specific
+  adaptations stay in the pipeline list as individual operators, not inside
+  shared infrastructure.
+- **Precision-agnostic.** Operators preserve the dtype of their input. A
+  pipeline that runs in `float32` runs in `float16` without modifying any
+  operator. A preprocessing step such as `Normalize()` sets the working
+  precision before data enters the Tensor domain.
+- **Runtime-agnostic.** Operators use NumPy. They impose no dependency on
+  PyTorch, TensorFlow, or any specific hardware. Runtime packages own the
+  inference step; the Tensor domain stays plain NumPy and transfers to any
+  compute environment.
+- **Backend-explicit.** Unlike the points above, operators are not
+  backend-agnostic. They do not pretend to be one backend-polymorphic tensor
+  layer. Runtime-specific execution stays in the owning runtime packages.
+- **Small and explicit.** Each operator should stay small and explicit in the
+  pipeline list and should own one clear tensor step.
+
+## Runtime Types
+
+The Tensor package uses explicit runtime values instead of passing bare
+`np.ndarray` objects through every step. `TensorPayload` covers one
+model-ready tensor together with layout and dtype metadata, while
+`TensorRegistry` covers a named working set of tensors for postprocess.
+
+### TensorPayload
+
+`TensorPayload` is the one-tensor value type.
+
+Use it when one array should move through the pipeline as one value and the
+next step needs its layout and working dtype together with the tensor:
+
+- `array`: the NumPy tensor
+- `layout`: the semantic axis order such as `NHWC` or `NCHW`
+- `dtype`: the working dtype recorded for the payload
+
+It is commonly created by preprocessing operators such as `Normalize()`, then
+consumed by operators such as `Infer()`, `ToTorch()`, or `Collate()`.
+
+This is the common runtime handoff:
+
+```python
+from ml_pipes.core import Pipeline
+from ml_pipes.onnx import Infer
+from ml_pipes.vision import Normalize
+
+pipeline = Pipeline([
+    Normalize(),  # -> TensorPayload
+    Infer(model_path),
+])
+```
+
+### TensorRegistry
+
+`TensorRegistry` is the named multi-tensor working set for postprocess.
+
+Use it when postprocess needs multiple intermediate tensors to stay named and
+aligned. Tensor operators then refine those named tensors step by step until a
+task package turns them into the final result.
+
+This is the common postprocess shape:
+
+```python
+from ml_pipes.core import Pipeline
+from ml_pipes.onnx import Extract
+from ml_pipes.tensor import ArgMax, GatherScores
+
+pipeline = Pipeline([
+    Extract("scores", as_="class_scores"),  # -> TensorRegistry
+    ArgMax("class_scores", as_="classes"),
+    GatherScores("class_scores", "classes", as_="scores"),
+])
+```
+
+## Where Tensor Fits
+
+Tensor sits between runtime packages and task packages. It does not own the
+runtime step itself.
+
+The nearby package crossings are:
+
+- `Normalize()` from `ml_pipes.vision` creates a `TensorPayload`
+- `Extract()` from `ml_pipes.onnx` creates a `TensorRegistry`
+- `ToNumpy()` and `ToNumpyRegistry()` from `ml_pipes.torch` return back to the
+  Tensor domain
+- `ToDetections()`, `ToSegmentations()`, and `ToDensityPrediction()` from
+  `ml_pipes.vision` finalize typed task results
+
+At a high level, a common flow looks like this:
+
+```text
+┌──────────────────────────────────────────────────────────┐
+│ Input / Task Domain                                      │
+├─ Decode -> Resize -> Normalize -> ...                    │
+└────────┬─────────────────────────────────────────────────┘
+         |
+         | TensorPayload
+         ▼
+┌──────────────────────────────────────────────────────────┐
+│ Runtime Domain                                           │
+├─ Infer / TorchInfer / ...                                │
+└────────┬─────────────────────────────────────────────────┘
+         |
+         | Extract / ToNumpyRegistry
+         ▼
+┌──────────────────────────────────────────────────────────┐
+│ Tensor Domain                                            │
+├─ Squeeze -> Slice -> Softmax -> ArgMax -> FilterTensors  │
+└────────┬─────────────────────────────────────────────────┘
+         |
+         | ToDetections / ToSegmentations / ...
+         ▼
+┌──────────────────────────────────────────────────────────┐
+│ Task Result Domain                                       │
+└──────────────────────────────────────────────────────────┘
+```
+
+That split keeps runtime integration, shared tensor postprocess, and
+task-specific finalization as separate stages.
+
+## Using Tensor In Pipelines
+
+This section shows only the Tensor-owned slice: start from extracted named
+tensors, apply small registry operators to refine them, then hand the final
+tensors to a task package.
+
+```python
+from ml_pipes.core import Pipeline
+from ml_pipes.onnx import Extract
+from ml_pipes.tensor import ArgMax, GatherScores, Slice, Squeeze, Transpose
+from ml_pipes.vision import ConvertBoxFormat, ToDetections
+
+pipeline = Pipeline([
+    ...,
+    Extract("output0", as_="preds"),
+    Squeeze("preds"),
+    Transpose("preds"),
+    Slice("preds", slice(None, 4), as_="boxes"),
+    Slice("preds", slice(4, None), as_="scores"),
+    ArgMax("scores", as_="classes"),
+    GatherScores("scores", "classes"),
+    ConvertBoxFormat(from_="cxcywh"),
+    ToDetections(),
+])
+```
+
+This is the shape used in
+[`examples/run_yolo8_onnx.py`](../../../examples/run_yolo8_onnx.py) and
+[`examples/run_rfdetr_nano.py`](../../../examples/run_rfdetr_nano.py).
+
+For the full guide on how to build scaffolding around the model, see
+[`SCAFFOLDING.md`](../../../docs/SCAFFOLDING.md).
+
+## Further Reading
+
+- [`INDEX.md`](./INDEX.md) for the full surface catalog
+- [`docs/README.md`](../../../docs/README.md) for the shared framework docs index
+- [`REGIONS.md`](../../../docs/REGIONS.md) for batching and regions
+- [`Torch guide`](../../torch/docs/README.md) for Torch/NumPy crossover pipelines
+- [`Vision guide`](../../vision/docs/README.md) for task-specific tensor operations and typed results in vision pipelines
+- [`examples/README.md`](../../../examples/README.md) for runnable pipeline entry points
+  - [`examples/run_yolo8_onnx.py`](../../../examples/run_yolo8_onnx.py)
+  - [`examples/run_rfdetr_nano.py`](../../../examples/run_rfdetr_nano.py)

ml_pipes_tensor-0.1.0rc2/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ml-pipes-tensor"
+version = "0.1.0rc2"
+description = "Tensor payloads and tensor registry operators for ml-pipes"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+keywords = [
+    "machine-learning",
+    "numpy",
+    "pipelines",
+    "postprocess",
+    "tensor",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "ml-pipes-core==0.1.0rc2",
+    "numpy>=1.26",
+]
+
+[project.urls]
+Homepage = "https://github.com/trained-by-humans/ml-pipes"
+Documentation = "https://github.com/trained-by-humans/ml-pipes/blob/main/packages/tensor/docs/INDEX.md"
+Repository = "https://github.com/trained-by-humans/ml-pipes"
+Issues = "https://github.com/trained-by-humans/ml-pipes/issues"
+Changelog = "https://github.com/trained-by-humans/ml-pipes/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ml_pipes"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+    "src/ml_pipes",
+]

ml_pipes_tensor-0.1.0rc2/src/ml_pipes/tensor/__init__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from .ops import (
+    ApplyTensorMask,
+    ArgMax,
+    AsType,
+    BinarizeTensor,
+    BinarizeTensorByThreshold,
+    Collate,
+    CreateTensorMask,
+    CreateTensorMaskByThreshold,
+    FilterTensors,
+    GatherRows,
+    GatherScores,
+    MapTensor,
+    MultiplyTensors,
+    Scale,
+    SelectTensors,
+    Sigmoid,
+    Slice,
+    Softmax,
+    SortTensorsBy,
+    Squeeze,
+    TopK,
+    TopKIndices2D,
+    Transpose,
+)
+from .types import TensorPayload, TensorRegistry
+
+__all__ = [
+    "ApplyTensorMask",
+    "ArgMax",
+    "AsType",
+    "BinarizeTensor",
+    "BinarizeTensorByThreshold",
+    "Collate",
+    "CreateTensorMask",
+    "CreateTensorMaskByThreshold",
+    "FilterTensors",
+    "GatherRows",
+    "GatherScores",
+    "MapTensor",
+    "MultiplyTensors",
+    "Scale",
+    "SelectTensors",
+    "Sigmoid",
+    "Slice",
+    "Softmax",
+    "SortTensorsBy",
+    "Squeeze",
+    "TensorPayload",
+    "TensorRegistry",
+    "TopK",
+    "TopKIndices2D",
+    "Transpose",
+]

ml_pipes_tensor-0.1.0rc2/src/ml_pipes/tensor/ops.py

@@ -0,0 +1,473 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Generic, Literal, TypeAlias, TypeVar, cast, overload
+
+import numpy as np
+import numpy.typing as npt
+
+from ml_pipes._operator_utils import resolve_multi_output_names
+from ml_pipes._typing.annotation import is_assignable
+from ml_pipes.operator import Operator
+from .types import TensorPayload, TensorRegistry
+
+__all__ = [
+    "ApplyTensorMask",
+    "ArgMax",
+    "AsType",
+    "BinarizeTensor",
+    "BinarizeTensorByThreshold",
+    "Collate",
+    "CreateTensorMask",
+    "CreateTensorMaskByThreshold",
+    "FilterTensors",
+    "GatherRows",
+    "GatherScores",
+    "MapTensor",
+    "MultiplyTensors",
+    "Scale",
+    "SelectTensors",
+    "Sigmoid",
+    "Slice",
+    "Softmax",
+    "SortTensorsBy",
+    "Squeeze",
+    "TensorPayload",
+    "TensorRegistry",
+    "TopK",
+    "TopKIndices2D",
+    "Transpose",
+]
+
+TensorLike: TypeAlias = (
+    TensorPayload
+    | np.ndarray
+    | tuple[TensorPayload, ...]
+    | tuple[np.ndarray, ...]
+    | list[TensorPayload]
+    | list[np.ndarray]
+)
+TensorMask: TypeAlias = npt.NDArray[np.bool_]
+TensorInput: TypeAlias = TensorLike | TensorRegistry
+TensorValueT = TypeVar("TensorValueT", bound=TensorLike)
+AsTypeModeT = TypeVar("AsTypeModeT", bound=bool)
+
+
+def _normalize_axis(axis: int, ndim: int) -> int:
+    normalized = axis if axis >= 0 else axis + ndim
+    if normalized < 0 or normalized >= ndim:
+        raise np.exceptions.AxisError(axis, ndim=ndim)
+    return normalized
+
+
+def _shape_without_axis(shape: tuple[int, ...], axis: int) -> tuple[int, ...]:
+    return shape[:axis] + shape[axis + 1 :]
+
+
+def _flatten_leading_dim(array: np.ndarray) -> np.ndarray:
+    leading = int(array.shape[0])
+    trailing = int(np.prod(array.shape[1:], dtype=np.int64))
+    return array.reshape(leading, trailing)
+
+
+@Operator
+class AsType(Generic[AsTypeModeT]):
+    @overload
+    def __init__(
+        self: "AsType[Literal[False]]",
+        dtype: str,
+        src: None = None,
+        as_: None = None,
+    ) -> None:
+        ...
+
+    @overload
+    def __init__(
+        self: "AsType[Literal[True]]",
+        dtype: str,
+        src: str,
+        as_: str | None = None,
+    ) -> None:
+        ...
+
+    def __init__(self, dtype: str, src: str | None = None, as_: str | None = None):
+        if src is None and as_ is not None:
+            raise ValueError("AsType as_ requires src.")
+        self.dtype = np.dtype(dtype)
+        self.src = src
+        self.as_ = as_ or src
+
+    def resolve_contract(self, upstream_annotation, error_type):
+        if self.src is not None:
+            return (TensorRegistry,), TensorRegistry
+        if upstream_annotation is not Any and is_assignable(upstream_annotation, TensorLike):
+            return (upstream_annotation,), upstream_annotation
+        return (TensorLike,), TensorLike
+
+    @overload
+    def __call__(self: "AsType[Literal[False]]", value: TensorValueT) -> TensorValueT:
+        ...
+
+    @overload
+    def __call__(self: "AsType[Literal[True]]", value: TensorRegistry) -> TensorRegistry:
+        ...
+
+    def __call__(self, value: Any) -> Any:
+        if self.src is not None:
+            if not isinstance(value, TensorRegistry):
+                raise TypeError(f"AsType src={self.src!r} requires TensorRegistry, got {type(value)!r}")
+            value[self.as_] = self._cast_array(value[self.src])
+            return value
+        return self._cast_value(value)
+
+    def _cast_value(self, value: TensorValueT) -> TensorValueT:
+        if isinstance(value, TensorPayload):
+            return cast(
+                TensorValueT,
+                TensorPayload(array=value.array.astype(self.dtype, copy=False), layout=value.layout, dtype=str(self.dtype)),
+            )
+        if isinstance(value, np.ndarray):
+            return cast(TensorValueT, self._cast_array(value))
+        if isinstance(value, tuple):
+            return cast(TensorValueT, tuple(self._cast_sequence_item(item) for item in value))
+        if isinstance(value, list):
+            return cast(TensorValueT, [self._cast_sequence_item(item) for item in value])
+        raise TypeError(f"AsType does not support value type {type(value)!r}")
+
+    def _cast_sequence_item(self, value: object) -> TensorPayload | np.ndarray:
+        if isinstance(value, TensorPayload):
+            return TensorPayload(array=value.array.astype(self.dtype, copy=False), layout=value.layout, dtype=str(self.dtype))
+        if isinstance(value, np.ndarray):
+            return self._cast_array(value)
+        raise TypeError(f"AsType does not support sequence item type {type(value)!r}")
+
+    def _cast_array(self, value: np.ndarray) -> np.ndarray:
+        return np.asarray(value).astype(self.dtype, copy=False)
+
+
+@Operator
+class Squeeze:
+    def __init__(self, src: str, axis: int | tuple[int, ...] | None = None, as_: str | None = None):
+        self.src = src
+        self.axis = axis
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        tensor = registry[self.src]
+        registry[self.as_] = np.squeeze(tensor, axis=self.axis) if self.axis is not None else np.squeeze(tensor)
+        return registry
+
+
+@Operator
+class Transpose:
+    def __init__(self, src: str, axes: tuple[int, ...] | None = None, as_: str | None = None):
+        self.src = src
+        self.axes = axes
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        registry[self.as_] = np.transpose(registry[self.src], self.axes)
+        return registry
+
+
+@Operator
+class Slice:
+    def __init__(self, src: str, at: slice, as_: str | None = None):
+        self.src = src
+        self.at = at
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        registry[self.as_] = registry[self.src][:, self.at]
+        return registry
+
+
+@Operator
+class GatherRows:
+    def __init__(self, src: str, indices: str, as_: str | None = None):
+        self.src = src
+        self.indices = indices
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        src = registry[self.src]
+        idx = registry[self.indices]
+        registry[self.as_] = src[np.arange(src.shape[0]), idx]
+        return registry
+
+
+GatherScores = GatherRows
+
+
+@Operator
+class TopK:
+    def __init__(self, src: str, k: int, values_as: str = "top_values", indices_as: str = "top_indices"):
+        self.src = src
+        self.k = k
+        self.values_as = values_as
+        self.indices_as = indices_as
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        values = registry[self.src]
+        if values.ndim != 1:
+            raise ValueError(f"TopK expects a 1D tensor, got shape {values.shape}")
+        size = int(values.shape[0])
+        top_k = min(self.k, size)
+        if top_k == 0:
+            registry[self.values_as] = values[:0]
+            registry[self.indices_as] = np.zeros((0,), dtype=np.int64)
+            return registry
+        top_indices = np.argpartition(values, -top_k)[-top_k:]
+        order = np.argsort(values[top_indices])[::-1]
+        top_indices = top_indices[order].astype(np.int64, copy=False)
+        registry[self.values_as] = values[top_indices]
+        registry[self.indices_as] = top_indices
+        return registry
+
+
+@Operator
+class TopKIndices2D:
+    def __init__(
+        self,
+        src: str,
+        k: int,
+        values_as: str = "top_values",
+        row_indices_as: str = "row_indices",
+        col_indices_as: str = "col_indices",
+    ):
+        self.src = src
+        self.k = k
+        self.values_as = values_as
+        self.row_indices_as = row_indices_as
+        self.col_indices_as = col_indices_as
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        values = registry[self.src]
+        if values.ndim != 2:
+            raise ValueError(f"TopKIndices2D expects a 2D tensor, got shape {values.shape}")
+        rows, cols = values.shape
+        flat = values.reshape(-1)
+        top_k = min(self.k, int(flat.shape[0]))
+        if top_k == 0:
+            registry[self.values_as] = flat[:0]
+            registry[self.row_indices_as] = np.zeros((0,), dtype=np.int64)
+            registry[self.col_indices_as] = np.zeros((0,), dtype=np.int64)
+            return registry
+        top_indices = np.argpartition(flat, -top_k)[-top_k:]
+        order = np.argsort(flat[top_indices])[::-1]
+        top_indices = top_indices[order].astype(np.int64, copy=False)
+        registry[self.values_as] = flat[top_indices]
+        registry[self.row_indices_as] = (top_indices // cols).astype(np.int64, copy=False)
+        registry[self.col_indices_as] = (top_indices % cols).astype(np.int64, copy=False)
+        return registry
+
+
+@Operator
+class ArgMax:
+    def __init__(self, src: str, axis: int = -1, as_: str | None = None):
+        self.src = src
+        self.axis = axis
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        tensor = registry[self.src]
+        axis = _normalize_axis(self.axis, tensor.ndim)
+        if tensor.shape[axis] == 0:
+            registry[self.as_] = np.zeros(_shape_without_axis(tensor.shape, axis), dtype=np.int32)
+            return registry
+        registry[self.as_] = np.argmax(tensor, axis=axis).astype(np.int32)
+        return registry
+
+
+@Operator
+class Softmax:
+    def __init__(self, src: str, axis: int = -1, as_: str | None = None):
+        self.src = src
+        self.axis = axis
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        x = registry[self.src]
+        axis = _normalize_axis(self.axis, x.ndim)
+        if x.shape[axis] == 0:
+            registry[self.as_] = x.copy()
+            return registry
+        shifted = x - np.max(x, axis=axis, keepdims=True)
+        exp = np.exp(shifted)
+        registry[self.as_] = exp / np.sum(exp, axis=axis, keepdims=True)
+        return registry
+
+
+@Operator
+class Sigmoid:
+    def __init__(self, src: str, as_: str | None = None):
+        self.src = src
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        x = registry[self.src]
+        positive = x >= 0
+        result = np.empty_like(x)
+        result[positive] = 1.0 / (1.0 + np.exp(-x[positive]))
+        exp_values = np.exp(x[~positive])
+        result[~positive] = exp_values / (1.0 + exp_values)
+        registry[self.as_] = result
+        return registry
+
+
+@Operator
+class MultiplyTensors:
+    def __init__(self, left: str, right: str, as_: str | None = None):
+        self.left = left
+        self.right = right
+        self.as_ = as_ or left
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        registry[self.as_] = registry[self.left] * registry[self.right]
+        return registry
+
+
+@Operator
+class CreateTensorMask:
+    def __init__(self, src: str, predicate: Callable[[np.ndarray], TensorMask], as_: str):
+        self.src = src
+        self.as_ = as_
+        self.predicate = predicate
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        registry[self.as_] = np.asarray(self.predicate(registry[self.src]), dtype=bool)
+        return registry
+
+
+BinarizeTensor = CreateTensorMask
+
+
+@Operator
+class CreateTensorMaskByThreshold:
+    def __init__(self, src: str, threshold: float, as_: str | None = None):
+        self._inner = CreateTensorMask(
+            src=src,
+            as_=as_ or src,
+            predicate=lambda tensor: tensor >= threshold,
+        )
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        return self._inner(registry)
+
+
+BinarizeTensorByThreshold = CreateTensorMaskByThreshold
+
+
+@Operator
+class ApplyTensorMask:
+    def __init__(self, *srcs: str, mask: str, as_: str | tuple[str, ...] | None = None):
+        self.srcs = srcs
+        self.mask = mask
+        self.dst_names = resolve_multi_output_names("ApplyTensorMask", srcs, as_)
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        mask = registry[self.mask]
+        for src, dst in zip(self.srcs, self.dst_names, strict=True):
+            registry[dst] = registry[src][mask]
+        return registry
+
+
+@Operator
+class SelectTensors:
+    def __init__(self, *srcs: str, indices: str, as_: str | tuple[str, ...] | None = None):
+        self.srcs = srcs
+        self.indices = indices
+        self.dst_names = resolve_multi_output_names("SelectTensors", srcs, as_)
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        indices = registry[self.indices]
+        if np.issubdtype(indices.dtype, np.bool_):
+            raise TypeError("SelectTensors indices must be integers; use ApplyTensorMask for boolean masks.")
+        for src, dst in zip(self.srcs, self.dst_names, strict=True):
+            registry[dst] = registry[src][indices]
+        return registry
+
+
+@Operator
+class FilterTensors:
+    def __init__(
+        self,
+        *srcs: str,
+        by: str,
+        predicate: Callable[[np.ndarray], TensorMask],
+        as_: str | tuple[str, ...] | None = None,
+    ):
+        self.srcs = srcs
+        self.by = by
+        self.predicate = predicate
+        self.dst_names = resolve_multi_output_names("FilterTensors", srcs, as_)
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        mask = np.asarray(self.predicate(registry[self.by]))
+        if not np.issubdtype(mask.dtype, np.bool_):
+            raise TypeError("FilterTensors predicate must return a boolean mask.")
+        for src, dst in zip(self.srcs, self.dst_names, strict=True):
+            registry[dst] = registry[src][mask]
+        return registry
+
+
+@Operator
+class MapTensor:
+    def __init__(self, src: str, fn: Callable[[np.ndarray], np.ndarray], as_: str | None = None):
+        self.src = src
+        self.fn = fn
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        registry[self.as_] = self.fn(registry[self.src])
+        return registry
+
+
+@Operator
+class SortTensorsBy:
+    def __init__(
+        self,
+        *srcs: str,
+        by: str,
+        descending: bool = True,
+        as_: str | tuple[str, ...] | None = None,
+    ):
+        all_srcs = (by,) + tuple(src for src in srcs if src != by)
+        self.srcs = all_srcs
+        self.by = by
+        self.descending = descending
+        self.dst_names = resolve_multi_output_names("SortTensorsBy", all_srcs, as_)
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        order = np.argsort(registry[self.by])
+        if self.descending:
+            order = order[::-1]
+        for src, dst in zip(self.srcs, self.dst_names, strict=True):
+            registry[dst] = registry[src][order]
+        return registry
+
+
+@Operator
+class Collate:
+    def __call__(self, tensors: list[TensorPayload]) -> TensorPayload:
+        if not tensors:
+            raise ValueError("Collate received an empty list")
+        arrays = [t.array for t in tensors]
+        if arrays[0].ndim == 4 and arrays[0].shape[0] == 1:
+            batched = np.concatenate(arrays, axis=0)
+        else:
+            batched = np.stack(arrays, axis=0)
+        return TensorPayload(array=batched, layout=tensors[0].layout, dtype=tensors[0].dtype)
+
+
+@Operator
+class Scale:
+    def __init__(self, src: str, by: float | tuple | list, as_: str | None = None):
+        self.src = src
+        self.by = np.asarray(by)
+        self.as_ = as_ or src
+
+    def __call__(self, registry: TensorRegistry) -> TensorRegistry:
+        tensor = registry[self.src]
+        registry[self.as_] = tensor * self.by.astype(tensor.dtype)
+        return registry

ml_pipes_tensor-0.1.0rc2/src/ml_pipes/tensor/types.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = [
+    "TensorPayload",
+    "TensorRegistry",
+]
+
+
+@dataclass(frozen=True)
+class TensorPayload:
+    array: np.ndarray
+    layout: str
+    dtype: str
+
+
+class TensorRegistry:
+    """Mutable named store for intermediate tensors during post-processing."""
+
+    def __init__(self, tensors: dict[str, np.ndarray] | None = None):
+        self._tensors: dict[str, np.ndarray] = dict(tensors) if tensors else {}
+
+    def __getitem__(self, name: str) -> np.ndarray:
+        try:
+            return self._tensors[name]
+        except KeyError:
+            available = sorted(self._tensors)
+            raise KeyError(f"Tensor {name!r} not found in registry. Available: {available}")
+
+    def __setitem__(self, name: str, value: np.ndarray) -> None:
+        self._tensors[name] = value
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tensors
+
+    def keys(self) -> object:
+        return self._tensors.keys()
+
+    def __repr__(self) -> str:
+        shapes = {k: v.shape for k, v in self._tensors.items()}
+        return f"TensorRegistry({shapes})"