Skip to content

Composition API

Programmatic numeric graphs have no persistent configuration format or application dependencies. See branched pipelines for execution and failure semantics.

GraphPipeline

Python
GraphPipeline(nodes: Sequence[GraphComponent], model: ModelProtocol, output: str, *, model_minimum_updates: int = 0, observer: Observer | None = None)

A numeric feature DAG ending in exactly one online model.

Learning uses each transformer's post-update representation, but only when all of its inputs are ready. A newly ready output may feed successors in the same observation. Scoring never learns and rejects unready graphs. One caller owns execution; concurrent use is not supported.

This is model-ending composition, not a transformer with provisional outputs. Existing linear Pipeline deliberately retains its eager learning behaviour. Applications own calibration and alarm policies.

readiness property

Python
readiness: Readiness

Last complete learning outcome, detached from mutable model state.

learn_one

Python
learn_one(x: dict[str, float]) -> None

Commit one staged pass, or roll back every transactional learner.

Transactions remain open through the model's update. A failure after touching any nontransactional learner is uncertain and permanently disables this graph; no false all-component atomicity is promised.

score_one

Python
score_one(x: dict[str, float]) -> float

Execute one read-only pass using the previously committed state.

GraphNode dataclass

Python
GraphNode(id: str, transformer: TransformerProtocol, input: str = INPUT, minimum_updates: int | None = None)

One transformer applied to one predecessor's complete feature mapping.

Custom transformers without public readiness must specify minimum_updates explicitly, including zero for stateless components.

MergeNode dataclass

Python
MergeNode(id: str, inputs: tuple[str, ...])

Concatenate predecessor mappings in inputs order without collisions.

LearningOutcome dataclass

Python
LearningOutcome(model_updated: bool, model_updates: int, nodes: tuple[NodeState, ...], readiness: Readiness)

NodeState dataclass

Python
NodeState(node_id: str, updates: int, readiness: Readiness, blocked_by: tuple[str, ...] = ())

NodeObservation dataclass

Python
NodeObservation(node_id: str, phase: Literal['learn', 'transform', 'score', 'merge'], inputs: FeatureValues, output: FeatureValues | float | None, duration_ns: int)

Detached values from a call already executed; observation never replays it.

GraphNotReadyError

Bases: PipelineError

Scoring was requested before a complete learned path was ready.

GraphExecutionError

Python
GraphExecutionError(node_id: str, phase: str, message: str)

Bases: PipelineError

A graph operation failed with transformer rollback completed.

GraphStateUncertainError

Python
GraphStateUncertainError(node_id: str, phase: str, message: str)

Bases: GraphExecutionError

A nontransactional learner may have mutated before an unsuccessful pass.

This graph permanently refuses further execution. Restore a known snapshot or construct a fresh graph; retrying the same object cannot repair its state.