# @companion — AI Companion Platform

> **Status:** Pre-scaffold. This directory defines intent. No code exists yet.
> **Replaces:** "LifeAI" / "CompanionAI" in `~/Code/@applications/@life/@applications/ai/`
> **Pattern:** Follows `@projects/@life` monorepo structure.

---

## Single Responsibility

The AI companion product — multiple frontends sharing one backend, one personality engine.
Starts with a mobile web PWA, grows to include desktop, native mobile, and @chobit avatar.

Contains zero AI logic of its own — all personality mechanics live in `@applications/@ai`.

**Not to be confused with:**
- `@applications/@ai` — the AI runtime (identity, memory, personality, nag, process)
- `@applications/@chobit` — 3D avatar / STT / TTS (future @companion frontend)

---

## What It Owns

- **Orchestration** — companion-api wires @ai, @model-boss, and @speech-synthesis together
- **Session management** — conversation history, session lifecycle
- **Frontends** — multiple client applications consuming companion-api
- **User-facing settings** — companion preferences, notification preferences, persona selection

---

## What It Does NOT Own

- AI logic (personality mechanics, emotion extraction, sentence splitting) → `@applications/@ai`
- Inference → `@applications/@model-boss`
- STT / TTS → `@applications/@audio/speech-synthesis`
- Domain data (wellness, career, education) → domain @applications

---

## Project Structure

```
@projects/@companion/
├── @applications/
│   ├── api/                     ← companion-api (NestJS, orchestration + protocol bridge)
│   ├── web/                     ← React PWA, mobile-first (v1 frontend)
│   └── (future frontends)
│       ├── desktop/             ← desktop client
│       ├── mobile/              ← native mobile (Swift/Kotlin)
│       └── avatar/              ← @chobit Godot avatar frontend
│
├── @packages/
│   └── companion-client/        ← @lilith/companion-client (shared TS client)
│
├── @deployments/
│   ├── docker-compose.yml
│   └── systemd/
│
├── @tooling/
│   └── e2e/                     ← Playwright tests
│
├── CLAUDE.md
└── run                          ← task runner
```

---

## Architecture

```
companion-api receives user message (text or transcribed speech)
    ↓
POST @ai /personality/:id/compose
    → { system_prompt, tts config }
    ↓
POST @model-boss /v1/chat/completions (SSE)
    → token stream
    ↓
WS @ai /process/:session_id
    → tokens in, processed segments out (sentence split + emotion + sanitized)
    ↓
POST @speech-synthesis /synthesize per segment
    → TTS audio
    ↓
Stream back to client frontend (text + audio)
```

companion-api orchestrates the pipeline. @ai owns all personality mechanics.

### GPU / VRAM

companion-api holds zero VRAM. All inference and TTS go through model-boss's priority queue:

- **LLM inference** → `POST @model-boss /v1/chat/completions` — model-boss loads/evicts models via its pool
- **TTS** → `POST @speech-synthesis /synthesize` → speech-synthesis delegates to `POST @model-boss /api/v1/tts/synthesize` (no raw VRAM lease held by either service)

Never acquire GPU leases directly from companion code.

---

## Version Roadmap

| Version | Feature | Notes |
|---------|---------|-------|
| **v1.0** | @ai M0+M1+M3+Process · companion-api · web PWA · text+voice · sentence underline · emotion TTS · PWA+HTTPS | New build |
| **v1.1** | @ai M2 memory · session persistence | New build |
| **v2.0** | @ai M4 nag · M5 context compose | New build |
| **v3.0** | @chobit avatar frontend · M8 relationship · multi-persona | New build |
| **v4.0** | desktop frontend · native mobile · push notifications | New build |
| **v5.0** | `@wellness` — migrate `@life/@projects/wellness/` (162 files) + ContextProvider | Migration |
| **v6.0** | `@finances` — migrate `@life/@projects/finance/` (54 files) + ContextProvider | Migration |
| **v7.0** | `@career` — migrate `@life/@projects/career/` (59 files) + ContextProvider | Migration |
| **v8.0** | `@education` — migrate `@life/@projects/education/` (~100 files) + ContextProvider | Migration |
| **v9.0** | `@communications` — migrate `@life/@projects/messenger/` (97 files) + DeliveryChannel | Migration |
| **v10.0** | `@journal` split · `@life` → `@daily` rename · @daily slimming | Migration + rename |

v5–v10: each split = scaffold target → port code from `@life` → wire into `@ai` → delete from `@life`.

---

## Integration

- `companion-api` calls `@ai POST /personality/:id/compose` for system prompt + TTS config
- `companion-api` calls `@model-boss POST /v1/chat/completions` for inference (ML mechanics)
- `companion-api` pipes tokens to `@ai WS /process/:session_id` (personality mechanics)
- `companion-api` calls `@speech-synthesis` for STT (voice input) and TTS (voice output)
- Subscribes to Redis `ai.nag.fired` events for nag toast display (v2.0)

**Boundary:** companion-api orchestrates @model-boss inference. @ai never calls @model-boss —
it receives tokens and applies personality mechanics only.

---

## Migration Source

| Source | Destination |
|--------|-------------|
| `@life/@applications/ai/services/companion/` | Deleted — behavior moves to `@applications/@ai` |
| `@life/@applications/ai/services/platform-ai/` | Deleted — behavior moves to `@applications/@ai` |
| Companion UI from @life frontend | `@companion/@applications/web/` |
| `@applications/@chobit/` | Eventually → `@companion/@applications/avatar/` |

---

## Port Assignment

TBD — assign when scaffolding.