Platform Guide

Workflows & pipelines

Versioned graphs of typed steps with checkpoints, retries, idempotency, and dead-letter handling. Workflow Studio compiles the same contract the API executes.

Runs that finish — not runs that disappear

Every step is checkpointed as it completes (src/lace/pipeline/runtime.py). A crash, timeout, or restart resumes from the last completed step — not from the start, and not by vanishing. Idempotency keys make a retried step safe to re-execute even if it already did work. Work that cannot succeed lands in a dead-letter queue where it can be inspected instead of being silently dropped. Traces are emitted per step and surfaced in Studio and the observability stack.

Typed steps — a compile-time failure beats a 3am production failure

Each step declares its input and output JSON Schemas. The compiler (src/lace/pipeline/compiler.py & control_flow.py) validates the graph — wrong shape between two stages fails at compile time, not in production. Steps can be tools, LLM invocations, sub-pipelines, or control-flow primitives:

Primitive	What it does
`branch` / `switch`	Conditional fan-out
`foreach` / `parallel_foreach`	Iterate sequentially or in parallel
`parallel`	Concurrent steps with join
`reduce` / `repeat_until`	Accumulate / loop until condition
`trycatch` / `fallback`	Handle failures without aborting the graph
`delay` / `wait_until` / `wait_for_input`	Time & human gates

AppPipelineProvider is how apps contribute pipelines to the platform — see pipelines (SDK) for the provider contract and a full code example.

Workflow Studio — the visual compiler

Studio is a visual compiler over the same PipelineDefinition schema. You drag steps, bind inputs/outputs, set retry policies and idempotency keys, declare triggers and aliases, and Studio emits YAML the runtime executes verbatim. There is no "Studio-only" runtime that drifts. Drafts, versions, triggers, and the full run timeline (trace_report, replay) are part of the same model.

Operating workflows

POST /v1/pipelines/{pipeline_id}/runs — start a run.
GET /v1/pipelines/{pipeline_id}/runs/{run_id} — trace + step statuses.
From an agent: declare a PipelineCapability so the model can dispatch to a workflow.
On a schedule: declare AppScheduleSpecDeclaration with invoke_path at the manifest.

Reference: pipelines (typed graphs). Product context: Enterprise Search and Knowledge Graph both run as pipelines underneath.