vcti-dataflow 2.0.0__py3-none-any.whl

vcti/flow/data/__init__.py

@@ -0,0 +1,40 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.flow.data — the DataNode binding of vcti.flow.
+
+DataNode-bound node kinds (``Source``, ``Transformer``, ``Reducer``, ``Sink``,
+``Observer``) over the generic ``vcti.flow`` framework, plus ``from_array`` (eager)
+and ``ArraySource`` (lazy) for building ``DataNode`` payloads. Structured-array-
+specific nodes (field merge, row iteration, field shaping) live in the
+``vcti.flow.data.fields`` submodule.
+"""
+
+from importlib.metadata import version
+
+from vcti.datanode import DataNode, EagerDataSource, LazyDataSource
+
+from .aliases import (
+    Observer,
+    Reducer,
+    Sink,
+    Source,
+    Transformer,
+)
+from .record import from_array
+from .sources import ArraySource
+
+__version__ = version("vcti-dataflow")
+
+__all__ = [
+    "__version__",
+    "ArraySource",
+    "DataNode",
+    "EagerDataSource",
+    "LazyDataSource",
+    "Observer",
+    "Reducer",
+    "Sink",
+    "Source",
+    "Transformer",
+    "from_array",
+]

vcti/flow/data/aliases.py

@@ -0,0 +1,27 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""DataNode-bound aliases for the vcti.flow node kinds.
+
+These bind the generic ``vcti.flow`` framework to the ``DataNode`` payload, so
+authors subclass ``Source`` / ``Transformer`` / … — the ``vcti.flow.data``
+spelling of ``Source[DataNode]`` / ``Transformer[DataNode, DataNode]`` — instead
+of repeating the type parameter everywhere. They are plain assignments (not PEP
+695 ``type`` aliases) so they remain usable as base classes.
+
+The names intentionally shadow the generic ``vcti.flow.core`` kinds: within this
+binding ``Source`` *is* ``Source[DataNode]``. Note this ``Source`` is a flow leaf
+node and is unrelated to ``vcti.datanode.DataSource`` — the array-source ABC
+behind the re-exported ``EagerDataSource`` / ``LazyDataSource``. Dropping the
+``Data`` prefix is what keeps that ``DataSource`` name from clashing here.
+"""
+
+from __future__ import annotations
+
+import vcti.flow.core as core
+from vcti.datanode import DataNode
+
+Source = core.Source[DataNode]
+Transformer = core.Transformer[DataNode, DataNode]
+Reducer = core.Reducer[DataNode, DataNode]
+Sink = core.Sink[DataNode]
+Observer = core.Observer[DataNode]

vcti/flow/data/fields/__init__.py

@@ -0,0 +1,41 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.flow.data.fields — nodes for structured-array DataNode payloads.
+
+These assume the DataNode's array is a structured (named-field) array. The base
+``vcti.flow.data`` binding makes no such assumption (its ``ArraySource`` /
+``from_array`` build shape-agnostic payloads).
+
+- Source: ``RowTableSource`` (table from mapping rows) — lazy.
+- Transformers: ``NameFields`` (name plain columns), ``SelectFields`` (select /
+  rename), ``RenameFields`` (rename, keep the rest), ``DropFields`` (drop a
+  subset), ``CastFields`` (change dtypes), ``ComputeFields`` (append / replace
+  computed fields).
+- Reduce: ``MergeFields`` (field-wise merge).
+- Iterate: ``for_each_field`` / ``field_items`` (row-keyed fan-out).
+"""
+
+from .iterate import field_items, for_each_field
+from .merge import MergeFields
+from .sources import RowTableSource
+from .transforms import (
+    CastFields,
+    ComputeFields,
+    DropFields,
+    NameFields,
+    RenameFields,
+    SelectFields,
+)
+
+__all__ = [
+    "CastFields",
+    "ComputeFields",
+    "DropFields",
+    "MergeFields",
+    "NameFields",
+    "RenameFields",
+    "RowTableSource",
+    "SelectFields",
+    "field_items",
+    "for_each_field",
+]

vcti/flow/data/fields/iterate.py

@@ -0,0 +1,48 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Row iteration over a structured-array DataNode, as a flow combinator."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator
+from typing import Any
+
+from vcti.datanode import DataNode
+from vcti.flow.core import Node, for_each
+
+
+def field_items(key_field: str = "ID") -> Callable[[DataNode], Iterable[Any]]:
+    """Return an items-extractor that reads *key_field* from each row.
+
+    Suitable as the ``items`` argument to ``vcti.flow.core.for_each``. The
+    extractor loads the node's array and yields the value of *key_field* per row;
+    an absent or empty array yields nothing.
+
+    Raises:
+        ValueError: If the array is structured and lacks *key_field*.
+    """
+
+    def extract(record: DataNode) -> list[Any]:
+        arr = record.load()
+        if arr is None or arr.shape[0] == 0:
+            return []
+        if arr.dtype.names is not None and key_field not in arr.dtype.names:
+            raise ValueError(
+                f"Key field {key_field!r} not found in source fields {arr.dtype.names}."
+            )
+        return [row[key_field] for row in arr]
+
+    return extract
+
+
+def for_each_field[U](
+    source: Node[DataNode],
+    factory: Callable[[Any], Node[U]],
+    key_field: str = "ID",
+) -> Iterator[tuple[Any, Node[U]]]:
+    """Fan a keys DataNode out into one flow per row, keyed by *key_field*.
+
+    A DataNode-specific convenience over ``vcti.flow.core.for_each``: it yields
+    ``(key, flow)`` pairs, one per row of the source's structured array.
+    """
+    return for_each(source, field_items(key_field), factory)

vcti/flow/data/fields/merge.py

@@ -0,0 +1,53 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""MergeFields — merge structured-array DataNodes field-wise."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from numpy.lib import recfunctions as rfn
+from vcti.datanode import DataNode
+
+from ..aliases import Reducer
+from ..record import from_array
+
+
+class MergeFields(Reducer):
+    """Merge multiple DataNodes into one by combining fields horizontally.
+
+    Arrays are merged field-wise with ``numpy.lib.recfunctions.merge_arrays``.
+    All inputs must have the same number of rows. Attributes merge with
+    **last-wins** semantics. Inputs with no data are skipped; if no input has
+    data, an empty (metadata-only) DataNode is returned.
+
+    Raises:
+        ValueError: If the input arrays have different row counts.
+    """
+
+    def reduce(self, records: list[DataNode]) -> DataNode:
+        loaded = [(d, arr) for d in records if d.has_data and (arr := d.load()) is not None]
+        if not loaded:
+            return from_array()
+
+        arrays = [arr for _, arr in loaded]
+        if len(arrays) > 1:
+            first_length = len(arrays[0])
+            for i, arr in enumerate(arrays[1:], start=1):
+                if len(arr) != first_length:
+                    raise ValueError(
+                        f"Cannot merge arrays with different lengths. Array 0 has "
+                        f"{first_length} rows, but array {i} has {len(arr)} rows."
+                    )
+
+        if len(arrays) == 1:
+            merged = arrays[0]
+        else:
+            merged = rfn.merge_arrays(arrays, flatten=True, usemask=False)
+
+        combined: dict[str, Any] = {}
+        for d, _ in loaded:
+            if d.attributes:
+                combined.update(d.attributes)
+
+        return from_array(merged, combined or None)

vcti/flow/data/fields/sources.py

@@ -0,0 +1,94 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Leaf source that builds a structured-array DataNode from mapping rows (lazily)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+import numpy as np
+from vcti.datanode import DataNode, LazyDataSource
+
+from ..aliases import Source
+
+
+def _column_from_rows(rows: Sequence[Mapping[str, Any]], src_key: str) -> np.ndarray:
+    """Build one structured-array column from a sequence of mapping rows.
+
+    Gathers ``row[src_key]`` across rows (absent / ``None`` = missing) and picks
+    a dtype from the present scalar values: all-int → ``i8`` (missing 0),
+    all-str/bytes → ``U<maxlen>`` (missing ""), otherwise ``f8`` (missing NaN,
+    non-numeric coerced to NaN).
+    """
+    n = len(rows)
+    present = [(i, r[src_key]) for i, r in enumerate(rows) if r.get(src_key) is not None]
+    values = [v for _, v in present]
+
+    def _is_int(v: Any) -> bool:
+        return isinstance(v, (int, np.integer)) and not isinstance(v, bool)
+
+    def _is_str(v: Any) -> bool:
+        return isinstance(v, (str, bytes, np.bytes_, np.str_))
+
+    if values and all(_is_int(v) for v in values):
+        int_col = np.zeros(n, dtype="i8")
+        for i, v in present:
+            int_col[i] = int(v)
+        return int_col
+
+    if values and all(_is_str(v) for v in values):
+        decoded = [
+            v.decode("utf-8", "replace").rstrip("\x00")
+            if isinstance(v, (bytes, np.bytes_))
+            else str(v)
+            for v in values
+        ]
+        width = max((len(s) for s in decoded), default=1) or 1
+        str_col = np.zeros(n, dtype=f"U{width}")
+        for (i, _), s in zip(present, decoded):
+            str_col[i] = s
+        return str_col
+
+    float_col = np.full(n, np.nan, dtype="f8")
+    for i, v in present:
+        try:
+            float_col[i] = float(v)
+        except (TypeError, ValueError):
+            pass  # non-scalar / non-numeric stays NaN
+    return float_col
+
+
+class RowTableSource(Source):
+    """Build a structured-array DataNode from heterogeneous mapping rows.
+
+    ``columns`` selects and renames source keys into output fields; each
+    column's dtype is inferred from its present values, with missing entries
+    filled (0 / "" / NaN). ``rows_fn`` runs lazily — only when the resulting
+    node is loaded, not at ``execute()`` time.
+    """
+
+    def __init__(
+        self,
+        rows_fn: Callable[[], Sequence[Mapping[str, Any]]],
+        columns: list[str] | dict[str, str],
+        *,
+        name: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(name=name)
+        self._rows_fn = rows_fn
+        self._mapping = dict(columns) if isinstance(columns, dict) else {c: c for c in columns}
+        self._attributes = attributes
+
+    def load(self) -> DataNode:
+        def build() -> np.ndarray:
+            rows = list(self._rows_fn())
+            cols = {out: _column_from_rows(rows, src) for src, out in self._mapping.items()}
+            dtype = np.dtype([(out, cols[out].dtype) for out in self._mapping.values()])
+            table = np.empty(len(rows), dtype=dtype)
+            for out in self._mapping.values():
+                table[out] = cols[out]
+            return table
+
+        return DataNode(data_source=LazyDataSource(build), source_attributes=self._attributes)

vcti/flow/data/fields/transforms.py

@@ -0,0 +1,203 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Transformers that reshape structured-array DataNodes (eager)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from numpy.lib import recfunctions as rfn
+from vcti.datanode import DataNode
+
+from ..aliases import Transformer
+from ..record import from_array
+
+
+class NameFields(Transformer):
+    """Name the columns of a plain array, producing a structured field group.
+
+    A 1-D array becomes a single named field; a 2-D ``(N, K)`` array becomes K
+    named fields (e.g. ``["X", "Y", "Z"]`` for coordinates).
+    """
+
+    def __init__(self, names: str | list[str], *, name: str | None = None) -> None:
+        super().__init__(name=name)
+        self._names = [names] if isinstance(names, str) else list(names)
+
+    def transform(self, record: DataNode) -> DataNode:
+        arr = record.load()
+        if arr is None:
+            raise ValueError(f"{self.name}: input record has no data")
+        if arr.dtype.names is not None:
+            raise ValueError(f"{self.name}: expected a plain array, got a structured one")
+        cols = arr.reshape(len(arr), -1)
+        if cols.shape[1] != len(self._names):
+            raise ValueError(
+                f"{self.name}: array has {cols.shape[1]} column(s) "
+                f"but {len(self._names)} name(s) were given"
+            )
+        out_dtype = np.dtype([(n, arr.dtype) for n in self._names])
+        out = np.empty(len(arr), dtype=out_dtype)
+        for i, field in enumerate(self._names):
+            out[field] = cols[:, i]
+        return from_array(out, record.attributes)
+
+
+class SelectFields(Transformer):
+    """Select and optionally rename fields of a structured field group.
+
+    Pass a list to select by name, or a dict ``{source: output}`` to rename
+    while selecting.
+    """
+
+    def __init__(self, fields: list[str] | dict[str, str], *, name: str | None = None) -> None:
+        super().__init__(name=name)
+        self._mapping = dict(fields) if isinstance(fields, dict) else {f: f for f in fields}
+
+    def transform(self, record: DataNode) -> DataNode:
+        arr = record.load()
+        if arr is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        fields = arr.dtype.fields
+        if fields is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        missing = [s for s in self._mapping if s not in fields]
+        if missing:
+            raise ValueError(f"{self.name}: unknown field(s) {missing}; available: {list(fields)}")
+        out_dtype = np.dtype([(out, fields[src][0]) for src, out in self._mapping.items()])
+        out = np.empty(arr.shape, dtype=out_dtype)
+        for src, dst in self._mapping.items():
+            out[dst] = arr[src]
+        return from_array(out, record.attributes)
+
+
+class ComputeFields(Transformer):
+    """Append (or replace) one or more computed fields in a structured field group.
+
+    Pass ``{name: fn}``; each ``fn`` receives the structured array and returns a
+    1-D array of the same length. Fields are computed in iteration order against
+    the running result, so a later field may reference an earlier one; a name that
+    already exists is replaced. Example::
+
+        ComputeFields({"vmag": lambda a: np.sqrt(a["UX"] ** 2 + a["UY"] ** 2)})
+    """
+
+    def __init__(
+        self,
+        fields: dict[str, Callable[[np.ndarray], Any]],
+        *,
+        name: str | None = None,
+    ) -> None:
+        super().__init__(name=name)
+        self._fields = dict(fields)
+
+    def transform(self, record: DataNode) -> DataNode:
+        arr = record.load()
+        if arr is None or arr.dtype.names is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        n = len(arr)
+        out = arr
+        for field_name, fn in self._fields.items():
+            values = np.asarray(fn(out))
+            if len(values) != n:
+                raise ValueError(
+                    f"{self.name}: computed field {field_name!r} has {len(values)} "
+                    f"row(s), expected {n}"
+                )
+            if field_name in (out.dtype.names or ()):
+                out = out.copy()
+                out[field_name] = values
+            else:
+                out = rfn.append_fields(out, field_name, values, usemask=False)
+        return from_array(out, record.attributes)
+
+
+class RenameFields(Transformer):
+    """Rename fields of a structured field group, keeping the rest.
+
+    Pass ``{old: new}``; unlisted fields pass through unchanged and in order.
+    Renaming only relabels the dtype, so no array data is copied — the result
+    shares memory with the input.
+    """
+
+    def __init__(self, names: dict[str, str], *, name: str | None = None) -> None:
+        super().__init__(name=name)
+        self._mapping = dict(names)
+
+    def transform(self, record: DataNode) -> DataNode:
+        arr = record.load()
+        if arr is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        names = arr.dtype.names
+        if names is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        unknown = [s for s in self._mapping if s not in names]
+        if unknown:
+            raise ValueError(f"{self.name}: unknown field(s) {unknown}; available: {list(names)}")
+        renamed = [self._mapping.get(n, n) for n in names]
+        if len(set(renamed)) != len(renamed):
+            raise ValueError(f"{self.name}: rename produces duplicate field name(s) in {renamed}")
+        return from_array(rfn.rename_fields(arr, self._mapping), record.attributes)
+
+
+class DropFields(Transformer):
+    """Drop fields from a structured field group, keeping the rest.
+
+    The remaining fields are returned as a view over the input array (no data
+    copy). The inverse of ``SelectFields`` — ergonomic when you keep most fields.
+
+    Raises:
+        ValueError: If a named field is absent, or if every field would be dropped.
+    """
+
+    def __init__(self, fields: list[str], *, name: str | None = None) -> None:
+        super().__init__(name=name)
+        self._drop = list(fields)
+
+    def transform(self, record: DataNode) -> DataNode:
+        arr = record.load()
+        if arr is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        names = arr.dtype.names
+        if names is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        unknown = [f for f in self._drop if f not in names]
+        if unknown:
+            raise ValueError(f"{self.name}: unknown field(s) {unknown}; available: {list(names)}")
+        drop = set(self._drop)
+        kept = [n for n in names if n not in drop]
+        if not kept:
+            raise ValueError(f"{self.name}: dropping all fields leaves nothing")
+        return from_array(arr[kept], record.attributes)
+
+
+class CastFields(Transformer):
+    """Cast the dtypes of selected fields in a structured field group.
+
+    Pass ``{field: dtype}``; unlisted fields keep their dtype. A structured array
+    is contiguous in memory, so casting rebuilds it — this is the one field op
+    that copies. Narrowing casts (e.g. ``f8`` -> ``f4``) lose precision by design.
+    """
+
+    def __init__(self, dtypes: dict[str, Any], *, name: str | None = None) -> None:
+        super().__init__(name=name)
+        self._dtypes = {field: np.dtype(dt) for field, dt in dtypes.items()}
+
+    def transform(self, record: DataNode) -> DataNode:
+        arr = record.load()
+        if arr is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        names = arr.dtype.names
+        fields = arr.dtype.fields
+        if names is None or fields is None:
+            raise ValueError(f"{self.name}: requires a structured field group")
+        unknown = [f for f in self._dtypes if f not in names]
+        if unknown:
+            raise ValueError(f"{self.name}: unknown field(s) {unknown}; available: {list(names)}")
+        out_dtype = np.dtype([(n, self._dtypes.get(n, fields[n][0])) for n in names])
+        out = np.empty(arr.shape, dtype=out_dtype)
+        for n in names:
+            out[n] = arr[n]
+        return from_array(out, record.attributes)

vcti/flow/data/record.py

@@ -0,0 +1,34 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Build DataNode payloads for flow graphs from in-memory arrays."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+from vcti.datanode import DataNode, EagerDataSource
+
+
+def from_array(
+    array: np.ndarray | None = None,
+    attributes: Mapping[str, Any] | None = None,
+) -> DataNode:
+    """Build a DataNode wrapping an in-memory array.
+
+    The array (when given) is held by an ``EagerDataSource`` — it is already
+    resident, so deferring it would be pointless. Attributes go in the enriched
+    layer (the convention for derived metadata); a leaf source reading external
+    data uses ``source_attributes`` directly instead. When *array* is ``None``
+    the node has no data source — a metadata-only node.
+
+    Args:
+        array: The array to wrap, or ``None`` for a metadata-only node.
+        attributes: Optional metadata, stored in ``enriched_attributes``.
+
+    Returns:
+        A ``DataNode`` with an eager data source, or none when *array* is ``None``.
+    """
+    source = EagerDataSource(array) if array is not None else None
+    return DataNode(data_source=source, enriched_attributes=attributes)

vcti/flow/data/sources.py

@@ -0,0 +1,40 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Lazy leaf source over a callable that returns an array."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import numpy as np
+from vcti.datanode import DataNode, LazyDataSource
+
+from .aliases import Source
+
+
+class ArraySource(Source):
+    """Expose a callable that returns an array as a lazy DataNode source.
+
+    ``load_fn`` returns a numpy array and runs only when the node is loaded, so a
+    heavy read (file, service, reader accessor) is deferred past ``execute()``.
+    This is the lazy counterpart of :func:`from_array` (which is eager); it makes
+    no assumption about array shape.
+    """
+
+    def __init__(
+        self,
+        load_fn: Callable[[], np.ndarray],
+        *,
+        name: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(name=name)
+        self._load_fn = load_fn
+        self._attributes = attributes
+
+    def load(self) -> DataNode:
+        return DataNode(
+            data_source=LazyDataSource(self._load_fn),
+            source_attributes=self._attributes,
+        )

vcti_dataflow-2.0.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: vcti-dataflow
+Version: 2.0.0
+Summary: The DataNode binding of vcti-flow: sources, transformers, reducers, and combiners for vcti-datanode payloads.
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: vcti-flow>=2.0.0
+Requires-Dist: vcti-datanode>=2.0.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# Data Flow
+
+The DataNode binding of vcti-flow: sources, transformers, reducers, and combiners for vcti-datanode payloads.
+
+## Overview
+
+[vcti-flow](https://github.com/vcollab/vcti-python-flow) is a payload-agnostic
+framework for composing flow graphs — it never inspects the values flowing
+through it. `vcti.flow.data` binds that framework to the
+[vcti-datanode](https://github.com/vcollab/vcti-python-datanode) `DataNode`
+payload (data plus layered attributes behind a data source), so you get
+familiar, ready-bound node kinds — `Source`, `Transformer`, `Reducer`, `Sink` —
+instead of writing `Source[DataNode]` everywhere, plus `from_array` (eager) and
+`ArraySource` (lazy) for building payloads.
+
+These node-kind names are the `vcti.flow` kinds bound to `DataNode`: in this
+package `Source` *is* `Source[DataNode]`. It is a flow leaf node — distinct from
+`vcti.datanode.DataSource`, the array-source ABC re-exported here as
+`EagerDataSource` / `LazyDataSource`.
+
+Nodes that need a *structured* (named-field) array — field-wise merge and
+row-keyed iteration — live in the `vcti.flow.data.fields` submodule; the base
+binding makes no assumption about array shape.
+
+## Installation
+
+```bash
+pip install vcti-dataflow
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-dataflow>=2.0.0",
+]
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from vcti.flow.data import Source, Transformer, DataNode, from_array
+
+# A source produces a DataNode
+class Stress(Source):
+    def load(self) -> DataNode:
+        return from_array(np.array([1.0, 2.0, 3.0]), {"units": "MPa"})
+
+# A transformer maps one DataNode to another
+class Scale(Transformer):
+    def __init__(self, factor: float) -> None:
+        super().__init__()
+        self.factor = factor
+
+    def transform(self, record: DataNode) -> DataNode:
+        return from_array(record.load() * self.factor, record.attributes)
+
+result = Scale(2.0).connect(Stress()).execute()
+result.load()            # array([2., 4., 6.])
+result.attributes["units"]  # "MPa"
+```
+
+Reach for the array only when you need it (`record.load()`); a leaf source can
+hand back a `LazyDataSource`-backed node to defer a heavy read.
+
+### Structured-array nodes
+
+The `vcti.flow.data.fields` submodule adds nodes that assume a structured
+(named-field) array — building tables, naming/selecting/computing fields,
+merging field groups, and row-keyed iteration:
+
+```python
+from vcti.flow.data import ArraySource          # lazy leaf source (base binding)
+from vcti.flow.data.fields import (
+    RowTableSource, NameFields, SelectFields, ComputeFields,
+    RenameFields, DropFields, CastFields, MergeFields, for_each_field,
+)
+
+# Build a structured table from dict rows (lazy — rows read on load())
+mats = RowTableSource(lambda: material_rows(reader),
+                      columns={"id": "MAT_ID", "EX": "Young's Modulus"})
+
+# Name plain columns, select/rename, compute
+coords = NameFields(["X", "Y", "Z"]).connect(ArraySource(lambda: reader.coords()))
+picked = SelectFields({"X": "x", "Y": "y"}).connect(coords)
+mag = ComputeFields({"mag": lambda a: np.hypot(a["X"], a["Y"])}).connect(coords)
+
+# Rename, drop, cast (rename & drop return views — no data copy)
+renamed = RenameFields({"X": "x"}).connect(coords)   # rename, keep the rest
+trimmed = DropFields(["Z"]).connect(coords)          # drop, keep the rest
+narrow = CastFields({"X": "f4"}).connect(coords)     # change dtypes
+
+# Merge field groups (same row count) into one structured array
+combined = MergeFields().connect(ids).connect(coords).execute()
+
+# One flow per row, keyed by a field
+for case_id, flow in for_each_field(cases, build_case_flow, key_field="ID"):
+    flow.execute()
+```
+
+---
+
+## API
+
+| Symbol | Purpose |
+|--------|---------|
+| `Source` / `Transformer` / `Reducer` / `Sink` | `vcti.flow` node kinds bound to `DataNode` |
+| `Observer` | `vcti.flow` observer bound to `DataNode` |
+| `from_array(array, attributes=None)` | Build a `DataNode` from an in-memory array (eager) |
+| `ArraySource(load_fn, attributes=None)` | Lazy leaf source over a callable returning an array (the lazy counterpart of `from_array`) |
+| `DataNode` / `EagerDataSource` / `LazyDataSource` | Re-exported from `vcti-datanode` for convenience |
+| `fields.RowTableSource` | Lazy leaf source — a structured table from dict rows |
+| `fields.NameFields` / `fields.SelectFields` / `fields.ComputeFields` | Name plain columns, select/rename fields, append/replace computed fields |
+| `fields.RenameFields` / `fields.DropFields` / `fields.CastFields` | Rename or drop fields (views, no copy), or change field dtypes |
+| `fields.MergeFields` | Field-wise merge of structured arrays |
+| `fields.for_each_field` / `fields.field_items` | Row-keyed fan-out over a structured array |
+
+---
+
+## Dependencies
+
+- [vcti-flow](https://github.com/vcollab/vcti-python-flow) (>=2.0.0) — the generic framework
+- [vcti-datanode](https://github.com/vcollab/vcti-python-datanode) (>=2.0.0) — the `DataNode` payload
+- [numpy](https://numpy.org/) (>=1.24)

vcti_dataflow-2.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+vcti/flow/data/__init__.py,sha256=TBauzupjsaAMKvlZrGTLizBBp0eUaADCi9GuY2hx7MM,1026
+vcti/flow/data/aliases.py,sha256=2Tdby1qYkSig9JkhuZe1hjSXjxXaNbGi6OG4U5_WpJQ,1228
+vcti/flow/data/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vcti/flow/data/record.py,sha256=b6k_sg6ZzTNuVvv_diVAyOUK6k-i1DSi_KognAgS8_o,1287
+vcti/flow/data/sources.py,sha256=M0MTCcnWBfBsXsJ6sXbP5cBgD5SJLhLRMVbp4gl8RbI,1225
+vcti/flow/data/fields/__init__.py,sha256=c9bdahN3I1PtsRUb_H0gX_b3u77d0c2BgYy_rq0FHjI,1277
+vcti/flow/data/fields/iterate.py,sha256=v0p_JICHOP_15RcSl20NSz7QCfBr-7o0o_5KBqVhIRU,1691
+vcti/flow/data/fields/merge.py,sha256=OoKEQCCuPA-gs2U5y-NTsoPzhz07aH2ugmzsVn38UpI,1845
+vcti/flow/data/fields/sources.py,sha256=FrEb1wupcFezUhU8dEavdwi5_fp3TonY9IuSbiaycFc,3455
+vcti/flow/data/fields/transforms.py,sha256=dK87paRSFVC7J1GdbaHuiyYbyuruS_pl3ozqrCBr_Bw,8358
+vcti_dataflow-2.0.0.dist-info/licenses/LICENSE,sha256=gqRj-E4YRsT7mZ52W76LG6aTTFv6iEOK9QR_fV5EdrI,369
+vcti_dataflow-2.0.0.dist-info/METADATA,sha256=wwypvajpJ1Rio6bPWzFO2DnirS-2TbMSjendrgOT-88,5705
+vcti_dataflow-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vcti_dataflow-2.0.0.dist-info/top_level.txt,sha256=Jl6AIAI3Xhru_BFQAhD_13VeXLmZQd9BqBNUaAKNgKs,5
+vcti_dataflow-2.0.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+vcti_dataflow-2.0.0.dist-info/RECORD,,

vcti_dataflow-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vcti_dataflow-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_dataflow-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vcti

vcti_dataflow-2.0.0.dist-info/zip-safe

@@ -0,0 +1 @@
+