voice_outbound/AGENTS.md

# Outbound Voice (demo)

> Build spec for Paperclip. **Status: last project.** Do not start until the Hub,
> the phone app, and Artemis work. Follow the phases in section 11 in order.

---

## 1. Purpose and outcome

A **demonstration of technology**. Show that the system can hold an artificial voice
conversation: MiniMax supplies the voice, an LLM supplies the words.

Sam sets a phone number, a topic, and a tone, then presses **Call now**.

**Outcome (the single success statement):**
> Sam enters a number, a topic, and a tone, presses Call now, and listens to a
> short, natural conversation driven by the LLM in a MiniMax voice.

## 2. Scope

**In scope**
- Set the target number, the topic, the tone, and the goal.
- Start a call on demand ("Call now").
- Speech to text the other person; the LLM decides the reply; MiniMax text to speech speaks.
- Keep the conversation on topic and in tone.
- End the call gracefully.
- Store and show the transcript.

**Out of scope**
- Inbound calls.
- Production or unattended use.
- Anything safety-critical.
- WhatsApp, unless it turns out to be simple. Decide in Phase 2.

## 3. Users and roles

- **Sam only.** This is an operator tool.

## 4. Functional requirements

| ID | Requirement |
|---|---|
| FR-1 | Set a target: phone number, topic, tone, and goal. **Choose the channel:** a phone call, WhatsApp, or Sam's Aussie Broadband service. |
| FR-2 | Start a call on demand ("Call now"). |
| FR-3 | Loop: STT the callee → LLM plans the reply → MiniMax TTS speaks it. |
| FR-4 | Keep the reply on topic and in the chosen tone. |
| FR-5 | Detect the end and close the call gracefully. |
| FR-6 | Store the transcript: each turn, who spoke, and the time. |
| FR-7 | Show a live transcript during the call. |
| FR-8 | A hard time limit per call. The demo never runs away. |
| FR-9 | Log the call: number, topic, tone, duration, result. |

## 5. Screens and UX flow

**Screen: control page**
1. Fields: target number, topic, tone, goal.
2. A **Call now** button.
3. A live transcript panel (speaker, text, time).
4. A **Hang up** button.
5. Call history with transcripts.

**Main flow**
```
Fill the form → Call now → watch the transcript → Hang up (or auto-end) → read the log
```

## 6. Look and feel

Reuse the Family Home Lab design system.

- Source: `/home/sam/Docker/Containers/family-home-lab/DESIGN.md`
- Tokens: `/home/sam/Docker/Containers/family-home-lab/portal/static/tokens.css`
- Copy `tokens.css` into this project.

Canvas `#f6f5f4`, one action blue `#0075de`, Inter, 8px grid, pill CTAs. Dark mode.

## 7. Data model

SQLite inside the service. Suggested:

| Table | Holds |
|---|---|
| `calls` | number, topic, tone, goal, started-at, ended-at, duration, result |
| `turns` | call id, speaker (`ai` or `human`), text, created-at |
| `recordings` | optional audio paths |

Retention: keep transcripts for a bounded period. Recordings only if Sam asks.

## 8. Integrations

| System | Use |
|---|---|
| **MiniMax** | Text to speech, and speech to text. Keys already in `environment.d`. |
| **OmniRoute** | The LLM that plans each reply. |
| **Telephony** | **To be decided** — see section 13. |
| **Hub** | Optional. `/ask` is not required. A `/notify` on call end is optional. |

## 9. Technology (locked)

| Item | Value |
|---|---|
| Backend | **Go** |
| UI | **HTMX** + server-rendered HTML |
| Database | **SQLite** |
| Voice | **MiniMax** T2A and STT |
| LLM | **OmniRoute** |
| Telephony | **Choose per call:** phone call, WhatsApp, or Aussie Broadband. Providers decided in Phase 2. |
| Host | `.13`, Docker |
| Container | **This project's own.** |
| Port | Allocate one (suggest **8794**). |
| URL | `voice.lab.audasmedia.com.au` via Caddy on `.35` |
| Auth | **Separate session login.** |

## 10. Rules and constraints

1. **It is a demo.** Keep calls short, and set a hard time limit.
2. **Never call a real person without Sam's explicit action.** No bulk, no cold lists.
3. Consider whether to disclose that the caller is an AI. Decide in section 13.
4. Models go through **OmniRoute**, except MiniMax voice.
5. Secrets come from `environment.d`.
6. Own folder, own container, own port.
7. This project writes its own docs.

## 11. Build order

**Phase 1 — Skeleton and control page**
Go service, SQLite, session login, the form, Docker, Caddy route.
*DoD:* the page runs on `.13` and the form saves.

**Phase 2 — Telephony (the risk phase)**
Prove that a call can be placed and that audio flows both ways. Decide the provider
here.
*DoD:* a real call connects and the app receives the other person's audio. **If this
fails, stop and report.**

**Phase 3 — The conversation loop**
STT → LLM → MiniMax TTS, turn by turn.
*DoD:* a short real conversation happens, with the LLM replying in a MiniMax voice.

**Phase 4 — Topic and tone**
Prompt the LLM from the form's topic, tone, and goal.
*DoD:* two different tones produce clearly different conversations.

**Phase 5 — Transcript**
Store and display each turn live.
*DoD:* the transcript is complete after a call.

**Phase 6 — Graceful end**
Detect the end, hang up, enforce the time limit.
*DoD:* the call ends cleanly at the limit.

**Phase 7 — Documentation**
*DoD:* project-docs run; docs updated.

## 12. Acceptance criteria

- Sam enters a number, topic, and tone, and presses Call now.
- A real call connects, and the LLM holds a short on-topic conversation.
- The tone setting measurably changes the conversation.
- The transcript is stored and readable.
- The call ends cleanly at the time limit.
- It runs in its own container on its own port.

## 13. Decisions and remaining questions

Resolved:
1. It is a **demo**, not production.
2. **Last project.** Do not start early.
3. MiniMax voice, OmniRoute for the LLM.

Resolved:
1. **Channel is chosen per call:** a phone call, WhatsApp, or Sam's Aussie Broadband
   service.

Remaining:
1. **Telephony providers.** Three channels to prove in Phase 2:
   - **Phone call** — a SIP/cloud provider (for example Twilio), or the Kotlin app
     places the call and routes audio.
   - **WhatsApp** — no public API. Options: WhatsApp Business Cloud API, or screen
     control through `artemis_control`.
   - **Aussie Broadband — mobile.** Confirmed as a mobile service. Confirm whether
     it exposes an API, SIP, or only a SIM.
   **Phase 2 proves at least one channel end to end.**
2. Which channel is the default?
3. One-way (speak a message) or two-way (hold a conversation)? The demo implies two-way.
4. Do we disclose that the caller is an AI? Recommend yes.
5. Which number does it call from, and who pays for it?