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.

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.