111 lines
4.6 KiB
Markdown
111 lines
4.6 KiB
Markdown
# Central AI Hub (`central_ai_llm_master`)
|
|
|
|
## Mission
|
|
|
|
Build the **Hub**. The Hub is one small service. Every way in reaches every
|
|
ability through it. Build the ability once. All ways in get it.
|
|
|
|
## Authority
|
|
|
|
Read `hub_brief.md` in this folder first. It is the agreed design. If this file
|
|
and the brief disagree, the brief wins.
|
|
|
|
- `hub_brief.md` — the agreed brief (source of truth).
|
|
- `README.md` — technical readme.
|
|
- `docs/outline/` — AI context. Start with `00-index.md`.
|
|
|
|
## What the Hub does
|
|
|
|
Five steps, in order:
|
|
|
|
1. **Hear** — take voice or text from any way in.
|
|
2. **Understand** — the LLM works out what was asked.
|
|
3. **Check** — is this person allowed to ask for this?
|
|
4. **Route** — send it to the right destination.
|
|
5. **Answer** — return a short reply in the right shape for the device.
|
|
|
|
The reply can be text, spoken audio (TTS), Artemis commands, a notification, an
|
|
email, or a mix. TTS can play on the house speakers or on the phone.
|
|
|
|
A question about another project's data goes to that project's `/ask` endpoint.
|
|
See `docs/ask-contract.md`. The Hub never learns a project's data model.
|
|
|
|
## The dividing line
|
|
|
|
> 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.
|
|
|
|
**Paperclip is the work bench, not the switchboard.**
|
|
|
|
## Rules
|
|
|
|
1. All models go through **OmniRoute**. Never call a provider directly.
|
|
2. All secrets come from **`environment.d`**. Never hard-code.
|
|
3. Own service, own port, own folder.
|
|
4. No LLM in the path of a fast or consequential action.
|
|
5. Paperclip only for slow, multi-step, recorded work.
|
|
6. Replies return to the source and stay short.
|
|
7. Restricted actions need **tap-to-approve** on the admin app.
|
|
8. Only the admin app changes parental controls.
|
|
9. A new ability registers with the Hub. Build it once.
|
|
10. A data project answers `/ask` read-only. Never change state on a query.
|
|
11. High-consequence control does not route through the Hub. The admin app calls
|
|
the service directly.
|
|
12. Route with the capability list, `routing.md`, and the LLM. Ask the user when
|
|
unsure. Never route a control action.
|
|
13. Log every request. Append only. Cap the size. No secrets, no full personal
|
|
data.
|
|
14. There is one identity: Sam. Keep the `asker` field for a future second person.
|
|
|
|
## Build order
|
|
|
|
0. **Agree the `/ask` contract.** Both sides build to `docs/ask-contract.md`.
|
|
Nothing else starts until this is frozen.
|
|
1. **Thin slice, end to end.** Issue a Paperclip API key. File one job from a
|
|
script. Get the result announced back. Prove the round trip.
|
|
2. **Hub skeleton.** Hear → understand → route → answer, against a fake project
|
|
that speaks `/ask`. One real destination (speakers).
|
|
3. **Identity.** Decide how the Hub knows who is speaking.
|
|
4. **Approval flow.** "Did you ask for this?" on the admin app.
|
|
5. **One real data project** to the contract (email or school). Prove `/ask`.
|
|
6. **Internet control.** Separate service and portal. Control stays app-only.
|
|
7. **Artemis.** Separate service. Screen control only.
|
|
8. **Move Jervis's tools** into the Hub. Jervis becomes voice-only.
|
|
9. **Phone Kotlin app.** Wake word, voice to the Hub, replies and approvals.
|
|
10. **Remaining pipelines** connect when ready.
|
|
|
|
## Definition of done (phase 1)
|
|
|
|
- A Paperclip API key exists.
|
|
- One job is filed by script and its result is spoken.
|
|
- The round trip is recorded in `docs/outline/04-agent-runbook.md`.
|
|
|
|
## How this project relates to the other projects
|
|
|
|
This project owns the **shared Hub**. It does **not** own the other projects.
|
|
|
|
Every other project is a **peer**. Each has its own folder, repo, port,
|
|
interface, and build. Each can be built and used without the Hub. The Hub is an
|
|
**extra** way in, not the only one.
|
|
|
|
| Project | Talk direction |
|
|
|---|---|
|
|
| Email agent | Hub asks it (`/ask`). It tells the Hub (`/notify`). n8n scans it. |
|
|
| Compass / NHS | Hub asks it (`/ask`). It tells the Hub (`/notify`). n8n scans it. |
|
|
| Internet use control | Hub **asks** it. **Control goes through its own apps, not the Hub.** |
|
|
| Artemis | Hub calls it to act. Nothing comes back. |
|
|
| Jervis | Becomes voice-only. Its tools move here. |
|
|
| dsh | Calls the Hub for actions. Keeps its own chat. |
|
|
|
|
Each project writes its own docs. Do not copy theirs here. Link to them.
|
|
|
|
## Do not
|
|
|
|
- Do not build one central brain. No single personality or memory.
|
|
- Do not put Paperclip in the path of a fast command.
|
|
- Do not duplicate a destination inside the Hub.
|
|
- Do not add a spoken keycode as the only lock for restricted actions.
|