> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadenzalabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Inference orchestration

> Sequential and ChainOfThought: how a VLA thinks and acts during a run.

An **orchestrator** decides *how* a model interacts with motor execution: when to
run inference, how to handle interruptions, and when to inject recovery actions.
You attach one at construction, and the robot controller delegates every step to it.

```python theme={null}
from cadenza.inference import Sequential, ChainOfThought
import cadenza_lab as cadenza

go1 = cadenza.go1(inference=Sequential())
go1.run([go1.walk_forward(distance_m=5.0)])
```

Without an orchestrator, `go1.run([...])` executes **open-loop**, with no model in
the loop. With one, each `Step` is run under the strategy's control.

```mermaid theme={null}
flowchart TD
    RUN["go1.run([...])"] --> SETUP["orchestrator.setup(robot, sim, lib)"]
    SETUP --> LOOP{for each Step}
    LOOP -->|run_step| STRAT[strategy]
    STRAT --> EXEC[robot._execute_single]
    EXEC --> SIM[Sim · motors]
    SIM -->|observation| STRAT
    LOOP -->|done| TEAR["orchestrator.teardown()"]
```

## `Sequential`: think then move

Single-threaded "guard while you act". For each action, a **guardian** (default:
`VLAGuardian`, a small VLM on the forward camera) watches for obstacles. On a
detection mid-action:

1. The current step is cut short at whatever fraction completed.
2. The guardian emits an avoidance sequence (turn / side-step / wait).
3. Avoidance runs with the guardian off (no recursive interrupts).
4. The original action resumes with the remaining distance, bounded by
   `retries` so the robot can't thrash.

```python theme={null}
Sequential(*, show_camera=True, model_id=None, min_resume_distance_m=0.1,
           retries=5, guardian=None, logging=None)
```

| Param                   | Description                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `show_camera`           | Show the guardian's live camera window.                                            |
| `model_id`              | Override the guardian's VLM checkpoint.                                            |
| `min_resume_distance_m` | If less than this remains after an interrupt, drop the action instead of resuming. |
| `retries`               | Max VLA interrupts per step before abandoning (`None` = ∞).                        |
| `guardian`              | Custom detector: a class, factory, or instance.                                    |
| `logging`               | Path to a JSON-Lines event log (for later training).                               |

## `ChainOfThought`: think while you move

Concurrent inference and execution. While the robot executes action N, a
background worker is already running the next inference pass to produce N+1, so
there's no dead time waiting on the model.

```text theme={null}
tick 0  main: ───── exec A0 ─────
        bg:             [ infer A1 ]
tick 1  main: ───── exec A1 ─────
        bg:             [ infer A2 ]
```

```python theme={null}
ChainOfThought(*, model=..., sense=[...], goal="...", target=(x, y),
               max_steps=80, logging=None)
```

The `model` is any [`WorldModelAdapter`](/sdk/inference-stack). `sense` is a list
of [modalities](/sdk/inference-stack#modalities) merged into each observation.
Any trigger `Step` you pass to `run()` hands control to the orchestrator.

## Demo: guarded walk

```python theme={null}
"""demo_orchestration.py: guarded walk with the Sequential strategy.
Opens a MuJoCo window (needs a display). The guardian needs the `ai` extra
(torch) and downloads a small VLM on first run.   pip install "cadenza-lab[ai]"
"""
import cadenza_lab as cadenza
from cadenza.inference import Sequential

go1 = cadenza.go1(
    xml_path=cadenza.Go1.terrain("terrain"),
    inference=Sequential(show_camera=True, retries=5, logging="runs/episode.jsonl"),
)
go1.run([go1.walk_forward(distance_m=5.0)])   # guardian interjects around obstacles
```

```bash theme={null}
pip install "cadenza-lab[ai]"
python demo_orchestration.py
```

<Tip>
  Orchestration controls *timing and interruption*. To swap the actual decision
  model, or to run a goal-directed loop end to end, use the
  [inference stack](/sdk/inference-stack).
</Tip>