## megachad decision API

megachad (https://megachadcua.com) answers a schema of questions about text or speech: each field is one of N options, yes/no, or a scale, and comes back with a calibrated confidence. The model decides in ~17 ms. Full reference: https://megachadcua.com/llms-full.txt.

Key:

- The key is in the env var `MEGACHAD_API_KEY` (`mcc_live_...`). Read it at runtime. Never hardcode, commit, print or log it; never send it to a browser.
- If it's unset, stop and ask the user to get one at https://megachadcua.com/login?signup=1 and set it. Don't sign up for them.
- Keep `.env` in `.gitignore`.

Call (raw HTTP is the default; no SDK needed):

```bash
curl https://api.megachadcua.com/v1/decide \
  -H "Authorization: Bearer $MEGACHAD_API_KEY" \
  -H "content-type: application/json" \
  -d '{"schema": {"action": {"question": "What should the agent do?", "options": ["Click Sign in", "Scroll down", "Nothing yet"]}}, "text": "take me to sign in"}'
```

Response (200):

```json
{"session_id": "dcd_C8o5VFBm5AH65L7e", "fields": {"action": {"value": "Click Sign in", "confidence": 0.98, "probabilities": {"Click Sign in": 0.98, "Scroll down": 0.012, "Nothing yet": 0.008}}}, "transcript": "take me to sign in", "latency_ms": 112, "model_ms": 15.2, "usage": {"credits": 1}}
```

- Field kinds: `{"question": "...", "options": ["A", "B", "Nothing yet"]}`, `{"question": "...", "type": "yes_no"}`, `{"question": "...", "scale": ["low", "medium", "high"]}`.
- `text`: a string, or `[{"speaker": "user" | "other", "text": "..."}]`.
- Up to 50 texts per call: `POST /v1/decide/batch` with `{"schema", "items": [{"id", "text"}]}`. Live voice: `WS /v1/listen`.
- Schema: one question per field; short, distinct options with a way out ("Nothing yet", "Not sure"); option labels as the user sees them. The value comes back verbatim.
- Act only at or above a confidence threshold (start at 0.85); below it, confirm with the user. `confidence` can be `null`: treat as unsure. A human confirms destructive, financial or medical actions. Medical: it routes and structures for clinicians; it doesn't diagnose.
- Errors: `{"error": {"code", "message"}}`. Retry 409, 429 and 5xx with backoff and `Retry-After`, sending the same `Idempotency-Key` (a UUID per request) so a retry is never billed twice. Don't retry 400, 401, 402, 403, 413, 422; 402 and 403 need the user.
- SDKs: `pip install megachad` or `npm i megachad` (0.1.0: `decide`, `listen`); MCP: `npx -y megachad-mcp`. SDK batch and retry helpers are coming in 0.1.1; don't use them yet.
- Tests mock the HTTP call; real calls cost 10¢ per 1,000.