Source code for nvalchemi.data.transforms.compose

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# 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.
"""Left-to-right composition helper for user-supplied data transforms.

A single :class:`Compose` class handles either per-sample transforms
(:data:`~nvalchemi._typing.SampleTransform`, taking and returning
``(AtomicData, metadata)``) or per-batch transforms
(:data:`~nvalchemi._typing.BatchTransform`, taking and returning
:class:`~nvalchemi.data.Batch`). The composition kind is fixed at
construction by inspecting each callable's type annotations; mixing
sample and batch transforms in the same :class:`Compose` is rejected.

Transforms must *return* their (possibly mutated) output; in-place
mutation without returning is not supported.
"""

from __future__ import annotations

import inspect
from typing import Any, Literal, Sequence, get_type_hints

from plum import dispatch, overload

from nvalchemi._typing import BatchTransform, SampleTransform
from nvalchemi.data.atomic_data import AtomicData
from nvalchemi.data.batch import Batch

TransformKind = Literal["sample", "batch"]


def _gate_transforms(
    transforms: Sequence[SampleTransform | BatchTransform],
) -> TransformKind | None:
    """Validate ``transforms`` and determine the composition kind.

    For each callable, if type hints are available the first positional
    parameter's annotation is inspected: :class:`AtomicData` marks a
    sample transform, :class:`Batch` marks a batch transform, anything
    else raises :class:`TypeError`. Untyped callables are skipped (no
    classification contribution). After all callables are processed,
    the typed ones must agree on a single kind, or :class:`TypeError`
    is raised.

    Parameters
    ----------
    transforms : Sequence[SampleTransform | BatchTransform]
        Callables to validate.

    Returns
    -------
    {"sample", "batch"} or None
        The composition kind, or ``None`` if no callable carried
        classifiable annotations (empty input or every entry untyped).

    Raises
    ------
    TypeError
        If a callable is not callable, carries a typed first parameter
        that is neither :class:`AtomicData` nor :class:`Batch`, or if
        typed callables disagree on the composition kind.
    """
    kind: TransformKind | None = None
    classifying_index: int | None = None

    for i, fn in enumerate(transforms):
        if not callable(fn):
            raise TypeError(
                f"Compose: transform at index {i} is not callable: "
                f"got {type(fn).__name__}"
            )

        # Resolve annotations. For non-function callables (e.g., class
        # instances with __call__), descend into __call__.
        hint_source: Any = fn
        if not (
            inspect.isfunction(fn) or inspect.ismethod(fn) or inspect.isbuiltin(fn)
        ):
            call = getattr(type(fn), "__call__", None)
            if call is not None:
                hint_source = call
        try:
            hints = get_type_hints(hint_source)
        except Exception:
            hints = {}

        try:
            sig = inspect.signature(fn)
        except (TypeError, ValueError):
            continue

        positional = [
            p
            for p in sig.parameters.values()
            if p.kind
            in (
                inspect.Parameter.POSITIONAL_ONLY,
                inspect.Parameter.POSITIONAL_OR_KEYWORD,
            )
        ]
        if not positional:
            continue

        first_name = positional[0].name
        if first_name not in hints:
            # Untyped first parameter: skip this callable entirely.
            continue

        first_ann = hints[first_name]
        if first_ann is AtomicData:
            this_kind: TransformKind = "sample"
        elif first_ann is Batch:
            this_kind = "batch"
        else:
            raise TypeError(
                f"Compose: transform at index {i} ({fn!r}) has typed first "
                f"parameter {first_ann!r}; expected AtomicData (sample "
                f"transform) or Batch (batch transform)"
            )

        if kind is None:
            kind = this_kind
            classifying_index = i
        elif kind != this_kind:
            raise TypeError(
                f"Compose: cannot mix sample and batch transforms; "
                f"transform at index {classifying_index} is {kind!r} but "
                f"transform at index {i} is {this_kind!r}"
            )

    return kind


[docs] class Compose: """Compose a sequence of transforms into a single callable. Transforms are applied left-to-right: the output of transform ``i`` becomes the input to transform ``i + 1``. An empty sequence acts as the identity. A :class:`Compose` is either a *sample* composition or a *batch* composition, inferred at construction from the type annotations of the supplied callables. Each typed callable must declare its first positional parameter as :class:`~nvalchemi.data.AtomicData` (sample transform) or :class:`~nvalchemi.data.Batch` (batch transform); untyped callables are accepted and take on the kind established by the typed ones. Mixing sample and batch transforms in the same :class:`Compose` raises :class:`TypeError`. A composition with no typed callables defaults to sample semantics. Parameters ---------- transforms : Sequence[SampleTransform | BatchTransform] Transforms to compose in application order. Any iterable is accepted and eagerly materialized into an immutable :class:`tuple`. Each entry must be callable. Attributes ---------- transforms : tuple[SampleTransform, ...] | tuple[BatchTransform, ...] The composed transforms, stored in application order. is_batch : bool ``True`` if this is a batch composition, ``False`` if it is a sample composition. ``False`` for an empty / all-untyped composition (defaults to sample semantics). Raises ------ TypeError If any entry is not callable, if a typed first parameter is neither :class:`AtomicData` nor :class:`Batch`, or if typed callables disagree on the composition kind. RuntimeError (At call time) If any transform raises; the original exception is wrapped in a :class:`RuntimeError` identifying the failing index, with the original exception attached via ``__cause__``. Examples -------- Per-sample composition: >>> def shift_positions(data, metadata): # doctest: +SKIP ... new_data = data.model_copy(update={"positions": data.positions + 1.0}) ... return new_data, metadata >>> def tag_origin(data, metadata): # doctest: +SKIP ... metadata["origin"] = "shifted" ... return data, metadata >>> compose = Compose([shift_positions, tag_origin]) # doctest: +SKIP >>> new_data, new_meta = compose(data, {}) # doctest: +SKIP Per-batch composition: >>> def scale_positions(batch): # doctest: +SKIP ... batch.positions = batch.positions * 2.0 ... return batch >>> compose = Compose([scale_positions]) # doctest: +SKIP >>> new_batch = compose(batch) # doctest: +SKIP """ __slots__ = ("transforms", "is_batch") def __init__(self, transforms: Sequence[SampleTransform | BatchTransform]) -> None: self.transforms: tuple[SampleTransform, ...] | tuple[BatchTransform, ...] = ( tuple(transforms) ) kind = _gate_transforms(self.transforms) self.is_batch: bool = kind == "batch" @overload def __call__(self, data: Batch) -> Batch: # noqa: F811 """Apply a batch composition to a :class:`Batch`.""" for i, transform in enumerate(self.transforms): try: data = transform(data) except Exception as e: raise RuntimeError( f"Compose: transform[{i}] ({transform!r}) raised {type(e).__name__}" ) from e return data @overload def __call__( # noqa: F811 self, data: AtomicData, metadata: dict[str, Any] ) -> tuple[AtomicData, dict[str, Any]]: """Apply a sample composition to an ``(AtomicData, metadata)`` pair.""" for i, transform in enumerate(self.transforms): try: data, metadata = transform(data, metadata) except Exception as e: raise RuntimeError( f"Compose: transform[{i}] ({transform!r}) raised {type(e).__name__}" ) from e return data, metadata @dispatch def __call__( # noqa: F811 self, data: AtomicData | Batch, metadata: dict[str, Any] | None = None, ) -> tuple[AtomicData, dict[str, Any]] | Batch: """Apply the composed transforms left-to-right. Parameters ---------- data : AtomicData or Batch For a sample composition, the :class:`AtomicData` sample. For a batch composition, the :class:`Batch`. metadata : dict[str, Any], optional Per-sample metadata dict. Required for sample compositions and must be omitted for batch compositions. Returns ------- tuple[AtomicData, dict[str, Any]] or Batch The output of the final transform. For a sample composition, the ``(data, metadata)`` tuple. For a batch composition, the :class:`Batch`. An empty composition returns its input unchanged (identity). Raises ------ RuntimeError If any transform raises; the message identifies the failing index and the original exception is attached via ``__cause__``. This includes the case where the call argument types do not match the composition kind (e.g., passing a :class:`Batch` to a sample composition), in which case the first transform will typically raise when invoked on the wrong type. """ ... def __repr__(self) -> str: """Return a developer-readable representation listing the transforms.""" return f"Compose({list(self.transforms)!r})"