# Embedda Oracle SDK

Provide heavy compute (grounding VLMs, open-vocabulary detection) to Embedda
nodes: the swarm calls your **worker** only on the cells it is uncertain about
("directed surge"), over one frozen contract.

LLM agents: operate from [`manifest.json`](manifest.json). Labels are binding.

## The contract (v1, FROZEN)

`libs/swarm/nexus-oracle-wire` — pure serde, model-agnostic. The golden
fixtures in that crate's `tests/fixtures/` ARE the contract (hashes pinned in
`contracts/FROZEN.sha256`):

- Transport: `POST <your-worker>/infer`, body = JSON `OracleRequest`,
  `200` + JSON `OracleResponse`.
- `budget_ms` is a promise: answer partial with `truncated=true` rather than
  blowing past it.
- `none=true` is the model's explicit "nothing here" — distinct from an empty
  list by timeout, and never a skeleton's guess.
- Can't serve a request? Answer an explicit HTTP error with a reason body.
  Inventing results for unsupported queries is a conformance failure.
- The contract names no model (candidate weights carry non-commercial
  licences); `model`/`model_version` on every response keep answers
  attributable.

## Write a worker in three steps

```bash
# 1. copy the stdlib skeleton (it answers honest-501 for everything, and says so)
cp -r sdk/oracle/worker-template my-worker && cd my-worker
# 2. implement handle(request) -> OracleResponse dict
$EDITOR worker.py
# 3. prove conformance (real typed validation, not jq)
sdk/oracle/conformance.sh http://127.0.0.1:9110/infer
```

The reference **real** worker is the Modal deployment in
[`deploy/cloud/modal/`](../../deploy/cloud/modal/) (scale-to-zero cloud GPU) —
linked, not copied.

## Register your worker with the dispatcher

Single worker (legacy, unchanged): `NEXUS_ORACLE_WORKER_URL=http://…/infer`.

Multiple workers with declared capabilities (S3.2 registry, default-off):

```bash
NEXUS_ORACLE_WORKERS='[
  {"name":"modal-vlm","url":"http://127.0.0.1:9110/infer","kinds":["detect","ground"]},
  {"name":"verify-npu","url":"http://127.0.0.1:9111/infer","kinds":["verify"]}
]'
```

Selection is deterministic: first entry whose declared `kinds` cover every
query kind in the request. No covering worker ⇒ an explicit error naming the
unmet kinds — never a silent fallback. A malformed registry is fatal at
startup, never a silent "no oracle".

## Status (honest, per surface)

| Surface | Label |
|---|---|
| Wire contract v1 + golden fixtures | SHIPPED (frozen) |
| Dispatcher → worker HTTP path (`OracleLocalHttp`) | SHIPPED (gated `NEXUS_ORACLE=1`, shadow-first) |
| Multi-oracle registry (`NEXUS_ORACLE_WORKERS`) | SHIPPED (default-off; unit-tested) |
| Worker template + conformance kit | SHIPPED (this SDK) |
| Modal reference worker | SHIPPED (see `deploy/cloud/modal/`) |
| Selection by Expected Free Energy across oracles | ROADMAP — today's selection is declared-capability + first-match, nothing smarter |

## Tests & smoke

```bash
cargo test -p nexus-oracle-wire                          # golden fixtures (frozen)
cargo test -p nexus-oracle-dispatch                      # registry + dispatch units
python3 -m unittest discover -s sdk/oracle/worker-template -v   # template (6 tests)
sdk/oracle/smoke.sh                                      # OPT-IN: template + full conformance
```

## What this SDK does not do

- No service discovery, load balancing or failover between workers — a list
  with declared capabilities, first-match, nothing more.
- No model weights: bring your own, license-clean.
- No cloud budget for you: `cost.usd` you report is REAL measured spend and
  feeds the node's elastic budget ledger — misreporting it corrupts a real
  budget loop.