85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
# 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 *(planned)* |
|
|
|
|
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. |