Pipeline

Layer 2: Compose

Pipeline is a DSL for describing components and structured control regions. It does not execute OptimizationState directly; Optimizer uses it as input when building an execution plan.

from saealib import Branch, Loop, Pipeline, Repeat

pipeline = Pipeline(
    name="generation",
    steps=[
        Repeat(
            Pipeline(steps=[ask, acquire, tell], name="surrogate_generation"),
            count=10,
            name="surrogate_generations",
        ),
        Loop(evaluation, until=budget_reached, name="evaluation_loop"),
        Branch(route, then=fast_path, else_=safe_path, name="route"),
    ],
)

This example only shows how to build a Pipeline. In ordinary use, Optimizer compiles the Graph and Pipeline produced by a Strategy, so users do not need to call the Compiler directly.

Nested Pipelines and control values are kept as named structured regions. Repeat represents a fixed number of repetitions, while Loop and Branch evaluate conditions through declared state contracts. Because regions are not reduced to ordinary graph cycles, the Runtime can preserve state effects and resume frames.

Components placed in a structured Pipeline provide the graph-native contract() and execute(StateView) boundaries. The legacy Stage execution surface remains as a connection point for the compatibility Graph Builder. When placing an existing Stage in a structured Pipeline, wrap it explicitly with stage_component(stage).

During compilation, required input ports are matched to compatible outputs upstream in control order. A uniquely matched connection becomes a DataEdge; no match or multiple candidates produces a Compiler diagnostic. Use an explicit Graph when an ambiguous connection must be resolved.

stage_component(stage) is a migration adapter. State writes through the transaction proxy become StatePatch values, but the adapter retains ownership of mutable objects exposed as Services or Context capabilities. In a new graph-native component, keep persistent mutable state behind declared StateKey values and patches.

saealib.Stage	Abstract base class for a compatibility execution step.
saealib.Pipeline	An ordered structural DSL sequence lowered to a semantic graph.
saealib.Repeat	Repeat a structural body a fixed number of times.
saealib.Loop	Repeat a structural body while a condition remains active.
saealib.Branch	Select one of two structural bodies using a condition.