99 lines
3.3 KiB
Markdown
99 lines
3.3 KiB
Markdown
# 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
|
|
|
|
1. **Hear** — take voice or text from any way in.
|
|
2. **Understand** — the LLM works out what the user asked.
|
|
3. **Check** — test whether the user may ask for this.
|
|
4. **Route** — send the request to one destination.
|
|
5. **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.
|
|
|
|
1. The Hub asks a project.
|
|
2. A project tells the Hub.
|
|
3. 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.
|