Sam Rolfe
449fdd02c5
- docs/hub-api.md: language decision (Go 1.25) with reason and the frozen v1 routes POST /ask, POST /approve, GET /health, including request/response schemas, bearer-token auth, timeouts, error shapes, logging, versioning, and a safety confirmation that no route is a high-consequence control. - Update README, hub_brief.md open items, and the outline docs so they no longer say the API is undecided or the language is open. Co-Authored-By: Paperclip <noreply@paperclip.ing>
88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
# 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 1.25 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["Peers and services<br/>(the Hub is not a destination)"]
|
|
HA["Home Assistant"]
|
|
SPK["Speakers<br/>Jervis TTS"]
|
|
NET["Internet control<br/>parental limits"]
|
|
ART["Artemis<br/>phone screen"]
|
|
PC["Paperclip<br/>work bench"]
|
|
WEB["Web search"]
|
|
APP["Apprise / NTFY"]
|
|
end
|
|
|
|
PHONE --> HUB
|
|
ESP --> HUB
|
|
DSH --> HUB
|
|
CONSOLE --> HUB
|
|
ADMIN --> HUB
|
|
HUB --> HA
|
|
HUB --> SPK
|
|
HUB --> ART
|
|
HUB --> WEB
|
|
HUB --> APP
|
|
HUB -- "ask only (query)" --> NET
|
|
HUB -- "slow job (approved)" --> PC
|
|
ADMIN -- "control + tap to approve" --> NET
|
|
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`.
|
|
|
|
The interface between the Hub and every data project is `docs/ask-contract.md`.
|
|
The frozen inbound API (ways in to the Hub) is `docs/hub-api.md`.
|
|
Every other project is a **peer**, not a sub-project. A high-consequence control
|
|
(for example, cutting the kids' internet) does **not** route through the Hub.
|