`README.md`

44 lines
# exo-preflight

Cluster-health **gate** for the tiered-hybrid model-routing policy (DTD verdict A, 2026-08-13).

Before a pipeline routes a **production-feeding** job to the exo ring at "$0 local",
it must confirm the ring can actually hold the load. A degraded cluster (a node
offline, the requested model not loaded) must **not** silently proceed — the caller
queues the job or escalates to a paid API **and logs the fallback**. This script is
that check. It's read-only: it only GETs exo's `/state`.

## Usage

```sh
python3 preflight.py                      # is the ring healthy for any bulk job?
python3 preflight.py --model llama-3.1-70b  # ...and is THIS model loaded + ready?
python3 preflight.py --json               # machine-readable
python3 preflight.py --expect-nodes 4     # require the full 4-node fleet
```

### Exit codes
| Code | Verdict | Caller should… |
|---|---|---|
| `0` | HEALTHY | route the job to the ring ($0 local) |
| `2` | DEGRADED | queue the job **or** escalate to a paid API + log the fallback |
| `3` | UNREACHABLE | treat as DEGRADED |

### In a pipeline
```sh
if python3 /Users/macstudio3/Projects/exo-preflight/preflight.py --model llama-3.1-70b -q; then
    run_on_ring                 # $0 local
else
    escalate_to_paid_and_log    # per the routing policy — never silently proceed
fi
```

## Notes
- Default healthy baseline is **3 live nodes** — the 4th M1 Max is often offline by
  design. Override with `--expect-nodes N` or `EXO_EXPECT_NODES`.
- OS-build mismatch across nodes is surfaced as **informational** (fine for routing;
  it only blocks RDMA), never a hard fail.
- Zero dependencies (Python stdlib only). Reads `http://<node>:52415/state`.

See the standing policy + cluster facts in memory: `model-routing-policy`, `exo-cluster-topology`.