Initial Central AI Hub docs: brief, rules, README, outline context, architecture

2026-10-10 14:44:54 +11:00
commit b3658132dd
14 changed files with 14404 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,81 @@
+# Central AI Hub
+
+One small service that every way in reaches every ability through. Built once,
+shared by the phone app, the house voice, chat, and the admin app.
+
+## Demonstrated Skills & Tech Stack
+
+- **Core Technologies**: Go or Python service · HTTP JSON API · MQTT · LLM
+  intent routing · OmniRoute gateway · Docker
+- **Key Tools**: Jervis (voice) · Home Assistant · Paperclip · Artemis ·
+  internet use control · Apprise / NTFY · OmniRoute
+- **Engineering Capabilities**: service design · intent routing · authorization
+  and approval flows · event-driven integration · deterministic safety for
+  high-consequence actions
+
+## Quick Start
+
+```bash
+# Phase 1 — prove the Paperclip round trip
+# 1. Create an agent API key in Paperclip.
+# 2. Export it for the test only.
+export PAPERCLIP_API_KEY=<redacted>
+# 3. File one job.
+curl -s -X POST http://192.168.20.13:3100/api/issues \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"round-trip test","description":"prove the return path"}'
+```
+
+Full steps: `docs/outline/04-agent-runbook.md`.
+
+## System Architecture
+
+```mermaid
+flowchart LR
+    subgraph IN["Ways in"]
+        PHONE["Phone app<br/>wake word + voice"]
+        ADMIN["Admin app<br/>restricted actions"]
+        ESP["ESP32 voice<br/>Hey Jervis"]
+        DSH["dsh chat"]
+        CONSOLE["Console portal"]
+    end
+
+    HUB{{"HUB<br/>hear - understand - check - route - answer"}}
+
+    subgraph OUT["Destinations"]
+        HA["Home Assistant"]
+        SPK["Speakers<br/>Jervis TTS"]
+        NET["Internet control"]
+        ART["Artemis<br/>phone screen"]
+        PC["Paperclip<br/>slow jobs"]
+        WEB["Web search"]
+        APP["Apprise / NTFY"]
+    end
+
+    PHONE --> HUB
+    ESP --> HUB
+    DSH --> HUB
+    CONSOLE --> HUB
+    ADMIN --> HUB
+    HUB --> HA
+    HUB --> SPK
+    HUB --> NET
+    HUB --> ART
+    HUB --> PC
+    HUB --> WEB
+    HUB --> APP
+    PC -. result .-> HUB
+```
+
+*Interactive architecture map:* [maps.lab.audasmedia.com.au/central_ai_llm_master](https://maps.lab.audasmedia.com.au/central_ai_llm_master/docs/)
+
+## Usage & Configuration
+
+- **Model calls** go through OmniRoute at `http://192.168.20.13:20129/v1`.
+- **Secrets** come from `~/.config/environment.d/10-secrets.conf`.
+- **Paperclip** is at `http://192.168.20.13:3100`. An API key is required.
+- **Home Assistant** is at `http://192.168.20.30:8123`.
+- **Jervis** (voice) is at `http://192.168.20.13:8501`.
+
+The design brief is `hub_brief.md`. Project instructions are `AGENTS.md`.