# Central AI Hub

One small service that every way in reaches every ability through. Built once,
shared by the phone app, the house voice, chat, and the admin app.

## Demonstrated Skills & Tech Stack

- **Core Technologies**: Go or Python service · HTTP JSON API · MQTT · LLM
  intent routing · OmniRoute gateway · Docker
- **Key Tools**: Jervis (voice) · Home Assistant · Paperclip · Artemis ·
  internet use control · Apprise / NTFY · OmniRoute
- **Engineering Capabilities**: service design · intent routing · authorization
  and approval flows · event-driven integration · deterministic safety for
  high-consequence actions

## Quick Start

```bash
# Phase 1 — prove the Paperclip round trip
# 1. Create an agent API key in Paperclip.
# 2. Export it for the test only.
export PAPERCLIP_API_KEY=<redacted>
# 3. File one job.
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"}'
```

Full steps: `docs/outline/04-agent-runbook.md`.

## System Architecture

```mermaid
flowchart LR
    subgraph IN["Ways in"]
        PHONE["Phone app<br/>wake word + voice"]
        ADMIN["Admin app<br/>restricted actions"]
        ESP["ESP32 voice<br/>Hey Jervis"]
        DSH["dsh chat"]
        CONSOLE["Console portal"]
    end

    HUB{{"HUB<br/>hear - understand - check - route - answer"}}

    subgraph OUT["Destinations"]
        HA["Home Assistant"]
        SPK["Speakers<br/>Jervis TTS"]
        NET["Internet control"]
        ART["Artemis<br/>phone screen"]
        PC["Paperclip<br/>slow jobs"]
        WEB["Web search"]
        APP["Apprise / NTFY"]
    end

    PHONE --> HUB
    ESP --> HUB
    DSH --> HUB
    CONSOLE --> HUB
    ADMIN --> HUB
    HUB --> HA
    HUB --> SPK
    HUB --> NET
    HUB --> ART
    HUB --> PC
    HUB --> WEB
    HUB --> APP
    PC -. result .-> HUB
```

*Interactive architecture map:* [maps.lab.audasmedia.com.au/central_ai_llm_master](https://maps.lab.audasmedia.com.au/central_ai_llm_master/docs/)

## Usage & Configuration

- **Model calls** go through OmniRoute at `http://192.168.20.13:20129/v1`.
- **Secrets** come from `~/.config/environment.d/10-secrets.conf`.
- **Paperclip** is at `http://192.168.20.13:3100`. An API key is required.
- **Home Assistant** is at `http://192.168.20.30:8123`.
- **Jervis** (voice) is at `http://192.168.20.13:8501`.

The design brief is `hub_brief.md`. Project instructions are `AGENTS.md`.