3.3 KiB
Central AI Hub — System Overview
Writing Style: ASD-STE100 Simplified Technical English (
ste-writing).
Purpose
The Hub is one service. Every way in reaches every ability through the Hub. Build each ability once. All ways in get it.
Today, Jervis (voice) and dsh (chat) each understand the user and act. A third way in, the phone app, would repeat the same work. The Hub stops this repeat.
The Five Steps
- Hear — take voice or text from any way in.
- Understand — the LLM works out what the user asked.
- Check — test whether the user may ask for this.
- Route — send the request to one destination.
- Answer — return a short reply in the right shape.
When the question is about another project's data, step 4 asks that project
through the /ask contract. See docs/ask-contract.md.
Three Directions
Nothing here is ownership. These are directions of talk.
- The Hub asks a project.
- A project tells the Hub.
- n8n triggers the project.
Ways In
- Phone app (Kotlin) — wake word, voice, controls.
- Admin app (Kotlin) — restricted actions only.
- ESP32 voice — "Hey Jervis".
- dsh chat — per-person chat.
- Console portal — web dashboard.
Peers and Destinations
Every other project is a peer. Each has its own folder, repo, port, and interface. Each works without the Hub.
| Peer | Talk direction |
|---|---|
| Email agent | Hub asks it. It tells the Hub. n8n scans it. |
| Compass / NHS | Hub asks it. It tells the Hub. n8n scans it. |
| Internet control | Hub asks it. Control goes through its own apps. |
| Artemis | Hub calls it to act. Nothing comes back. |
| Home Assistant | Hub calls it to act. |
| Speakers (Jervis) | Hub calls it to speak. |
| Paperclip | Hub files jobs. The answer returns. |
| Web search | Hub calls it. |
| Apprise / NTFY | Hub calls it to notify. |
Query, Command, or Control
| Kind | Path | Confirm |
|---|---|---|
| Query | Hub asks a project (/ask) |
No |
| Command | Hub calls Home Assistant | No |
| Control | Admin app calls internet control | Yes, on the phone |
A high-consequence control does not route through the Hub.
Routing
The Hub picks a project with three things: a capability list from each project, a
human-editable routing.md, and an LLM. The LLM returns one of four answers:
route, fanout, clarify, or no_match. When it is unsure, it asks the user a short
question. It never routes a control action.
Observability
The Hub writes one append-only log. It records the request, the route, the project asked, and the latency. The log is capped. It holds no secrets.
Reply Shapes
The Hub returns one reply. The reply can hold text, spoken audio (TTS), Artemis commands, a notification, or an email. TTS can play on the house speakers or on the phone. The Hub returns the reply to the source.
The Dividing Line
The Hub asks one question: does this need a decision, or does it need to happen?
- Happen — fast and certain. Go straight to the destination. No LLM in the path of the action.
- Decision — slow, multi-step, worth recording. Send to Paperclip.
What the Hub Is Not
- Not a central brain. No single personality or memory.
- Not Paperclip. The Hub does not wait minutes for an answer.
- Not a destination. The Hub does not turn off the internet itself.
- Not an owner. The other projects are peers, not sub-projects.