Skip to content

pixano_inference.frameworks.base

Framework adapter protocol and registry.

pixano-inference is framework-agnostic: the core depends on numpy only, and each ML framework (PyTorch, JAX, TensorFlow, MLX) is an optional extra reached through an adapter. An adapter gives a model author framework-neutral helpers — device resolution, dtype resolution, and numpy interchange — so a custom model can be written against any supported framework without the core privileging one of them.

numpy is the interchange format: adapters convert their native arrays/tensors to and from numpy.ndarray (zero-copy via DLPack where the framework supports it).

This module imports NO framework at load time. Adapter modules (torch, jax, …) are imported lazily by :func:get_adapter, and each performs its own framework import lazily, so import pixano_inference.frameworks stays dependency-free.

FrameworkAdapter

Bases: Protocol

Framework-neutral operations a model backend needs.

Implementations live in pixano_inference.frameworks.<name> and import their framework lazily.

from_numpy(array, device=None, dtype=None)

Convert a numpy array to a framework array/tensor on device with dtype.

Source code in pixano_inference/frameworks/base.py 
58
59
60
def from_numpy(self, array: "np.ndarray", device: Any = None, dtype: Any = None) -> Any:
    """Convert a numpy array to a framework array/tensor on *device* with *dtype*."""
    ...

is_available()

Whether the underlying framework is importable in this environment.

Source code in pixano_inference/frameworks/base.py 
42
43
44
def is_available(self) -> bool:
    """Whether the underlying framework is importable in this environment."""
    ...

resolve_device(num_gpus)

Return the framework's device object for num_gpus requested GPUs.

Source code in pixano_inference/frameworks/base.py 
46
47
48
def resolve_device(self, num_gpus: float) -> Any:
    """Return the framework's device object for *num_gpus* requested GPUs."""
    ...

resolve_dtype(dtype)

Map a dtype string (e.g. "float32") to the framework's dtype.

Source code in pixano_inference/frameworks/base.py 
50
51
52
def resolve_dtype(self, dtype: str) -> Any:
    """Map a dtype string (e.g. ``"float32"``) to the framework's dtype."""
    ...

to_numpy(array)

Convert a framework array/tensor to a numpy array (host memory).

Source code in pixano_inference/frameworks/base.py 
54
55
56
def to_numpy(self, array: Any) -> "np.ndarray":
    """Convert a framework array/tensor to a numpy array (host memory)."""
    ...

available_frameworks()

Return the names of frameworks whose package is importable in this environment.

Source code in pixano_inference/frameworks/base.py 
103
104
105
106
107
108
109
110
111
112
def available_frameworks() -> list[str]:
    """Return the names of frameworks whose package is importable in this environment."""
    available: list[str] = []
    for name in _ADAPTER_MODULES:
        try:
            if get_adapter(name).is_available():
                available.append(name)
        except Exception:
            continue
    return available

get_adapter(name)

Return the adapter for framework name, importing its module lazily.

Parameters:

Name Type Description Default
name str

Framework name ("torch", "jax", "tensorflow", "mlx").

 required

Returns:

Type Description
The registered

class:FrameworkAdapter.

Raises:

Type Description
ValueError

If name is not a known framework.
Source code in pixano_inference/frameworks/base.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def get_adapter(name: str) -> FrameworkAdapter:
    """Return the adapter for framework *name*, importing its module lazily.

    Args:
        name: Framework name (``"torch"``, ``"jax"``, ``"tensorflow"``, ``"mlx"``).

    Returns:
        The registered :class:`FrameworkAdapter`.

    Raises:
        ValueError: If *name* is not a known framework.
    """
    key = name.lower()
    if key not in _ADAPTERS:
        module_path = _ADAPTER_MODULES.get(key)
        if module_path is None:
            raise ValueError(f"Unknown framework '{name}'. Known: {sorted(_ADAPTER_MODULES)}.")
        import importlib

        importlib.import_module(module_path)
    return _ADAPTERS[key]

register_adapter(adapter)

Register a framework adapter instance (called by adapter modules on import).

Source code in pixano_inference/frameworks/base.py 
75
76
77
def register_adapter(adapter: FrameworkAdapter) -> None:
    """Register a framework adapter instance (called by adapter modules on import)."""
    _ADAPTERS[adapter.name] = adapter