# ZelPi — SPE (State Perception Engine)

The **State Perception Engine** is the predictive layer ZelPi runs between
**System 2** (intent) and **System 0** (torque). Before the fleet acts it answers
three questions:

1. **Perceive** — what will the robot *understand* a few steps from now (objects,
   affordances, spatial relations, task-relevance) — not just what it will *see*.
2. **Optimise** — can that be inferred inside the latency budget? (quantisation ·
   caching · adaptive horizon)
3. **Validate** — is the predicted action inside the industrial safety envelope?
   (force / velocity / collision limits + ISO/ANSI compliance, with recovery)

It is implemented in [`cli/spe.mjs`](../cli/spe.mjs) as a **zero-dependency,
deterministic** module: every figure is derived from the live world snapshot via
a stable hash, so the same world + task always yields the same prediction —
matching ZelPi's seeded, reproducible engine.

## Commands

```bash
zelpi spe                                   # engine status: quantisation · cache · horizon · latency budget
zelpi perceive "Retrieve the green box"     # perception predictor (objects, affordances, task-relevance)
zelpi spe predict [--horizon n]             # world-model trajectory: proprio/visual/perception confidence
zelpi tactile [--robot Atlas-01]            # grasp prediction: contact, force, slip, stability
zelpi firewall [assembly|human-collab|precision]   # validate the live fleet vs. the safety envelope

zelpi spe quant <fp32|fp16|int8|int4>       # set inference quantisation (persists)
zelpi spe task  <assembly|human-collab|precision>  # set the active firewall constraint set (persists)
```

The SPE summary also rides the top-level surfaces:

- `zelpi status` gains an **SPE engine** line (quantisation · cache · latency · speedup · firewall set).
- `zelpi intent "..."` runs an **SPE pre-flight**: a `perceive →` line (the target
  object + relevance/confidence) and a `firewall →` line (clear, or violations +
  the recovery procedure) before the task is handed to the fleet.

## How the SPE spec maps to the code

| SPE spec component | Where it lives in ZelPi |
|---|---|
| **State representation** (proprio + visual + tactile) | reads the live `Robot` (`joints[7]`, `torque`, `status`, `pos`) + world `items`/`shelves` from the snapshot. |
| **Perception predictor** ("predict what it will UNDERSTAND") | `spe.predictPerception()` — grounds objects in the actual nearest warehouse items; infers affordances, spatial relations, per-object task-relevance and overall semantic accuracy from the intent text. |
| **World model** (dual-stream trajectory) | `spe.predictTrajectory()` — proprioceptive/visual/perception confidence over an **adaptive horizon** (2–10 steps) that stops early when confidence drops; kernel scrutiny biases the decay. |
| **Tactile prediction** (contact / force / slip) | `spe.predictTactile()` — gripper opening, fingers in contact, grasp force (N), slip likelihood, estimated mass/μ, stability margin. |
| **Inference optimisation** (quantise · cache · batch · adaptive horizon) | `spe.QUANT` levels (FP32/FP16/INT8/INT4) + `spe.latencyBreakdown()` — per-stage latency, cache-weighted effective inference, effective speedup vs FP32, and a within-budget check (~Hz). |
| **Safety firewall** (constraints · recovery · compliance) | `spe.CONSTRAINTS` (assembly / human-collab / precision) + `spe.runFirewall()` — validates predicted force/velocity/clearance, emits the recovery procedure, and rolls up ISO 10218 / ISO-TS 15066 / ANSI-RIA R15.06 compliance. The **kernel QoS profile** tightens the effective limits (scrutiny). |

## Constraint sets

| Set | Force | Velocity | Clearance | Standards |
|---|---|---|---|---|
| `assembly` | ≤ 50 N | ≤ 0.3 m/s | ≥ 20 mm | ISO 10218 · ANSI/RIA R15.06 |
| `human-collab` | ≤ 220 N (140 N sustained) | ≤ 0.5 m/s | ≥ 50 mm | ISO/TS 15066 · ISO 10218 · ANSI/RIA R15.06 |
| `precision` | ≤ 25 N | ≤ 0.15 m/s | ≥ 5 mm | ISO 10218 · ANSI/RIA R15.06 |

The active profile re-tunes these live: e.g. `system-critical` (scrutiny ×1.8)
divides the force limit and tightens velocity, so the firewall trips earlier.

## MCP tools

The SPE is exposed to AI agents over MCP (`zelpi mcp`) alongside the fleet tools:

- `pios_spe_status` — quantisation, cache, horizon, constraint set, latency budget.
- `pios_perceive` — perception prediction for an intent (`{ task, robot? }`).
- `pios_firewall` — fleet-wide firewall validation (`{ set? }`).
- `pios_tactile` — grasp prediction for a robot (`{ robot, task? }`).

## Connected mode

In the embedded/offline backend the figures are deterministic stand-ins. Point
the CLI at a full backend (`PIOS_HOST` / `PIOS_WS_URL`) to drive the same SPE
surface over real perception/world-model inference — the command set is identical.