central_ai_llm_master/AGENTS.md

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.