147 lines
5.6 KiB
Markdown
147 lines
5.6 KiB
Markdown
# @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.
|