arraybridge 0.2.10__tar.gz → 0.2.11__tar.gz

arraybridge-0.2.11/.github/badges/coverage.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 75.14%"><title>coverage: 75.14%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">75.14%</text><text x="865" y="150" fill-opacity=".3" textLength="430">75.14%</text></g><text x="865" y="140" textLength="430">75.14%</text></g></g></svg>

{arraybridge-0.2.10 → arraybridge-0.2.11}/ADDING_NEW_FRAMEWORKS.md

@@ -99,13 +99,15 @@ converter = MemoryType.MXNET.converter
 class MxnetConverter(MemoryTypeConverter):
     def to_numpy(self, data, gpu_id):
         return data.asnumpy()
+
     def from_numpy(self, data, gpu_id):
         return mxnet.nd.array(data)
+
     def to_torch(self, data, gpu_id):
-        # ... manual implementation
+        raise NotImplementedError
+
     def to_cupy(self, data, gpu_id):
-        # ... manual implementation
-    # ... 6+ more methods
+        raise NotImplementedError
 
 # Had to manually register
 _CONVERTERS[MemoryType.MXNET] = MxnetConverter()
@@ -113,8 +115,10 @@ _CONVERTERS[MemoryType.MXNET] = MxnetConverter()
 
 ### After (Auto-registration - New System)
 ```python
-# Just add to enum and config - everything else is automatic!
-MemoryType.MXNET = "mxnet"
+# Add one enum member and one config entry; everything else is automatic.
+class MemoryType(Enum):
+    # Existing members omitted.
+    MXNET = "mxnet"
 
 _FRAMEWORK_CONFIG[MemoryType.MXNET] = {
     'conversion_ops': {
@@ -160,7 +164,7 @@ def test_convert_numpy_to_mxnet(self, mxnet_available):
 
 ### GPU Framework with DLPack
 ```python
-'conversion_ops': {
+conversion_ops = {
     'to_numpy': 'data.cpu().numpy()',
     'from_numpy': '{mod}.from_numpy(data).to(device=gpu_id)',
     'from_dlpack': '{mod}.from_dlpack(data)',
@@ -170,7 +174,7 @@ def test_convert_numpy_to_mxnet(self, mxnet_available):
 
 ### CPU-only Framework
 ```python
-'conversion_ops': {
+conversion_ops = {
     'to_numpy': 'np.array(data)',
     'from_numpy': '{mod}.array(data)',
     'from_dlpack': None,  # Not supported

{arraybridge-0.2.10 → arraybridge-0.2.11}/CONTRIBUTING.md

@@ -35,7 +35,7 @@ We are committed to providing a welcoming and inclusive environment. Please be r
 
 ### Finding Issues
 
-- Check the [issue tracker](https://github.com/trissim/arraybridge/issues)
+- Check the [issue tracker](https://github.com/OpenHCSDev/arraybridge/issues)
 - Look for issues labeled `good first issue` or `help wanted`
 - Feel free to create new issues for bugs or feature requests
 
@@ -49,7 +49,7 @@ git clone https://github.com/YOUR_USERNAME/arraybridge.git
 cd arraybridge
 
 # Add upstream remote
-git remote add upstream https://github.com/trissim/arraybridge.git
+git remote add upstream https://github.com/OpenHCSDev/arraybridge.git
 ```
 
 ### 2. Create Virtual Environment
@@ -135,13 +135,11 @@ def convert_memory(data: Any, source_type: str, target_type: str, gpu_id: int) -
         MemoryConversionError: If conversion fails
 
     Example:
-        ```python
         import numpy as np
         from arraybridge import convert_memory
 
         data = np.array([1, 2, 3])
         result = convert_memory(data, "numpy", "torch", gpu_id=0)
-        ```
     """
 ```
 

arraybridge-0.2.11/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: arraybridge
+Version: 0.2.11
+Summary: Unified API for NumPy, CuPy, PyTorch, TensorFlow, JAX, and pyclesperanto with automatic memory type conversion
+Project-URL: Homepage, https://github.com/OpenHCSDev/arraybridge
+Project-URL: Documentation, https://arraybridge.readthedocs.io
+Project-URL: Repository, https://github.com/OpenHCSDev/arraybridge
+Project-URL: Issues, https://github.com/OpenHCSDev/arraybridge/issues
+Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
+License: MIT
+License-File: LICENSE
+Keywords: array,conversion,cupy,gpu,jax,numpy,pytorch,tensor,tensorflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: metaclass-registry>=0.1.5
+Requires-Dist: numpy>=1.20
+Provides-Extra: all
+Requires-Dist: cupy>=10.0; extra == 'all'
+Requires-Dist: jax>=0.3; extra == 'all'
+Requires-Dist: jaxlib>=0.3; extra == 'all'
+Requires-Dist: pyclesperanto>=0.10; extra == 'all'
+Requires-Dist: tensorflow>=2.8; extra == 'all'
+Requires-Dist: torch>=1.10; extra == 'all'
+Provides-Extra: cupy
+Requires-Dist: cupy>=10.0; extra == 'cupy'
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: gpu
+Requires-Dist: cucim-cu12<26.0.0,>=25.6.0; extra == 'gpu'
+Requires-Dist: cupy-cuda12x<14.0.0,>=13.3.0; extra == 'gpu'
+Requires-Dist: jax-cuda12-pjrt<0.6.0,>=0.5.3; extra == 'gpu'
+Requires-Dist: jax-cuda12-plugin<0.6.0,>=0.5.3; extra == 'gpu'
+Requires-Dist: jax<0.6.0,>=0.5.3; extra == 'gpu'
+Requires-Dist: jaxlib<0.6.0,>=0.5.3; extra == 'gpu'
+Requires-Dist: pyclesperanto>=0.17.1; extra == 'gpu'
+Requires-Dist: tensorflow-probability[tf]<0.26.0,>=0.25.0; extra == 'gpu'
+Requires-Dist: tensorflow<2.20.0,>=2.19.0; extra == 'gpu'
+Requires-Dist: torch<2.8.0,>=2.6.0; extra == 'gpu'
+Requires-Dist: torchvision<0.23.0,>=0.21.0; extra == 'gpu'
+Provides-Extra: jax
+Requires-Dist: jax>=0.3; extra == 'jax'
+Requires-Dist: jaxlib>=0.3; extra == 'jax'
+Provides-Extra: pyclesperanto
+Requires-Dist: pyclesperanto>=0.10; extra == 'pyclesperanto'
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow>=2.8; extra == 'tensorflow'
+Provides-Extra: torch
+Requires-Dist: torch>=1.10; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# arraybridge
+
+ArrayBridge provides explicit conversion and shared lifecycle utilities for
+NumPy, CuPy, PyTorch, TensorFlow, JAX, and pyclesperanto arrays.
+
+Core dependencies are NumPy and metaclass-registry. Other frameworks are
+optional.
+
+## Quick start
+
+```python
+import numpy as np
+
+from arraybridge import convert_memory, detect_memory_type
+
+value = np.arange(6).reshape(2, 3)
+assert detect_memory_type(value) == "numpy"
+
+copy = convert_memory(
+    value,
+    source_type="numpy",
+    target_type="numpy",
+    gpu_id=0,
+)
+```
+
+`convert_memory` requires the declared source type, target type, and device id.
+It uses the registered converter for the source framework. The device id is
+required even for CPU conversions so call sites have one stable signature.
+
+## Declarative decorators
+
+```python
+from arraybridge import numpy
+
+@numpy
+def normalize(image):
+    return image / max(float(image.max()), 1.0)
+```
+
+The framework decorators attach `input_memory_type` and `output_memory_type`
+metadata, provide dtype/slice runtime parameters, and add framework-specific
+stream/OOM handling where supported. They do **not** convert inputs or outputs
+between frameworks and do not accept a `gpu_id` argument. A host runtime must
+call `convert_memory` at the boundary it plans.
+
+## Stack utilities
+
+```python
+import numpy as np
+
+from arraybridge import stack_slices, unstack_slices
+
+slices = [np.zeros((8, 8)), np.ones((8, 8))]
+stack = stack_slices(slices, memory_type="numpy", gpu_id=0)
+restored = unstack_slices(stack, memory_type="numpy", gpu_id=0)
+```
+
+`stack_slices` requires non-empty 2D inputs. `unstack_slices` requires a 3D
+array. Both validate shape and use explicit target memory/device declarations.
+
+## Installation
+
+```bash
+pip install arraybridge
+pip install "arraybridge[torch]"
+pip install "arraybridge[cupy]"
+```
+
+Documentation: <https://arraybridge.readthedocs.io>

arraybridge-0.2.11/README.md

@@ -0,0 +1,70 @@
+# arraybridge
+
+ArrayBridge provides explicit conversion and shared lifecycle utilities for
+NumPy, CuPy, PyTorch, TensorFlow, JAX, and pyclesperanto arrays.
+
+Core dependencies are NumPy and metaclass-registry. Other frameworks are
+optional.
+
+## Quick start
+
+```python
+import numpy as np
+
+from arraybridge import convert_memory, detect_memory_type
+
+value = np.arange(6).reshape(2, 3)
+assert detect_memory_type(value) == "numpy"
+
+copy = convert_memory(
+    value,
+    source_type="numpy",
+    target_type="numpy",
+    gpu_id=0,
+)
+```
+
+`convert_memory` requires the declared source type, target type, and device id.
+It uses the registered converter for the source framework. The device id is
+required even for CPU conversions so call sites have one stable signature.
+
+## Declarative decorators
+
+```python
+from arraybridge import numpy
+
+@numpy
+def normalize(image):
+    return image / max(float(image.max()), 1.0)
+```
+
+The framework decorators attach `input_memory_type` and `output_memory_type`
+metadata, provide dtype/slice runtime parameters, and add framework-specific
+stream/OOM handling where supported. They do **not** convert inputs or outputs
+between frameworks and do not accept a `gpu_id` argument. A host runtime must
+call `convert_memory` at the boundary it plans.
+
+## Stack utilities
+
+```python
+import numpy as np
+
+from arraybridge import stack_slices, unstack_slices
+
+slices = [np.zeros((8, 8)), np.ones((8, 8))]
+stack = stack_slices(slices, memory_type="numpy", gpu_id=0)
+restored = unstack_slices(stack, memory_type="numpy", gpu_id=0)
+```
+
+`stack_slices` requires non-empty 2D inputs. `unstack_slices` requires a 3D
+array. Both validate shape and use explicit target memory/device declarations.
+
+## Installation
+
+```bash
+pip install arraybridge
+pip install "arraybridge[torch]"
+pip install "arraybridge[cupy]"
+```
+
+Documentation: <https://arraybridge.readthedocs.io>

{arraybridge-0.2.10 → arraybridge-0.2.11}/SETUP_INSTRUCTIONS.md

@@ -6,17 +6,17 @@ This document contains the manual steps needed to complete the badge and documen
 
 To display the coverage reports hosted on GitHub Pages:
 
-1. Go to: https://github.com/trissim/arraybridge/settings/pages
+1. Go to: https://github.com/OpenHCSDev/arraybridge/settings/pages
 2. Under "Build and deployment" > "Source", select **"GitHub Actions"**
 3. Save the changes
 
-Once enabled, the coverage-pages.yml workflow will deploy coverage reports to https://trissim.github.io/arraybridge/coverage/
+Once enabled, the coverage-pages.yml workflow will deploy coverage reports to https://openhcsdev.github.io/arraybridge/coverage/
 
 ## 2. Update Repository Description
 
 To add the ReadTheDocs link to the repository description:
 
-1. Go to: https://github.com/trissim/arraybridge
+1. Go to: https://github.com/OpenHCSDev/arraybridge
 2. Click the gear icon (⚙️) next to "About" on the right side
 3. In the "Website" field, enter: `https://arraybridge.readthedocs.io`
 4. Optionally add topics/tags to improve discoverability
@@ -55,7 +55,7 @@ After merging this PR to main:
 The following badges have been added to README.md:
 
 - **ReadTheDocs**: `[![Documentation Status](https://readthedocs.org/projects/arraybridge/badge/?version=latest)](https://arraybridge.readthedocs.io/en/latest/?badge=latest)`
-- **Coverage**: `[![Coverage](https://raw.githubusercontent.com/trissim/arraybridge/main/.github/badges/coverage.svg)](https://trissim.github.io/arraybridge/coverage/)`
+- **Coverage**: `[![Coverage](https://raw.githubusercontent.com/OpenHCSDev/arraybridge/main/.github/badges/coverage.svg)](https://openhcsdev.github.io/arraybridge/coverage/)`
 
 ## Notes
 

{arraybridge-0.2.10 → arraybridge-0.2.11/docs/archive}/CI_IMPROVEMENTS.md

@@ -190,4 +190,3 @@ If issues arise, revert to previous CI by:
 ## Questions?
 
 See `TESTING.md` for detailed testing documentation.
-

arraybridge-0.2.11/docs/archive/README.md

@@ -0,0 +1,5 @@
+# Archived ArrayBridge notes
+
+These CI incident reports, migration summaries, conflict guides, and dated
+coverage plans are superseded history. Use `README.md`, `CONTRIBUTING.md`,
+`TESTING.md`, and the active Sphinx site under `docs/source/`.

arraybridge-0.2.11/docs/ci-cd.md

@@ -0,0 +1,7 @@
+# CI/CD documentation
+
+The maintained CI/CD documentation is
+[`source/ci-cd.rst`](source/ci-cd.rst). It deliberately links to the current
+[GitHub Actions workflows](https://github.com/OpenHCSDev/arraybridge/actions)
+instead of duplicating a version matrix or release procedure that can drift
+from the workflow files.

arraybridge-0.2.11/docs/source/README.md

@@ -0,0 +1,15 @@
+# ArrayBridge documentation source
+
+The active Sphinx source is this directory.
+
+From the repository root:
+
+```bash
+python -m pip install -e ".[docs]"
+python -m sphinx -E -W --keep-going -b html docs/source docs/source/_build/html
+```
+
+Narrative pages document public behavior and ownership. `api_reference.rst`
+tracks the root export surface. Keep code examples valid under
+`scripts/validate_docs.py` in the OpenHCS superproject and verify signatures
+against `src/arraybridge/` when public APIs change.

arraybridge-0.2.11/docs/source/advanced_topics.rst

@@ -0,0 +1,20 @@
+Advanced extension topics
+=========================
+
+Framework behavior is centralized in the registered conversion and framework
+strategy families. Add a new framework by extending those owning declarations:
+
+1. add the ``MemoryType`` member;
+2. provide framework configuration and conversion strategies;
+3. define stack/allocation/device behavior where it differs;
+4. add cleanup and OOM behavior only when the framework supports them;
+5. exercise detection and every supported conversion pair.
+
+Do not add a parallel framework-name table in a consumer. Generic consumers use
+``MemoryType``, the converter registry, and framework configuration owned by
+ArrayBridge.
+
+Conversion caching and batching belong to the caller because value lifetime and
+semantic identity are application concerns. ArrayBridge functions remain
+stateless at the conversion boundary except for declared thread-local GPU
+context.

arraybridge-0.2.11/docs/source/api_reference.rst

@@ -0,0 +1,38 @@
+API reference
+=============
+
+Public imports
+--------------
+
+``MemoryType``, ``CPU_MEMORY_TYPES``, ``GPU_MEMORY_TYPES``, ``SUPPORTED_MEMORY_TYPES``
+  Nominal framework identities.
+
+``detect_memory_type`` and ``convert_memory``
+  Detection and explicit conversion.
+
+``memory_types``, ``numpy``, ``cupy``, ``torch``, ``tensorflow``, ``jax``, ``pyclesperanto``
+  Callable memory declarations and wrappers.
+
+``DtypeConversion``
+  Output dtype policy values.
+
+``stack_slices``, ``unstack_slices``, ``process_slices``
+  Validated plane/stack operations.
+
+``cleanup_all_gpu_frameworks``
+  Installed-framework cache cleanup.
+
+``MemoryConversionError``
+  Conversion failure boundary.
+
+The canonical export list is ``arraybridge.__all__``. Names beginning with an
+underscore are implementation surfaces even when temporarily re-exported for a
+host migration.
+
+Documented public surface
+-------------------------
+
+.. automodule:: arraybridge
+   :members:
+   :exclude-members: _FRAMEWORK_CONFIG, _FRAMEWORK_OPS, _ensure_module, _execute_with_oom_recovery, _get_device_id, _supports_dlpack
+   :member-order: bysource

arraybridge-0.2.11/docs/source/ci-cd.rst

@@ -0,0 +1,25 @@
+Continuous integration
+======================
+
+The repository workflows are authoritative. The main test matrix currently
+covers Python 3.10 through 3.13 on Linux, Windows, and macOS. Separate jobs
+exercise optional GPU paths and code quality.
+
+Before opening a change, run:
+
+.. code-block:: bash
+
+   python -m pytest
+   ruff check src tests
+   black --check src tests
+   mypy src --ignore-missing-imports
+
+Documentation changes should also build with warnings as errors:
+
+.. code-block:: bash
+
+   python -m sphinx -E -W --keep-going -b html docs/source docs/source/_build/html
+
+See the current `GitHub Actions workflows
+<https://github.com/OpenHCSDev/arraybridge/actions>`_ instead of copying a
+workflow matrix into downstream documentation.

{arraybridge-0.2.10 → arraybridge-0.2.11}/docs/source/conf.py

@@ -5,7 +5,16 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../src'))
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+EXTERNAL_ROOT = PACKAGE_ROOT.parent
+
+# Prefer the sibling owner source when ArrayBridge is documented from the
+# OpenHCS checkout; an installed metaclass-registry remains the standalone
+# fallback when that sibling is absent.
+sys.path.insert(0, str(EXTERNAL_ROOT / "metaclass-registry" / "src"))
+sys.path.insert(0, str(PACKAGE_ROOT / "src"))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -13,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../../src'))
 project = 'arraybridge'
 copyright = '2025, Tristan Simas'
 author = 'Tristan Simas'
-release = '0.1.0'
+release = '0.2.11'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -29,13 +38,13 @@ extensions = [
 ]
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'api/**']
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_static_path = []
 
 # -- Extension configuration -------------------------------------------------
 
@@ -114,7 +123,6 @@ html_theme_options = {
     'sticky_navigation': True,
     'includehidden': True,
     'titles_only': False,
-    'display_version': True,
     'prev_next_buttons_location': 'both',
     'style_external_links': False,
 }

arraybridge-0.2.11/docs/source/contributing.rst

@@ -0,0 +1,27 @@
+Contributing
+============
+
+Install the editable development environment and run the same core checks used
+by the repository:
+
+.. code-block:: bash
+
+   python -m pip install -e ".[dev,docs]"
+   ruff check src tests
+   black --check src tests
+   mypy src --ignore-missing-imports
+   python -m pytest
+   python -m sphinx -E -W --keep-going -b html docs/source docs/source/_build/html
+
+Framework extensions
+--------------------
+
+A framework extension must update the nominal ``MemoryType`` declaration and
+the owning conversion/framework strategies. Add detection tests, conversion
+pair tests, stack tests, and optional-dependency behavior. Consumers should not
+maintain a second framework-name registry.
+
+See :doc:`advanced_topics` for the ownership model and the repository's
+`contribution guide
+<https://github.com/OpenHCSDev/arraybridge/blob/main/CONTRIBUTING.md>`_ for the
+review workflow.

arraybridge-0.2.11/docs/source/converters.rst

@@ -0,0 +1,36 @@
+Conversion system
+=================
+
+``convert_memory(data, source_type, target_type, gpu_id)`` selects the converter
+registered for ``source_type`` and invokes its target method.
+
+.. code-block:: python
+
+   import numpy as np
+
+   from arraybridge import convert_memory
+
+   value = np.arange(4)
+   result = convert_memory(value, "numpy", "numpy", 0)
+
+Call ``detect_memory_type`` when the source type is not already known. Passing a
+wrong source declaration is a caller error; conversion planning should keep the
+declared type aligned with the actual value.
+
+Device semantics
+----------------
+
+``gpu_id`` is required. GPU converters use it for allocation or device
+selection. CPU conversion accepts the same argument for a uniform API. Moving a
+value between two devices is expressed as conversion with the target device id.
+
+Converters prefer framework-native or DLPack paths when the registered strategy
+supports them and otherwise use the strategy's explicit fallback. No zero-copy
+guarantee applies to every pair.
+
+Failures
+--------
+
+Invalid framework names raise ``ValueError``. Conversion failures raise
+``MemoryConversionError`` with source/target context. Optional frameworks are
+loaded only when their converter is used.

arraybridge-0.2.11/docs/source/decorators.rst

@@ -0,0 +1,40 @@
+Memory declaration decorators
+=============================
+
+``memory_types`` and the six framework helpers declare callable memory
+contracts.
+
+.. code-block:: python
+
+   from arraybridge import memory_types, numpy
+
+   @memory_types(input_type="numpy", output_type="numpy")
+   def identity(image):
+       return image
+
+   @numpy(oom_recovery=False)
+   def offset(image, value=1):
+       return image + value
+
+Framework helpers accept ``input_type``, ``output_type``, ``oom_recovery``, and
+``contract``. They may be used as ``@numpy`` or ``@numpy()``.
+
+Direct-call behavior
+--------------------
+
+Decorators do not convert the input or output between frameworks. They attach
+metadata, add keyword-only ``slice_by_slice`` and ``dtype_config`` runtime
+parameters, apply the selected dtype policy, and wrap supported GPU frameworks
+with thread-local stream/OOM handling.
+
+The decorator does not accept ``gpu_id`` or ``clear_cuda_cache``. Device
+selection belongs to explicit conversion or the host runtime. A non-callable
+``contract`` is stored as declarative metadata; a callable contract validates
+the returned value.
+
+Dtype policy
+------------
+
+Direct calls default to preserving the input dtype. Hosts can pass an object
+implementing ``DtypeConversionConfig`` to select native or explicit output dtype
+behavior.

arraybridge-0.2.11/docs/source/examples/basic_conversion.rst

@@ -0,0 +1,16 @@
+Basic conversion
+================
+
+.. code-block:: python
+
+   import numpy as np
+
+   from arraybridge import convert_memory, detect_memory_type
+
+   source = np.arange(9).reshape(3, 3)
+   source_type = detect_memory_type(source)
+   result = convert_memory(source, source_type, "numpy", 0)
+
+For an optional target such as ``torch`` or ``cupy``, install that framework and
+replace the target string. The returned value is allocated according to the
+registered converter and requested device.

arraybridge-0.2.11/docs/source/examples/decorators.rst

@@ -0,0 +1,18 @@
+Decorator declarations
+======================
+
+.. code-block:: python
+
+   import numpy as np
+
+   from arraybridge import numpy
+
+   @numpy
+   def threshold(image, *, cutoff=0.5):
+       return image > cutoff
+
+   value = threshold(np.array([0.25, 0.75]))
+   assert threshold.input_memory_type == "numpy"
+
+The caller supplies the NumPy value. A compiler or orchestration layer may use
+the metadata to plan conversion before calling ``threshold``.

arraybridge-0.2.11/docs/source/examples/multi_framework.rst

@@ -0,0 +1,18 @@
+Multi-framework boundary
+========================
+
+Keep conversion visible at the point that owns the boundary:
+
+.. code-block:: python
+
+   from arraybridge import convert_memory, detect_memory_type
+
+   def as_framework(value, target, gpu_id):
+       source = detect_memory_type(value)
+       if source == target:
+           return value
+       return convert_memory(value, source, target, gpu_id)
+
+For a sequence of framework-specific functions, a host compiler should read
+their declared input/output memory types and create one conversion plan. The
+functions themselves should not each guess the incoming framework.