Examples and Results

Run one cell, compare its real output, then read what the graph did. The commands below are Pixi tasks from the source checkout; the output blocks are captured verbatim (INFO log lines stripped). Because Retriever is functionally deterministic, these results reproduce run to run.

What you’ll get: a concrete path from a one-Flow function up to visual perception, a rendered graph, and a recorded run you can replay.

Cell 1: The smallest Flow

Command

pixi run demo-basic-flow

Output

============================================================
DoubleFlow - direct attribute access
  Input type: NumberInput
  Output type: NumberOutput
  [DoubleFlow] input.value=5 → result=10
  Result: NumberOutput(result=10)

============================================================
SignalAwareFlow - _signals pattern matching

  Case 1: Empty input (no signals)
  empty_input._signals = []
  [SignalAwareFlow] input._signals=[]
    No signals - skipping

  Case 2: Input with value
  full_input._signals = ['value']
  [SignalAwareFlow] input._signals=['value']
    value=7 → result=14
  Result: NumberOutput(result=14)
============================================================

What this teaches: a Flow is ordinary Python. IO types are declared with @io, the class is Flow[Input, Output], and your logic lives in step(). _signals lets a Flow tell “field absent” from “field present” — the basis for composing partial inputs.

Cell 2: Step a graph in-process

Command

pixi run demo-stepper

Output

=== step 0 ===
[Sink] got value=2

=== step 1 ===
[Sink] got value=4

=== step 2 ===
[Sink] got value=6

=== step 3 ===
[Sink] got value=8

=== step 4 ===
[Sink] got value=10

What this teaches: before launching any backend you can advance the whole graph one step at a time with pipe.step(dt=…). This is where you set a breakpoint inside step(), inspect local state, and reproduce a small failing case.

Cell 3: Step perception without a camera

Command

pixi run demo-perception-stepper

Output

=== step 0 ===
[PrintDetections] frame=1 labels=['blue_object']

=== step 1 ===
[PrintDetections] frame=2 labels=['red_object']

=== step 2 ===
[PrintDetections] frame=3 labels=['blue_object']

What this teaches: the perception graph steps on deterministic mock frames, so the first debugging loop is independent of camera permissions, GUI windows, and backend scheduling.

Cell 4: Run the perception pipeline

Command: deterministic first smoke

pixi run demo-webcam-detection-mock

Output

============================================================
Perception Demo - Live or Mock Camera to Detection

Building perception pipeline:
  Camera @ Rate(20Hz) -> ColorDetector @ Trigger -> Display @ Rate

✓ Graph created: 3 nodes, 5 edges

Running for 0.1 seconds...
Tip: This run is using mock frames. Use --camera-mode real to require a live webcam path.
------------------------------------------------------------
  Frame 1: 2 objects - [('red_object', '0.95'), ('blue_object', '0.95')]
------------------------------------------------------------

============================================================
Pipeline Summary

Camera Input:
  • Uses mock test pattern when mock mode is selected or auto fallback triggers

Detection:
  • Red objects: RGB(255, <100, <100)
  • Blue objects: RGB(<100, <100, 255)
============================================================

Command: live webcam and Rerun/stdout

pixi run demo-webcam-detection

What this teaches: the visual demo is the same three-Flow graph — camera, detector, display — as the stepper. The mock target gives a stable expected result for docs, tests, and remote machines; the live target runs the identical graph on a real webcam with Rerun when available.

Cell 5: Render the graph before debugging timing

Command

pixi run docs-tutorial-perception-html

Output

[Success] Visualization saved to: artifacts/tutorial_perception.html
Open this file in your browser to view the interactive graph.

What this teaches: open artifacts/tutorial_perception.html to see Flow nodes, ports, clocks, and per-edge sync policies. Inspect the graph before blaming backend scheduling.

Cell 6: Record a run, then replay it

Command: record 10 mock steps

pixi run demo-webcam-record

Output

[Recording] saved 10 steps to logs/perception.rrd, logs/perception.mcap
[Recording] mock frame mode was used for deterministic artifact generation.

Command: replay the recording

pixi run demo-webcam-replay-rrd

Output

  Frame 1: 2 objects - [('red_object', '0.95'), ('blue_object', '0.95')]
  Frame 2: 2 objects - [('red_object', '0.95'), ('blue_object', '0.95')]
  Frame 3: 2 objects - [('red_object', '0.95'), ('blue_object', '0.95')]
  Frame 4: 2 objects - [('red_object', '0.90'), ('blue_object', '0.95')]
  Frame 5: 2 objects - [('red_object', '0.79'), ('blue_object', '0.95')]
  Frame 6: 2 objects - [('red_object', '0.66'), ('blue_object', '0.95')]
  Frame 7: 1 objects - [('blue_object', '0.95')]
  Frame 8: 1 objects - [('blue_object', '0.95')]
  Frame 9: 1 objects - [('blue_object', '0.95')]
  Frame 10: 1 objects - [('blue_object', '0.95')]
[Replay] ran 10 steps from logs/perception.rrd

What this teaches: a run becomes a portable artifact (.rrd and .mcap). Replay reproduces the exact trace — watch the red-object confidence decay from 0.95 to 0.66 and then drop out at frame 7 — so you can debug downstream logic without the original sensor timing. This is functional determinism made concrete: the same recorded input yields the same output.

Where to go next

Understand FlowThe stateful stream-function model behind these examples.Understand timeClocks decide when a Flow runs; sync policies decide which input it reads.Debug deliberatelyGraph render, stepping, Rerun, record, and replay.Run the first GoldenRetriever proofMove from runtime primitives to a robot-facing Hub pack.