Typed graph pipelines

A graph is built from nodes that each declare an input artifact type and an output artifact type, so the pipeline reads like the sentence it describes — Detect → Filter → PromptBoxes → Fuse. Detections, masks, classifications, depth maps, tracks and regions are all typed artifacts rather than loose arrays.

The same graph can be written as a pipe, as explicit wiring, or as a list passed to mata.infer(). All three compile to the same validated structure, so a team can start with the short form and keep it readable as the pipeline grows.

graph.compile(providers) runs the GraphValidator over the whole structure. When something is wrong, a ValidationError lists each problem with the node and the artifact involved — at compile time, not on the first frame of a live stream.

• Name collisions — every node name is unique.
• Dependency resolution — every input artifact is produced upstream or supplied as a graph input.
• Type compatibility — connected artifacts must match, so a DepthMap cannot be wired into a node that expects Image.
• Cycle detection — the structure has to stay acyclic.
• Provider capabilities — every referenced provider exists in the registry with the capability it is asked for.

After validation, the graph is sorted into stages, and nodes with no dependency between them land in the same stage. Detection, classification and depth estimation on one frame execute as a group rather than one after another, which is where the documented 1.5–3× speedup comes from.

Three schedulers cover different deployments: SyncScheduler in topological order for debugging, ParallelScheduler for independent work, and OptimizedParallelScheduler for device placement, multi-GPU execution and model unloading.

Branching and looping are graph primitives rather than surrounding Python. A node can carry a condition and is skipped when that condition is false, so empty frames cost nothing and low-confidence detections never reach an expensive segmentation stage.

• EarlyExit — stop a branch as soon as its purpose is served.
• While — repeat a stage until a quality threshold is met.
• Graph.add(condition=...) — attach a conditional edge to any node.
• Filter — drop detections below a score before downstream work.

Cheap decisions run first; expensive models run once, on the frames that deserve them.

A completed run returns a multi-task result bundle with named channels — result.final.dets.instances, result["final"]["masks"].instances — and a stable instance identity that survives fusion, so a detection and its mask remain the same object across stages.

Three observability subsystems are wired into execution and need no instrumentation: MetricsCollector records per-node latency and memory, ExecutionTracer emits hierarchical spans, and ProvenanceTracker records the model and graph configuration behind a result.

• Per-node metrics, exported as a summary with total and wall-clock latency.
• Execution traces exported as JSON for review after a run.
• Provenance entries carrying the model type and hash for each provider.

Presets cover the common shapes — grounding_dino_sam, full_scene_analysis, defect_detect_classify, crowd_monitoring and others — and each one is simply a graph factory, so a working pipeline is a starting point rather than a target.

For long or distributed workloads, storage nodes persist results to Valkey through a valkey:// URI and read them back later as artifacts, without any other node in the graph being aware of it.

• A preset is a factory: call it with parameters, get a graph you can compile, inspect and extend.
• Cases that repeat across projects are worth promoting to a preset of your own.
• The graph that runs in production is the same object you debug on a laptop, which keeps the two from drifting apart.