vcti-dataflow 2.0.0__tar.gz

vcti_dataflow-2.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,127 @@
+# 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/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-dataflow"
+version = "2.0.0"
+description = "The DataNode binding of vcti-flow: sources, transformers, reducers, and combiners for vcti-datanode payloads."
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    "vcti-flow>=2.0.0",
+    "vcti-datanode>=2.0.0",
+    "numpy>=1.24",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.flow.data", "vcti.flow.data.*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"vcti.flow.data" = ["py.typed"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.flow.data --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_dataflow-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_dataflow-2.0.0/src/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_dataflow-2.0.0/src/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_dataflow-2.0.0/src/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_dataflow-2.0.0/src/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_dataflow-2.0.0/src/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_dataflow-2.0.0/src/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)