# Voice-Agent Command API

> The stable contract for sending a command to the Jervis LLM service and getting a spoken reply.
> Works for **any** AI model, script, N8N workflow, ESP32, web page, or Android app — not just Home Assistant.

---

## Quick start

**Send a command (HTTP):**
```bash
curl -X POST http://192.168.20.13:8501/voice \
  -H "Content-Type: application/json" \
  -d '{"text":"add chicken to the shopping list"}'
# → {"text":"add chicken to the shopping list","reply":"Done, I've added chicken to your shopping list."}
```

The reply is **also spoken** through your speakers via Snapcast.

**Send a command (MQTT):**
```bash
mosquitto_pub -h 192.168.20.30 -u mqtt-user -P <pass> -t homeassistant/voice/text -m "what time is it"
```
Same effect — the agent picks up the topic and speaks the reply. (Use whichever transport is easier for the caller.)

---

## Endpoint

| Method | Path | Body | Returns |
|---|---|---|---|
| POST | `/voice` | `{"text": "<command>"}` | `{"text": ..., "reply": ...}` |
| GET  | `/health` | — | `{"status":"ok","model":"..."}` |

- **Base URL:** `http://192.168.20.13:8501`
- **Optional:** `{"message": "..."}` can be used instead of `{"text": "..."}`.

---

## What the LLM can do (tools it will call)

| Example command | Tool | Backend |
|---|---|---|
| "what time is it" | `get_time` | built-in |
| "what's the weather" | `get_weather` | Open-Meteo |
| "add milk to the shopping list" | `add_shopping_item` | KitchenOwl |
| "turn on the lounge lights" | `control_ha` | Home Assistant REST |
| "remind me to water the plants" | `set_reminder` | HA notification |
| "feed the fish" | `feed_fish` | HA `input_button.fish_feeder` |
| "put on your Donald Trump voice and tell me a joke" | `speak_as` | piper (per-character) |
| "send {topic}/{payload}" (advanced) | `ha_service_cmd` | HA any service |
| any open question | `answer` | OmniRoute LLM |
| "play {artist/album}" | `play_music` | Mopidy → Spotify (gst-plugin-spotify + credentials.json) ✅ |

The LLM picks the tool automatically from natural language — you don't pick it.

---

## Voices (for `speak_as`)

`trump`, `donald`, `hal`, `hal 9000`, `picard`, `captain`, `eminem`, `glados`, `ryan`, `alan`, `bt`/`bt7274`, `mech`.

---

## Notes for other AI agents

- The same text can be sent by any model/caller — the agent does the reasoning + tool dispatch + speaking.
- For non-voice callers (N8N, scripts) that just want the **reply text without speaking**, the agent currently speaks by design (voice assistant). A `?speak=0` / `{"speak": false}` option can be added if needed.
- Timeouts: LLM tool loops are bounded (max 5). Expect a few seconds for tool calls.

---

## Config / env (`/home/sam/voice-agent/.env`)

| Var | Meaning |
|---|---|
| `LLM_BASE`, `LLM_MODEL`, `LLM_KEY` | OmniRoute endpoint + model |
| `HA_URL`, `HA_TOKEN` | Home Assistant REST + long-lived token |
| `KITCHENOWL_URL/_HOUSEHOLD/_LIST/_USER/_PASS` | KitchenOwl shopping write |
| `MQTT_BROKER/_TOPIC/_USER/_PASS` | text intake + output |
| `SPEAK_CMD`, `DEFAULT_VOICE` | piper TTS command/voice |
| `LAT`, `LON` | weather location |
| `AGENT_PORT` | HTTP port (`8501`) |

Secrets live in `.env` (gitignored) — never commit them.