Add overview, agent-api, clients docs for Jervis voice agent

2026-08-30 14:42:11 +10:00
commit 4b86c18622
5 changed files with 283 additions and 0 deletions
--- a/docs/clients.md
+++ b/docs/clients.md
@@ -0,0 +1,73 @@
+# Clients & Gateways
+
+> Ways to talk to Jervis — **type it**, a **web page**, or your **Android** — all sending text to the same agent (`POST :8501/voice` or MQTT). You do not need the ESP32 to use the brain; any of these work.
+
+---
+
+## 1. Type it (terminal)
+
+```bash
+curl -X POST http://192.168.20.13:8501/voice \
+  -H "Content-Type: application/json" \
+  -d '{"text":"add eggs to the shopping list"}'
+```
+Alias for convenience (add to `~/.bashrc` / `~/.zshrc`):
+```bash
+jervis() { curl -s -m60 -X POST http://192.168.20.13:8501/voice -H "Content-Type: application/json" -d "{\"text\":\"$*\"}"; echo; }
+# usage: jervis add milk to the shopping list
+```
+
+---
+
+## 2. Web page (type + voice input)
+
+A single-file HTML page that:
+- lets you type a command (POSTs to the agent), and
+- uses your browser's **Web Speech API** so you can *speak* into it (works in Chrome/Edge, incl. desktop).
+
+Save as `voice.html` and open it, or serve it. Example (`speech-to-text` → POST):
+
+```html
+<!doctype html><html><head><meta charset="utf-8"><title>Jervis</title></head>
+<body style="font-family:sans-serif;max-width:640px;margin:2em auto">
+<h1>Jervis</h1>
+<input id="t" style="width:80%;padding:.5em" placeholder="Type a command…">
+<button onclick="send()">Send</button>
+<button onclick="mic()">🎤 Speak</button>
+<div id="r" style="margin-top:1em;white-space:pre-wrap"></div>
+<script>
+const API="http://192.168.20.13:8501/voice";
+async function send(tx){const r=await fetch(API,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({text:tx})});const j=await r.json();document.getElementById("r").textContent=(j.reply||j.error||"");}
+document.addEventListener("keydown",e=>{if(e.key==="Enter")send(document.getElementById("t").value)});
+function mic(){const S=window.SpeechRecognition||window.webkitSpeechRecognition;if(!S){alert("Speech recognition unsupported in this browser");return;}const sr=new S();sr.lang="en-AU";sr.interimResults=false;sr.onresult=e=>{const t=e.results[0][0].transcript;document.getElementById("t").value=t;send(t)};sr.start();}
+</script></body></html>
+```
+> ⚠️ The page calls the LAN IP directly — fine on your home network. If served off the LAN, add CORS to the agent and use a LAN-only endpoint or Tunnel/WireGuard.
+
+---
+
+## 3. Android
+
+Best options, in order of simplicity:
+
+- **Browser speech** — open the `voice.html` above on your phone and tap 🎤 (works in Chrome on Android; uses your phone's speech recognition). **Zero install.**
+- **Home Assistant Companion (mobile app)** — you already have HA. Configure an `assist`/text pipeline that forwards to the agent's reply (HA already consumes the same MQTT topic the agent uses). This ties into the app you already run.
+- **KWGT / Tasker / MacroDroid** — a quick action that captures voice → POSTs to `:8501/voice` (Tasker "HTTP Post" with your chosen TTS engine).
+
+All three just send text to the same endpoint — they don't care about the ESP32.
+
+---
+
+## Other callers
+
+- **N8N / Prefect** — HTTP node → `POST :8501/voice` (or MQTT publish) to trigger + hear.
+- **MQTT** — publish to `homeassistant/voice/text` on broker `.30`; the agent speaks the reply.
+- **Another AI model / assistant** — call `POST :8501/voice` like any function (see `agent-api.md`).
+
+---
+
+## Planning notes (not yet implemented)
+
+- Per-person Apprise notifications (sam/jo/harry/finn) — `send_message` tool (planned).
+- Calendar read via N8N webhook returning the day's events — `calendar` tool (planned).
+- Native Android app / always-listening mic — future.