syrtis-python-dataflow 1.0.1__tar.gz → 2.0.0__tar.gz

{syrtis_python_dataflow-1.0.1 → syrtis_python_dataflow-2.0.0}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.1
 Name: syrtis-python-dataflow
-Version: 1.0.1
+Version: 2.0.0
 Author-Email: weeger <contact@syrtis.ai>
 License: MIT
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
+Requires-Dist: syrtis-python-storage>=2.0.0
+Requires-Dist: wexample-helpers>=20.6.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -14,16 +16,23 @@ Description-Content-Type: text/markdown
 
 # python-dataflow
 
-Version: 1.0.1
+Version: 2.0.0
 
 ## Table of Contents
 
+- [Introduction](#introduction)
 - [Install](#install)
 - [Tests](#tests)
 - [Roadmap](#roadmap)
 - [Status Compatibility](#status-compatibility)
 - [Useful Links](#useful-links)
 
+`syrtis-python-dataflow` runs a pipeline: stages reading one another from the sources down, each a projection of elements an operator computes — a book, its paragraphs, their summaries, the chapters', the book's. It is the engine of the data side of Syrtis, where the scenarios' engine holds a conversation: here nothing reasons, and no session is kept; collections are read, transformed and kept, in a storage.
+
+What it does that the scenarios' engine does not: it works on collections, element by element; it remembers what every element was computed from, so that a run computes only what changed — a stage's config, a source refreshed — and keeps the rest; it runs a stage's elements on several threads; an element an operator fails on is reported and left out, the stage going on.
+
+It knows nothing of Syrtis' database: the host — the core — builds the pipeline from what it keeps, hands the operators what they need, and reads the report back.
+
 ## Installation
 
 ```bash

{syrtis_python_dataflow-1.0.1 → syrtis_python_dataflow-2.0.0}/README.md

@@ -1,15 +1,22 @@
 # python-dataflow
 
-Version: 1.0.1
+Version: 2.0.0
 
 ## Table of Contents
 
+- [Introduction](#introduction)
 - [Install](#install)
 - [Tests](#tests)
 - [Roadmap](#roadmap)
 - [Status Compatibility](#status-compatibility)
 - [Useful Links](#useful-links)
 
+`syrtis-python-dataflow` runs a pipeline: stages reading one another from the sources down, each a projection of elements an operator computes — a book, its paragraphs, their summaries, the chapters', the book's. It is the engine of the data side of Syrtis, where the scenarios' engine holds a conversation: here nothing reasons, and no session is kept; collections are read, transformed and kept, in a storage.
+
+What it does that the scenarios' engine does not: it works on collections, element by element; it remembers what every element was computed from, so that a run computes only what changed — a stage's config, a source refreshed — and keeps the rest; it runs a stage's elements on several threads; an element an operator fails on is reported and left out, the stage going on.
+
+It knows nothing of Syrtis' database: the host — the core — builds the pipeline from what it keeps, hands the operators what they need, and reads the report back.
+
 ## Installation
 
 ```bash

{syrtis_python_dataflow-1.0.1 → syrtis_python_dataflow-2.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "syrtis-python-dataflow"
-version = "1.0.1"
+version = "2.0.0"
 authors = [
     { name = "weeger", email = "contact@syrtis.ai" },
 ]
@@ -16,7 +16,10 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-dependencies = []
+dependencies = [
+    "syrtis-python-storage>=2.0.0",
+    "wexample-helpers>=20.6.0",
+]
 
 [project.readme]
 file = "README.md"

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from syrtis_python_dataflow.common.abstract_operator import AbstractOperator
+from syrtis_python_dataflow.common.abstract_projection_storage import AbstractProjectionStorage
+from syrtis_python_dataflow.common.element import Element
+from syrtis_python_dataflow.common.executor import Executor
+from syrtis_python_dataflow.common.file_projection_storage import FileProjectionStorage
+from syrtis_python_dataflow.common.memory_projection_storage import MemoryProjectionStorage
+from syrtis_python_dataflow.common.operator_context import OperatorContext
+from syrtis_python_dataflow.common.pipeline import Pipeline
+from syrtis_python_dataflow.common.port import Port
+from syrtis_python_dataflow.common.run_report import RunReport
+from syrtis_python_dataflow.common.stage import Stage
+from syrtis_python_dataflow.common.stage_input import StageInput
+from syrtis_python_dataflow.common.stage_report import StageReport
+
+__all__ = [
+    "AbstractOperator",
+    "AbstractProjectionStorage",
+    "Element",
+    "Executor",
+    "FileProjectionStorage",
+    "MemoryProjectionStorage",
+    "OperatorContext",
+    "Pipeline",
+    "Port",
+    "RunReport",
+    "Stage",
+    "StageInput",
+    "StageReport",
+]

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/abstract_operator.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_dataflow.const.config import CONFIG_TRANSMIT_CONTENT_TYPE
+from syrtis_python_dataflow.const.port import PORT_NAME_DEFAULT
+
+if TYPE_CHECKING:
+    from syrtis_python_dataflow.common.element import Element
+    from syrtis_python_dataflow.common.operator_context import OperatorContext
+    from syrtis_python_dataflow.common.port import Port
+
+
+@base_class
+class AbstractOperator(BaseClass):
+    """What a stage runs: named, with its ports. Given, for each input port,
+    the whole of what reaches it — the elements of every stage linked to the
+    port, in the links' order —, it gives back the elements of its
+    projection. Whether it gives one per element read, ten, or one for the
+    lot is its own business. A stage whose operator has no input port is
+    where a pipe starts: what it reads lives outside the pipe.
+
+    An element keeps its key through what derives from it (`derive`): what
+    two branches made of the same thing is told apart by it, and put back
+    together by it.
+
+    An operator that passes through (`passes_through`, or a stage's config
+    saying so: `transmit_content_type`) — a text in capitals is still the
+    text it was — gives each element the type it came with,
+    whatever its output port declares; a stage reading it may then name a
+    type in place of a port, and read the elements of that type alone."""
+
+    name: str = ""
+
+    @classmethod
+    def passes_through(cls) -> bool:
+        """Whether what it gives keeps the type of what it read."""
+        return False
+
+    @classmethod
+    def transmits(cls, config: dict[str, Any] | None) -> bool:
+        """Whether a stage set with this config keeps the type of what it
+        reads: as set (`transmit_content_type`), else as the operator does
+        by default."""
+        said = (config or {}).get(CONFIG_TRANSMIT_CONTENT_TYPE)
+        return cls.passes_through() if said is None else bool(said)
+
+    @classmethod
+    def get_ports_input(cls) -> list[Port]:
+        from syrtis_python_dataflow.common.port import Port
+
+        return [Port(name=PORT_NAME_DEFAULT)]
+
+    @classmethod
+    def get_ports_output(cls) -> list[Port]:
+        from syrtis_python_dataflow.common.port import Port
+
+        return [Port(name=PORT_NAME_DEFAULT)]
+
+    @classmethod
+    def get_port_input(cls, name: str) -> Port | None:
+        return next((port for port in cls.get_ports_input() if port.name == name), None)
+
+    @classmethod
+    def get_port_output(cls, name: str) -> Port | None:
+        return next((port for port in cls.get_ports_output() if port.name == name), None)
+
+    @abstract_method
+    def run(self, inputs: dict[str, list[Element]], config: dict[str, Any], context: OperatorContext) -> list[Element]:
+        """The elements of the projection, from what each input port reads."""
+
+    def each(self, elements: list[Element], make: Callable[[Element], Element | list[Element] | None], context: OperatorContext) -> list[Element]:
+        """What `make` gives of each element — one, several, none —, an
+        element it fails on said in the stage's report (`context.fail`) and
+        left out: one page out of reach costs that page, not the stage."""
+        produced: list[Element] = []
+
+        for element in elements:
+            try:
+                made = make(element)
+            except Exception as exception:  # noqa: BLE001 — whatever it failed with is the element's report.
+                context.fail(element, exception)
+
+                continue
+
+            if isinstance(made, list):
+                produced.extend(made)
+            elif made is not None:
+                produced.append(made)
+
+        return produced
+
+    def get_output_content_type(self, config: dict[str, Any], port: str = PORT_NAME_DEFAULT) -> str | None:
+        """The content type the elements of an output port carry; an
+        operator whose type depends on its config says it here. None when
+        it depends on what is read: the element keeps the type it came with."""
+        found = self.get_port_output(port)
+        return found.get_content_type() if found else None
+
+    def element(
+        self,
+        key: str,
+        data: Any,
+        content_type: str | None = None,
+        parents: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> Element:
+        """A new element, its type the default output port's unless given."""
+        from syrtis_python_dataflow.common.element import Element
+
+        return Element(
+            content_type=content_type or self.get_output_content_type(config or {}) or "content/text",
+            data=data,
+            key=key,
+            metadata=metadata or {},
+            parents=parents or [],
+        )
+
+    def derive(
+        self,
+        source: Element,
+        data: Any,
+        content_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        key: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> Element:
+        """An element made from another: the same key unless given — a
+        paragraph of `moby-dick` is `moby-dick/3` —, descending from it, its
+        metadata carried over, its type the source's own when the operator
+        passes through, else the output port's, else the source's."""
+        kept = source.content_type if self.transmits(config) else None
+
+        return self.element(
+            key=key if key is not None else source.key,
+            data=data,
+            content_type=content_type or kept or self.get_output_content_type(config or {}) or source.content_type,
+            parents=[source.key],
+            metadata={**source.metadata, **(metadata or {})},
+            config=config,
+        )

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/abstract_projection_storage.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from syrtis_python_dataflow.common.element import Element
+    from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+    from syrtis_python_dataflow.common.stored_element import StoredElement
+
+
+@base_class
+class AbstractProjectionStorage(BaseClass):
+    """Where a pipeline's projections are kept between runs: an index per
+    projection, and each element's content by key. What a run computes is
+    written here; what it finds unchanged is read back from here."""
+
+    @abstract_method
+    def read_index(self, pipeline: str, projection: str) -> ProjectionIndex:
+        """The projection as it stands; empty before any run."""
+
+    @abstract_method
+    def write_index(self, pipeline: str, projection: str, index: ProjectionIndex) -> None:
+        pass
+
+    @abstract_method
+    def read_content(self, pipeline: str, projection: str, key: str) -> bytes:
+        pass
+
+    @abstract_method
+    def write_content(self, pipeline: str, projection: str, key: str, content: bytes) -> None:
+        pass
+
+    @abstract_method
+    def delete_content(self, pipeline: str, projection: str, key: str) -> None:
+        pass
+
+    def read_element(self, pipeline: str, projection: str, stored: StoredElement) -> Element:
+        """An element read back whole from what the index keeps of it."""
+        from syrtis_python_dataflow.common.element import Element
+        from syrtis_python_dataflow.helper.content import content_from_bytes
+
+        return Element(
+            content_type=stored.content_type,
+            data=content_from_bytes(self.read_content(pipeline, projection, stored.key), stored.content_type),
+            key=stored.key,
+            metadata=dict(stored.metadata),
+            parents=list(stored.parents),
+        )
+
+    def read_elements(self, pipeline: str, projection: str) -> list[Element]:
+        """Every element of a projection, in its order."""
+        index = self.read_index(pipeline, projection)
+        return [self.read_element(pipeline, projection, stored) for stored in index.elements.values()]

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/element.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_dataflow.helper.content import ElementData, content_to_bytes
+
+
+@base_class
+class Element(BaseClass):
+    """One thing of a projection: a book, a paragraph, a summary. Its key is
+    its identity, posed by the operator that first makes it and kept by what
+    derives from it — a paragraph of `moby-dick` is `moby-dick/12`, its
+    summary keeps that key —; its parents say which elements it was made
+    from."""
+
+    content_type: str = public_field(description="The Syrtis content type its data follows, e.g. `content/text`.")
+    data: ElementData = public_field(description="What it holds: text, bytes, or a JSON structure.")
+    key: str = public_field(description="Its name in the projection, unique there.")
+    metadata: dict[str, Any] = public_field(
+        factory=dict, description="What goes with it without being it: a chapter number, a source url."
+    )
+    parents: list[str] = public_field(
+        factory=list, description="The keys of the elements it was made from, in the projections upstream."
+    )
+
+    def to_bytes(self) -> bytes:
+        return content_to_bytes(self.data)
+
+    def __repr__(self) -> str:
+        return f"Element(key={self.key!r}, content_type={self.content_type!r})"

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/executor.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from syrtis_python_dataflow.common.abstract_projection_storage import AbstractProjectionStorage
+    from syrtis_python_dataflow.common.element import Element
+    from syrtis_python_dataflow.common.pipeline import Pipeline
+    from syrtis_python_dataflow.common.run_report import RunReport
+    from syrtis_python_dataflow.common.stage import Stage
+    from syrtis_python_dataflow.common.stage_input import StageInput
+    from syrtis_python_dataflow.common.stage_report import StageReport
+
+
+@base_class
+class Executor(BaseClass):
+    """Runs a pipeline, stage after stage, from the start down: each
+    operator given the whole of what its ports read, its elements written
+    in the stage's place of the run before. An element the operator fails
+    on (`each`, `context.fail`) is reported and left out, the others kept;
+    a stage whose operator fails whole is reported and left empty, the
+    stages reading it read nothing. The run goes on."""
+
+    host: Any = public_field(default=None, description="What every operator is handed in its context: a kernel, a wallet.")
+    storage: AbstractProjectionStorage = public_field(description="Where the projections are kept between runs.")
+    listener: Callable[[str, Stage, StageReport | None], None] | None = public_field(
+        default=None,
+        description="Told of each stage as it starts (`stage.start`, no report yet) and ends (`stage.done`, its report): whoever follows the run.",
+    )
+
+    def run(self, pipeline: Pipeline) -> RunReport:
+        from syrtis_python_dataflow.common.run_report import RunReport
+
+        report = RunReport(pipeline=pipeline.name)
+        for stage in pipeline.get_stages_ordered():
+            self._tell("stage.start", stage, None)
+            stage_report = self._run_stage(pipeline, stage)
+            report.stages.append(stage_report)
+            self._tell("stage.done", stage, stage_report)
+
+        return report
+
+    def _tell(self, event: str, stage: Stage, report: StageReport | None) -> None:
+        if self.listener is not None:
+            self.listener(event, stage, report)
+
+    def _run_stage(self, pipeline: Pipeline, stage: Stage) -> StageReport:
+        from syrtis_python_dataflow.common.operator_context import OperatorContext
+        from syrtis_python_dataflow.common.stage_report import StageReport
+
+        report = StageReport(name=stage.name)
+        # Each port the union of what its links bring, in the links' order; a
+        # link naming a type in place of a port brings the elements of that
+        # type alone.
+        inputs = {
+            port.name: [
+                element
+                for read in stage.inputs.get(port.name, [])
+                for element in self._read(pipeline, read)
+            ]
+            for port in stage.operator.get_ports_input()
+        }
+
+        context = OperatorContext(host=self.host, stage_name=stage.name)
+
+        try:
+            produced = list(stage.operator.run(inputs, stage.config, context))
+            # What it made, and the elements it failed on.
+            report.errors.extend(context.errors)
+            report.failed = len(context.errors)
+        except Exception as exception:  # noqa: BLE001 — whatever the operator failed with is the stage's report.
+            report.failed = 1
+            report.errors.append({"key": None, "reason": f"{type(exception).__name__}: {exception}"})
+            produced = []
+
+        for position, element in enumerate(produced):
+            if not element.key:
+                element.key = str(position)
+
+        self._write(pipeline, stage, produced)
+        report.computed = len(produced)
+        report.total = len({element.key for element in produced})
+
+        return report
+
+    def _read(self, pipeline: Pipeline, read: StageInput) -> list[Element]:
+        elements = self.storage.read_elements(pipeline.name, read.stage)
+        upstream = pipeline.get_stage(read.stage)
+
+        if upstream and upstream.operator.get_port_output(read.port) is None:
+            return [element for element in elements if element.content_type == read.port]
+
+        return elements
+
+    def _write(self, pipeline: Pipeline, stage: Stage, elements: list[Element]) -> None:
+        """The stage's elements written in place of the run before's: two
+        under one key, the last one stands."""
+        from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+        from syrtis_python_dataflow.common.stored_element import StoredElement
+
+        before = self.storage.read_index(pipeline.name, stage.name)
+        index = ProjectionIndex()
+
+        for element in elements:
+            self.storage.write_content(pipeline.name, stage.name, element.key, element.to_bytes())
+            index.elements[element.key] = StoredElement(
+                content_type=element.content_type,
+                key=element.key,
+                metadata=dict(element.metadata),
+                parents=list(element.parents),
+            )
+
+        for key in before.elements:
+            if key not in index.elements:
+                self.storage.delete_content(pipeline.name, stage.name, key)
+
+        self.storage.write_index(pipeline.name, stage.name, index)

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/file_projection_storage.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_dataflow.common.abstract_projection_storage import AbstractProjectionStorage
+
+if TYPE_CHECKING:
+    from syrtis_python_storage.common.abstract_file_storage import AbstractFileStorage
+
+    from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+
+# Where a projection's index stands among its contents.
+FILE_PROJECTION_STORAGE_INDEX_NAME: str = "index.json"
+
+
+@base_class
+class FileProjectionStorage(AbstractProjectionStorage):
+    """Projections kept in a syrtis-python-storage file storage — a directory,
+    a bucket —: `<pipeline>/<projection>/index.json` and one file per
+    element, named by a digest of its key so that `a` and `a/b` never
+    collide as a file and a directory would."""
+
+    storage: AbstractFileStorage = public_field(description="The file storage the projections are written to.")
+
+    def read_index(self, pipeline: str, projection: str) -> ProjectionIndex:
+        from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+
+        path = self._index_path(pipeline, projection)
+        if not self.storage.exists(path):
+            return ProjectionIndex()
+
+        return ProjectionIndex.from_dict(json.loads(self.storage.read(path).decode("utf-8")))
+
+    def write_index(self, pipeline: str, projection: str, index: ProjectionIndex) -> None:
+        self.storage.write(
+            self._index_path(pipeline, projection),
+            json.dumps(index.to_dict(), ensure_ascii=False, indent=2).encode("utf-8"),
+        )
+
+    def read_content(self, pipeline: str, projection: str, key: str) -> bytes:
+        return self.storage.read(self._content_path(pipeline, projection, key))
+
+    def write_content(self, pipeline: str, projection: str, key: str, content: bytes) -> None:
+        self.storage.write(self._content_path(pipeline, projection, key), content)
+
+    def delete_content(self, pipeline: str, projection: str, key: str) -> None:
+        self.storage.delete(self._content_path(pipeline, projection, key))
+
+    def _index_path(self, pipeline: str, projection: str) -> str:
+        return f"{pipeline}/{projection}/{FILE_PROJECTION_STORAGE_INDEX_NAME}"
+
+    def _content_path(self, pipeline: str, projection: str, key: str) -> str:
+        from syrtis_python_dataflow.helper.fingerprint import fingerprint_bytes
+
+        return f"{pipeline}/{projection}/{fingerprint_bytes(key.encode('utf-8'))[:32]}"

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/memory_projection_storage.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+from syrtis_python_dataflow.common.abstract_projection_storage import AbstractProjectionStorage
+
+if TYPE_CHECKING:
+    from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+
+
+@base_class
+class MemoryProjectionStorage(AbstractProjectionStorage):
+    """Projections kept in memory: for tests, and for a run whose result
+    is read at once and never again."""
+
+    contents: dict[str, bytes] = public_field(factory=dict, description="Contents by pipeline, projection and key.")
+    indexes: dict[str, ProjectionIndex] = public_field(factory=dict, description="Indexes by pipeline and projection.")
+
+    def read_index(self, pipeline: str, projection: str) -> ProjectionIndex:
+        from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+
+        index = self.indexes.get(f"{pipeline}/{projection}")
+        # Read back as written: a run's own edits never reach the storage before it writes.
+        return ProjectionIndex.from_dict(index.to_dict()) if index else ProjectionIndex()
+
+    def write_index(self, pipeline: str, projection: str, index: ProjectionIndex) -> None:
+        from syrtis_python_dataflow.common.projection_index import ProjectionIndex
+
+        self.indexes[f"{pipeline}/{projection}"] = ProjectionIndex.from_dict(index.to_dict())
+
+    def read_content(self, pipeline: str, projection: str, key: str) -> bytes:
+        return self.contents[f"{pipeline}/{projection}/{key}"]
+
+    def write_content(self, pipeline: str, projection: str, key: str, content: bytes) -> None:
+        self.contents[f"{pipeline}/{projection}/{key}"] = content
+
+    def delete_content(self, pipeline: str, projection: str, key: str) -> None:
+        self.contents.pop(f"{pipeline}/{projection}/{key}", None)

syrtis_python_dataflow-2.0.0/src/syrtis_python_dataflow/common/operator_context.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from syrtis_python_dataflow.common.element import Element
+
+
+@base_class
+class OperatorContext(BaseClass):
+    """What an operator is handed besides its inputs and its config: the
+    stage it runs for, whatever the host gives every operator — a kernel, a
+    wallet —, and where it says which elements it failed on."""
+
+    errors: list[dict[str, str | None]] = public_field(factory=list, description="The elements the operator could not make anything of, each its key and why: the stage's report.")
+    host: Any = public_field(default=None, description="What the host lends its operators; nothing in a bare run.")
+    stage_name: str = public_field(description="The stage the operator runs for.")
+
+    def fail(self, element: Element, exception: BaseException) -> None:
+        """An element the operator could not make anything of: said in the
+        stage's report, the others going on."""
+        self.errors.append({"key": element.key, "reason": f"{type(exception).__name__}: {exception}"})