8.6 KiB
8.6 KiB
The Hub — a short brief
Purpose: tell every project where it fits and the rules it must follow. Written: 2026-10-10 Status: agreed direction, not a build order.
The idea in one line
Share the plumbing. Keep the brains separate. Put one small hub in the middle.
Every way in (phone, house voice, chat) reaches every ability (lights, internet, Artemis, Paperclip) through one place — built once, not repeated.
What already works (do not rebuild)
| System | What it is |
|---|---|
| Jervis | The house voice. ESP32 "Hey Jervis" → STT → agent → TTS → speakers. Controls HA, timers, reminders, shopping, calendar, music, weather, web search, family messages. |
| dsh | Per-person chat (sam / jo / harry / finn). Memory, images, video, documents. |
| Console portal | Logins and dashboard for the family. |
| Front Door Cam | Its own separate ESP32. Visitor detection, Gemini sees the person, voice asks them to speak. |
| OmniRoute | The model gateway. All models go through here. |
| Home Assistant | Devices, timers, calendar, notifications. |
| Shared | Apprise, Snapcast, STT/TTS, n8n, secrets in environment.d. |
These stay. The hub is added, not a replacement.
What is new
Each of these is a separate project. Each has its own folder, repo, port, interface, and build. The Hub never owns them.
- The Hub (this brief) — a shared way in and a router. Not a brain.
- Email agent — scans and logs the inbox. Answers questions. Own pipeline.
- School (Compass / Teams) — scans school data. Answers questions. Own pipeline.
- Internet use control — its own service and information portal. Enforces limits.
- Artemis — its own service. Operates the phone screen.
- Kotlin phone app — a new way in (wake word, voice).
- Admin app + kids app — control and confirmation, admin only.
What the Hub is
One service that does five steps:
- Hear — takes voice or text from any way in.
- Understand — the LLM works out what was asked.
- Check — is this person allowed to ask for this?
- Route — sends it to the right destination.
- Answer — returns a short reply in the right shape for the device.
The reply can be text, spoken audio (TTS), Artemis commands, a phone notification, an email, or a mix. TTS can play on the house speakers or on the phone.
When a question is about another project's data, the Hub asks that project and
returns the answer. See docs/ask-contract.md.
Three directions
Nothing here is ownership. These are directions of talk.
- The Hub asks a project. "What is important in my inbox?", "What does Harry have on today?", "How long have the kids been on screens?"
- A project tells the Hub. "Overdue homework found.", "3 emails need a decision."
- n8n triggers the project. Scan the inbox. Scan the school. Enforce the schedule.
The projects keep their own interfaces. The Hub is an extra way in.
What the Hub is NOT
- Not a central brain. It does not hold one personality or one memory.
- Not Paperclip. It never waits minutes for an answer.
- Not a destination. It does not turn off the internet itself. It sends the request to the service that does.
The dividing line
One question sorts every request:
Does this need a decision, or does it need to happen?
- Happen (fast, certain) → straight to the destination: HA, internet control, Artemis, speakers. No LLM in the path of the action.
- Decision (slow, multi-step, worth recording) → Paperclip.
Paperclip is the work bench, not the switchboard. It is never in the path of a fast or high-consequence command.
Query, command, or control
| Kind | Example | Path | Confirm? |
|---|---|---|---|
| Query (read) | "What does Harry have on today?" | Hub → project (/ask) |
No |
| Command (do it now) | "Turn on the lounge light." | Hub → Home Assistant | No |
| Control (high consequence) | "Cut the kids' internet." | Admin app → internet control | Yes, on the phone |
A query goes through the Hub. A high-consequence control does not. The admin app talks to the internet control service directly. Voice may start it. Only the admin app confirms.
Where each system fits
Each project is a peer. These are talk directions, not ownership.
| System | Relation | Talk direction |
|---|---|---|
| Jervis | House voice. Peer. | Becomes voice-only. Its tools move into the Hub over time. |
| dsh | Chat. Peer. | Calls the Hub for actions. Keeps its own chat. |
| Console portal | Login and dashboard. Peer. | Unchanged. May show Hub status and approvals. |
| Front Door Cam | Visitor intercom. Peer. | Separate. May use the Hub to speak. |
| Email agent | Separate pipeline. Peer. | Hub asks it (/ask). It tells the Hub (/notify). n8n scans it. |
| School agent | Separate pipeline. Peer. | Hub asks it (/ask). It tells the Hub (/notify). n8n scans it. |
| Internet control | Separate service and portal. Peer. | Hub asks it. Control goes through its own apps, not the Hub. |
| Artemis | Separate service. Peer. | Hub calls it to act. Nothing comes back. |
| Paperclip | Work bench. Peer. | The Hub files jobs and hears the answer. |
| Phone app | Way in. | Sends voice to the Hub. Shows replies and approvals. |
Rules every project follows
- All models go through OmniRoute. Never call a provider directly.
- All secrets come from
environment.d. Never hard-code. - Own service, own port, own folder. Do not merge into another project.
- No LLM in the path of a fast or consequential action. Deterministic calls for anything that turns something off.
- Paperclip only for slow, multi-step, recorded work. Never make a person wait on it.
- Replies return to the source, and stay short. Speaker → one line. Phone → notification. Chat → text. No long-winded answers.
- Restricted commands need tap-to-approve on the admin app. This includes parental controls and any job filed to Paperclip.
- Only the admin app can change parental controls. Kids' apps and desktop exes may only obey and report.
- New work registers with the Hub. A capability is added once, and every way in gets it.
- A data project answers
/askread-only. It never changes state on a query. - High-consequence control does not route through the Hub. The admin app calls the service directly.
Safety
- Voice is shared and unauthenticated. Anyone in the house can speak.
- The admin app is the only trusted door for restricted actions.
- A spoken keycode is not the lock. It can be overheard and misheard. Voice may ask; the admin app confirms with "Did you ask for this?".
- Approval is required for parental controls and Paperclip jobs.
- Identity is not solved yet. Voice has no identity. Personal data (inbox, school, screen time) needs it. See open items.
Build order
- Agree the
/askcontract. Both sides build todocs/ask-contract.md. Nothing else starts until this is frozen. - Thin slice, end to end. Issue a Paperclip API key, file one job from a script, and get the result announced back. Proves the round trip.
- Hub skeleton. Hear → understand → route → answer, against a fake
project that speaks
/ask. One real destination (speakers). - Identity. Decide how the Hub knows who is speaking.
- Approval flow. "Did you ask for this?" on the admin app.
- One real data project to the contract (email or school). Prove
/ask. - Internet control. Separate service and portal. Control stays app-only.
- Artemis. Separate service. Screen control only.
- Move Jervis's tools into the Hub. Jervis becomes voice-only.
- Phone Kotlin app. Wake word, voice to the Hub, replies and approvals.
- Remaining pipelines connect when ready.
What is still open
- Identity. How does the Hub know who is speaking? Voice has none. This is the top gap, because personal data now flows.
- Routing. How does the Hub pick the project to ask? A small capability registry, or an LLM choice.
- Overlap. "What do I have on today?" may match several projects. Ask one, or ask all and merge?
- Approval service. One shared mechanism, or one per project?
- Service tokens. One bearer token per project, stored in
environment.d. - Job contract. Exact fields for a Paperclip job (title, brief, project, agent).
- Artemis voice. Stream or file. When does phone TTS get used?
- Paperclip layout. One company or several. Which projects.