sam/central_ai_llm_master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial Central AI Hub docs: brief, rules, README, outline context, architecture

Browse Source
This commit is contained in:
Sam Rolfe
2026-10-10 14:44:54 +11:00
commit b3658132dd
14 changed files with 14404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/outline/00-index.md Normal file
View File

@@ -0,0 +1,38 @@
# Central AI Hub — AI Document Index
> **Target**: AI Agents
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
## Document Catalog (Inject Specific Document)
Read this index to inject the exact file you need. Do not search all files.
| Document Title | Path | Scope / Description |
| :--- | :--- | :--- |
| **System Overview** | `docs/outline/01-system-overview.md` | Explains the Hub purpose, its five steps, and the destinations. |
| **Configuration & Env** | `docs/outline/02-config-and-env.md` | Lists services, ports, env vars, and secret paths. |
| **Code Structure Map** | `docs/outline/03-code-map.md` | Shows the planned folder layout and entry points. |
| **AI Agent Runbook** | `docs/outline/04-agent-runbook.md` | Gives steps to build, test, and restart Hub work. |
| **Design Brief** | `hub_brief.md` | The agreed design. This file is the source of truth. |
| **Project Rules** | `AGENTS.md` | Mission, rules, build order, and project relations. |
---
## System Summary
The Hub is one service. Every way in reaches every ability through it. The Hub
does five steps: hear, understand, check, route, and answer. The Hub does not
hold a personality or a memory. The Hub does not do the destination work.
## Core Configuration
- **Env File**: `~/.config/environment.d/10-secrets.conf`
- **Config Directory**: `docs/`
- **Active Ports**: Hub port not allocated yet.
## Agent Restart Steps
1. Read the Document Catalog above. Inject only required files.
2. Read `hub_brief.md`.
3. Check git status: `git status`.
4. Check recent commits: `git log -n 5 --oneline`.

59
docs/outline/01-system-overview.md Normal file
View File

@@ -0,0 +1,59 @@
# Central AI Hub — System Overview
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
## Purpose
The Hub is one service. Every way in reaches every ability through the Hub. Build
each ability once. All ways in get it.
Today, Jervis (voice) and dsh (chat) each understand the user and act. A third
way in, the phone app, would repeat the same work. The Hub stops this repeat.
## The Five Steps
1. **Hear** — take voice or text from any way in.
2. **Understand** — the LLM works out what the user asked.
3. **Check** — test whether the user may ask for this.
4. **Route** — send the request to one destination.
5. **Answer** — return a short reply in the right shape.
## Ways In
- Phone app (Kotlin) — wake word, voice, controls.
- Admin app (Kotlin) — restricted actions only.
- ESP32 voice — "Hey Jervis".
- dsh chat — per-person chat.
- Console portal — web dashboard.
## Destinations
| Destination | Job |
|---|---|
| Home Assistant | Lights, switches, timers, calendar. |
| Speakers (Jervis) | Speak and announce. |
| Internet control | Parental limits on kids' devices. |
| Artemis | Operate the phone screen. |
| Paperclip | Slow, multi-step, recorded work. |
| Web search | Tavily search. |
| Apprise / NTFY | Notifications and email. |
## Reply Shapes
The Hub returns one reply. The reply can hold text, spoken audio (TTS), Artemis
commands, a notification, or an email. TTS can play on the house speakers or on
the phone. The Hub returns the reply to the source.
## The Dividing Line
The Hub asks one question: 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.
## What the Hub Is Not
- Not a central brain. No single personality or memory.
- Not Paperclip. The Hub does not wait minutes for an answer.
- Not a destination. The Hub does not turn off the internet itself.

43
docs/outline/02-config-and-env.md Normal file
View File

@@ -0,0 +1,43 @@
# Central AI Hub — Configuration & Environment
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
## Secrets
All secrets come from `~/.config/environment.d/10-secrets.conf` on each machine.
Never hard-code a secret. Never commit a secret.
Relevant keys:
| Key | Use |
|---|---|
| `OMNIROUTE_API_KEY` | Model calls through OmniRoute. |
| `PAPERCLIP_API_KEY` | File jobs to Paperclip. Does not exist yet. |
| `TAVILY_API_KEY` | Web search. |
| `OL_API_KEY` | Outline docs. |
| `VIKUNJA_TOKEN` | Vikunja tasks. |
| `GITEA_TOKEN` | Gitea repository. |
## Services and Ports
| Service | Host | Port | Use |
|---|---|---|---|
| OmniRoute | 192.168.20.13 | 20129 | Model gateway. |
| Paperclip | 192.168.20.13 | 3100 | Job orchestration. |
| Jervis (voice) | 192.168.20.13 | 8501 | Speak and announce. |
| Home Assistant | 192.168.20.30 | 8123 | Devices and timers. |
| MQTT | 192.168.20.13 | 1883 | Voice topics. |
| Apprise | 192.168.20.35 | 8210 | Notifications. |
| Hub | not allocated | — | This service. |
## Config Paths
- Brief: `hub_brief.md`
- Rules: `AGENTS.md`
- Docs: `docs/`
- Outline context: `docs/outline/`
## Rule
A new project gets its own service, its own port, and its own folder. Do not
merge a destination into the Hub.

56
docs/outline/03-code-map.md Normal file
View File

@@ -0,0 +1,56 @@
# Central AI Hub — Code Structure Map
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
> **Status**: Planned. The Hub is not built yet.
## Planned Folder Layout
```text
central_ai_llm_master/
AGENTS.md project rules for agents
hub_brief.md agreed design (source of truth)
README.md technical readme
docs/
hub-architecture.mmd Mermaid source
hub-architecture-map.html Archify map
diagrams/ rendered images
archify/ Archify JSON input
outline/ AI context documents
vikunja-tasks.json human task list
src/ Hub service code (to build)
main.* HTTP entry point
hear/ takes voice or text
understand/ LLM intent routing
check/ authorization and approval
route/ dispatch to a destination
answer/ reply shaping (text, TTS, notify)
destinations/ one client per destination
tests/ unit and round-trip tests
```
## Entry Points
| Entry point | Use |
|---|---|
| `POST /ask` | Send a voice transcript or text. Returns a reply. |
| `POST /approve` | Admin app confirms a restricted action. |
| `GET /health` | Liveness check. |
The API contract is not final. See `hub_brief.md`.
## Primary Dependencies
- HTTP server (Go or Python — decide before build).
- HTTP client for OmniRoute, Home Assistant, Paperclip.
- MQTT client for voice topics.
- Tavily API client for web search.
## Destinations
Each destination gets one client under `src/destinations/`. The client calls the
destination API. The client does not hold business logic.
## Source Control
- Gitea: `sam/central_ai_llm_master`
- Local: `/home/sam/paseo/projects/central_ai_llm_master/`

55
docs/outline/04-agent-runbook.md Normal file
View File

@@ -0,0 +1,55 @@
# Central AI Hub — AI Agent Runbook
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
## Phase 1 — Prove the Paperclip Round Trip
This phase has no Hub code. It proves the missing link: a job that leaves and a
result that returns.
### Steps
1. Create a Paperclip agent API key for this project.
- Paperclip board: `http://192.168.20.13:3100`.
- Store the key in `~/.config/environment.d/10-secrets.conf` as
`PAPERCLIP_API_KEY`. Never commit it.
2. File one job with `curl`. Use the issue-create endpoint.
3. Confirm the job appears in the Paperclip board.
4. Wait for the agent to close the job.
5. Send the result to Jervis `POST /announce` so the house speaks it.
6. Record the result in this file.
### Commands
```bash
export PAPERCLIP_API_KEY=<from secrets>
curl -s -X POST http://192.168.20.13:3100/api/issues \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"round-trip test","description":"prove the return path"}'
# Speak the result.
curl -s -X POST http://192.168.20.13:8501/announce \
-H "Content-Type: application/json" \
-d '{"text":"Round trip works."}'
```
### Definition of Done
- The job appears in Paperclip.
- The job closes.
- The house speaks the result.
- This file records the result.
## After Phase 1
Follow the build order in `AGENTS.md`. Do not start a destination before the
round trip works.
## Health Checks
```bash
curl -s http://192.168.20.13:3100/health # Paperclip
curl -s http://192.168.20.13:8501/health # Jervis
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.20.30:8123/ # HA
```