# 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.

## 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.

## Build order

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, with one destination.
3. **Approval flow.** "Did you ask for this?" on the admin app.
4. **Internet control.** Standalone service with a plain API. Device-side
   enforcement. Admin-only.
5. **Artemis.** Standalone service with a plain API. Screen control only.
6. **Move Jervis's tools** into the Hub. Jervis becomes voice-only.
7. **Phone Kotlin app.** Wake word, voice to the Hub, replies and approvals.
8. **Email and school pipelines.** Stay independent. 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 destinations.

| Project | Relation |
|---|---|
| Email agent | Own pipeline. Reports through the Hub when ready. |
| Compass / NHS | Own pipeline. Reports through the Hub when ready. |
| Internet use control | Destination. Exposes a plain API. The Hub calls it. |
| Artemis | Destination. Exposes a plain API. The Hub calls it. |
| Jervis | Becomes voice-only. Its tools move here. |
| dsh | Calls the Hub for actions. |

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.