init: Kira — AI body double with Honcho memory

Full voice pipeline (Whisper STT -> DeepSeek LLM -> OpenAI TTS), animated SVG avatar (Live2D-ready), girly-pop UI, lofi music, timer/notes/pets/wardrobe widgets, 10 background scenes with particle effects, Honcho cross-session memory.
2026-06-04 10:51:38 -04:00
commit 97424cb98f
47 changed files with 5691 additions and 0 deletions
@@ -0,0 +1,129 @@
+# Kira ✨
+
+AI body double — a girly-pop focus companion with real-time voice conversation, lo-fi music, ADHD tools, and a customizable avatar.
+
+Your wife's very own focus bestie who's always there when her real body double isn't available.
+
+## Features
+
+- **🎙️ Voice conversation** — Push-to-talk microphone → STT (Whisper) → LLM (DeepSeek) → TTS (OpenAI Nova voice)
+- **💬 Text chat fallback** — Type when you don't want to speak
+- **🎶 Lo-fi music** — Streaming from Lofi Girl YouTube channel
+- **🍅 Timer** — Pomodoro, countdown, stopwatch modes
+- **📝 Notes** — Quick task list / check-in notes
+- **🎨 10 background scenes** — Cozy room, coffee shop, garden, rainy window, starry night, sakura, ocean, autumn, winter cabin, sunset
+- **✨ Particle effects** — Rain, stars, cherry petals, snow per scene
+- **👘 Wardrobe** — 5 outfits + 5 accessories (bow, glasses, flower crown, earrings, scarf)
+- **🐱 Pet zone** — Two cats: Mochi (orange fluffy) and Luna (sleepy black)
+- **🕐 Live clock** — Time + date
+- **🌸 Animated avatar** — Blinking, speaking mouth, waving, outfit colors (Live2D-ready)
+
+## Quick Start
+
+### 1. Get API keys
+
+| Service | What for | Where |
+|---------|----------|-------|
+| OpenAI | Whisper STT + TTS (Nova voice) | https://platform.openai.com/api-keys |
+| DeepSeek | LLM brain | https://platform.deepseek.com/api_keys |
+
+### 2. Configure
+
+```bash
+cd ~/Projects/ai-body-double
+cp .env.example .env
+# Edit .env with your API keys:
+#   OPENAI_API_KEY=sk-...
+#   DEEPSEEK_API_KEY=sk-...
+```
+
+### 3. Run
+
+```bash
+docker compose up -d
+```
+
+Open **http://kira.hobokenchicken.com:3000** (or wherever you deploy it).
+
+### 4. Add a Caddy entry (homelab)
+
+```
+kira.hobokenchicken.com {
+    reverse_proxy 172.20.0.X:3000
+}
+```
+
+## Architecture
+
+```
+Browser ──WebSocket──▶ Backend (FastAPI)
+  │                        │
+  ├─ Mic audio ──────────▶ ├─ Whisper API (STT)
+  │                        ├─ DeepSeek (LLM)
+  │ ◀── TTS audio ──────── ├─ OpenAI TTS
+  │                        │
+  ├─ YouTube embed (lo-fi) │
+  ├─ Timer / Notes / Cats  │
+  └─ Animated avatar       │
+```
+
+## Live2D Model Setup
+
+Kira currently uses a CSS/SVG animated placeholder avatar. To add a Live2D model:
+
+1. Commission or obtain a `.model3.json` (Cubism 4.x format) model
+2. Place the model directory in `frontend/public/live2d/models/`
+3. Rename the model entry point to `kira.model3.json`
+4. The WebGL renderer will auto-detect and switch
+
+Required model files:
+- `kira.model3.json` — model definition
+- `kira.moc3` — mesh/deformer data
+- `kira.cdi3.json` — display info (optional)
+- `textures/` — PNG texture files
+- `motions/` — animation files (optional)
+- `expressions/` — face expression files (optional)
+
+Recommended creators for custom Live2D models: search VGen, VTube Studio model artists, or Fiverr.
+
+## Color Palette
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Kira Pink | `#FFB6C1` | Primary accent |
+| Kira Lavender | `#D8B4FE` | Secondary accent |
+| Kira Mint | `#A7F3D0` | Success/status |
+| Background | `#FFF5F5` | Card/comfy bg |
+| Text Plum | `#4A1942` | Body text |
+| Text Violet | `#7C3AED` | Soft text |
+
+## Project Structure
+
+```
+ai-body-double/
+├── docker-compose.yml
+├── .env
+├── backend/          # FastAPI + WebSocket
+│   ├── main.py       # WS handler (STT→LLM→TTS pipeline)
+│   ├── services/
+│   │   ├── stt.py    # OpenAI Whisper
+│   │   ├── llm.py    # DeepSeek
+│   │   └── tts.py    # OpenAI TTS
+│   └── config.py     # Env config
+├── frontend/         # React + Vite + TailwindCSS
+│   ├── src/
+│   │   ├── App.tsx           # Main layout
+│   │   ├── components/
+│   │   │   ├── AnimatedAvatar.tsx  # SVG animated character
+│   │   │   ├── KiraAvatar.tsx      # Live2D loader + fallback
+│   │   │   ├── ChatBubble.tsx      # Conversation display
+│   │   │   ├── Timer.tsx           # Pomodoro/stopwatch
+│   │   │   ├── MusicPlayer.tsx     # Lofi Girl embed
+│   │   │   ├── PetZone.tsx         # Two CSS cats
+│   │   │   ├── Wardrobe.tsx        # Outfit + accessories
+│   │   │   └── Particles.tsx       # Rain/stars/petals/snow
+│   │   └── hooks/
+│   │       └── useConversation.ts  # WS + audio management
+│   └── public/live2d/     # Cubism SDK + model slot
+└── README.md
+```