2026-04-01 07:50:13 -07:00
# @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.
2026-04-02 21:44:53 -07:00
### 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.
2026-04-01 07:50:13 -07:00
---
## 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– `@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.
