# ZelPi v2 — 9-Layer Physical-Intelligence Architecture

ZelPi is organised as a 9-layer embodied-AI stack. Each layer is a first-class
runtime component with a live status (`live | sim`) and a latency budget. See it
live with `zelpi stack`.

```
┌─────────────────────────────────────────────────────────────────────────┐
│  1 HUMAN LAYER           Natural Language Prompt                           │ ┐
├─────────────────────────────────────────────────────────────────────────┤ │
│  2 AGENT LAYER           LLM + Reasoning + Planning                        │ │ DELIBERATIVE
│      ├ firewall          screen instruction (injection · unsafe · scope)   │ │ path
│      └ optimiser         plan-cache  (~700ms → <1ms)                        │ │ once / intent
├─────────────────────────────────────────────────────────────────────────┤ │
│  3 MEMORY LAYER          Episodic + Semantic + Skill                       │ ┘
╞═════════════════════════════════════════════════════════════════════════╡
│  4 WORLD MODEL LAYER     Predict Future States · Simulation & Imagination  │ ┐
│      └ optimiser         INT8 · adaptive horizon · rollout cache           │ │
├─────────────────────────────────────────────────────────────────────────┤ │
│  5 POLICY LAYER          VLA / Manipulation / Navigation policies          │ │ CONTROL
│      └ optimiser         quantise · action-cache · batching                │ │ loop
├─────────────────────────────────────────────────────────────────────────┤ │ every tick
│  6 PERCEPTION LAYER      Vision + Audio + Touch + Proprioception           │ │ ~164 Hz
├─────────────────────────────────────────────────────────────────────────┤ │
│  ✦ SPE SAFETY FIREWALL   validate ACTION vs ISO 10218 / TS 15066 / R15.06  │ │
├─────────────────────────────────────────────────────────────────────────┤ │
│  7 HARDWARE ABSTRACTION  Motors · Sensors · Controllers   (native, no ROS) │ │
├─────────────────────────────────────────────────────────────────────────┤ │
│  8 PHYSICAL ROBOT        real robot (native telemetry) | software twin     │ ┘
└─────────────────────────────────────────────────────────────────────────┘
  cross-cutting:  Kernel QoS router · SPE · MCP agent-API     telemetry ▲ feeds back to (4)
```

## Layer reference

| # | Layer | Does | Code | See |
|---|---|---|---|---|
| 1 | Human | NL prompt / operator console | `cli/repl.mjs`, `cli/commands.mjs#intent` | `zelpi intent` |
| 2 | Agent | LLM plan + **firewall** + **plan-cache** | `server/planner.ts`, `cli/spe.mjs#agentFirewall`, `cli/optimiser.mjs` | `zelpi agent` |
| 3 | Memory | episodic · semantic · skill (persistent) | `cli/memory.mjs` | `zelpi memory` |
| 4 | World Model | predict future states · adaptive horizon | `lib/engine.ts`, `cli/spe.mjs#predictTrajectory` | `zelpi spe predict` |
| 5 | Policy | VLA / manipulation / navigation policies | `lib/engine.ts`, `cli/hub.mjs` | `zelpi models` |
| 6 | Perception | vision+audio+touch+proprio · tactile | `cli/spe.mjs` | `zelpi perceive`, `zelpi tactile` |
| — | SPE firewall | validate action vs ISO/ANSI envelope | `cli/spe.mjs#runFirewall` | `zelpi firewall` |
| 7 | HAL | versioned protocol v1 (JSON WS) · e-stop/watchdog/heartbeat · `RobotDriver` adapter · no ROS | `cli/hal.mjs`, `lib/hal/protocol.mjs` | `zelpi hal`, [`docs/HARDWARE.md`](HARDWARE.md) |
| 8 | Physical Robot | real robot agent (native, no ROS) or software twin | `server/robot-agent.mjs` | `zelpi hal connect …` |

Cross-cutting: **Kernel** QoS router (`cli/kernel.mjs`, `zelpi profile`) · **SPE**
optimisation+firewall band (`cli/spe.mjs`, `zelpi spe`) · **MCP** agent API
(`cli/mcp.mjs`, `zelpi mcp`).

## Life of an intent

Tracing `"Retrieve the green box from Aisle 3"`:

1. **Human** — operator submits the intent.
2. **Agent firewall** — screens it (clear / elevated / blocked); a blocked intent never proceeds.
3. **Agent** — plan-cache lookup; on a miss the LLM plans the task + subtasks (result is cached).
4. **Memory** — recall similar episodes/skills *before* planning; *after* dispatch record the episode, learn semantic facts, refresh skills.
5. **Kernel** — routes through the active QoS profile (biases speed vs. safety scrutiny).
6. **World Model** — predicts the future-state trajectory over an adaptive horizon.
7. **Policy** — selects VLA/ACT/M-HAL + nav policy → emits a velocity/skill command.
8. **Perception** — predicts objects/affordances/task-relevance + tactile (force/slip).
9. **SPE firewall** — validates the action vs. the ISO envelope; applies recovery, or raises the HITL gate if high-risk.
10. **HAL** — sends the native skill/cmd over WebSocket (no ROS).
11. **Physical Robot** — executes; telemetry streams back → `setRobotPose` → loop repeats.

Steps 6–11 are the **control loop** (every tick, ~164 Hz); steps 1–5 are the
**deliberative path** (once per intent).

## The two-path optimisation

The core v2 optimisation is splitting the stack into two paths so the slow LLM
never throttles real-time control:

- **Deliberative path** — `Human → Agent → Memory`. Runs **once per intent**. The
  Agent layer's **plan-cache** turns a repeated intent from a ~700 ms LLM call
  into a <1 ms lookup.
- **Control loop** — `World → Policy → Perception → HAL`. Runs **every tick**.
  Quantisation (INT8/INT4) + action-cache + adaptive horizon keep it ~150–250 Hz.

`zelpi stack` reports both budgets and the control-loop Hz.

## Optimisers (Agent · World Model · Policy)

`zelpi optimise` shows the per-layer optimisers and their measured saving:

| Layer | Optimiser | Techniques |
|---|---|---|
| Agent (LLM) | plan-cache | plan cache · prompt compression · distilled fallback · speculative decode |
| World Model | quantise + adaptive horizon | INT8 · adaptive horizon · latent-rollout cache |
| Policy | quantise + cache + batch | quantisation · action/KV cache · request batching |

Tune with `zelpi spe quant int8|int4`. The Agent plan-cache is real and persists
to `~/.pi-os/plan-cache.json`.

## Firewalls (two of them)

- **Agent-layer firewall** (`zelpi agent "<intent>"`) screens the *instruction*
  before it enters the stack: prompt-injection / jailbreak, destructive commands
  ("disable safety", "rm -rf"), and out-of-scope requests. Blocked intents never
  reach planning.
- **SPE safety firewall** (`zelpi firewall`) screens the *physical action*
  against ISO 10218 / ISO-TS 15066 / ANSI-RIA R15.06 force/velocity/collision
  envelopes, with recovery procedures.

## Memory Layer

Real, persistent (`~/.pi-os/memory.json`), three stores:

- **Episodic** — every intent → task → outcome, time-stamped.
- **Semantic** — world facts learned from snapshots (item locations, layout).
- **Skill** — competence registered from deployed policy models.

The Agent recalls relevant episodes/skills before planning (`⟲ memory recall →`).
Inspect with `zelpi memory`, query with `zelpi memory recall "<q>"`.

## Hardware Abstraction Layer — native, DIMOS-style, no ROS

The HAL connects to real robots over a **minimal JSON skill/telemetry protocol on
plain WebSocket** — no ROS 2, no rosbridge, no DDS. A robot only needs the tiny
**native agent** running beside its SDK, which keeps deployment fast.

### Wire Protocol v1

Every frame is versioned (`v: 1`) and validated on inbound (decode-side). All ops:

```
controller → robot : {op:"pose",   id, x, y, theta}      # seed pose (once per robot)
                     {op:"cmd",    id, v_, w, seq}        # velocity (unicycle); ~15 Hz
                     {op:"skill",  id, skill, args, reqId}# high-level skill
                     {op:"estop",  reason}                # latch motion until release
                     {op:"release"}                        # clear e-stop
                     {op:"ping",   t}                      # heartbeat liveness probe

robot → controller : {op:"hello",       caps}             # advertise: kind, drive, limits, skills
                     {op:"welcome",     accept, reason}   # link established (or rejected)
                     {op:"telemetry",   id, x, y, theta, ts, vx?, w?, battery?, joints?, estop?, faults?}
                     {op:"skillResult", id, reqId, status, progress?, error?}
                     {op:"fault",       id, code, message, severity}  # out-of-band errors
                     {op:"pong",        t}                 # heartbeat reply
```

Key details:
- **Protocol version mismatch** → controller rejects and closes the link.
- **Malformed frames** → silently dropped (never crash).
- **E-stop latch** → robot refuses motion until `release`.
- **Watchdog** (500 ms default) — link silence → safe-stop (zero all velocity).
- **Heartbeat** (500 ms) — controller sends `ping`, expects `pong` within 1.5 s; link stale → safe-stop + auto-reconnect.

For the complete protocol spec, message shapes, field semantics, and unit contract, see [`docs/HARDWARE.md`](HARDWARE.md).

### RobotDriver Interface

To go from sim to real hardware, implement one `RobotDriver` against your SDK:

```typescript
interface RobotDriver {
  capabilities(): Capabilities
  seedPose(id, x, y, theta): void
  applyCmd(id, v, w): void
  async runSkill(id, skill, args): Promise<{ status, error? }>
  readTelemetry(id): { x, y, theta, vx?, w?, battery?, joints? } | null
  estop(): void
  release(): void
}
```

See [`docs/HARDWARE.md`](HARDWARE.md) for skeleton drivers (Unitree, xArm, AgileX).

### Deploy (trivial)

Robot side = 3 files + 1 npm dep:
1. `server/robot-agent.mjs` — agent loop.
2. `lib/hal/protocol.mjs` — codec.
3. `package.json` — lists `ws`.

Then:
```bash
node server/robot-agent.mjs --driver unitree   # (or --driver=xarm, etc.)
```

When a link is up, the engine yields pose integration to the robot
(`setExternalControl`) and ingests telemetry (`setRobotPose`) — so the World-Model
/ Policy layers drive **real hardware** through the same seam they drive the twin.

### Quick Start

```bash
# 1. on the robot (or locally to demo): run the native agent
node server/robot-agent.mjs                      # ws://127.0.0.1:9091   (sim driver)

# 2. link the OS to it
zelpi hal connect ws://127.0.0.1:9091
zelpi stack                                      # HAL + Physical Robot now ● live
zelpi intent "Patrol Aisle 1"                    # the robot moves; pose from telemetry
zelpi hal disconnect                             # back to the software twin

# 3. safety commands
zelpi hal estop "reason"                         # emergency stop (motion refused)
zelpi hal release                                # clear e-stop, resume
zelpi hal skills                                 # list advertised skills & hardware metadata
```

> Deprecated: the legacy ROS 2 rosbridge link (`server/rosbridge.ts`,
> `zelpi up --ros`) still exists but is no longer the recommended path — the
> native HAL is faster to deploy and runs inside the embedded backend.