waifu/README.md
2026-05-19 22:14:00 -06:00

332 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Arisu AI
Asistente de IA con avatar Live2D animado. Responde por voz y texto, te sigue con la mirada a través de la cámara, y habla con voz expresiva usando ElevenLabs.
## Stack
| Capa | Tecnología |
|------|-----------|
| Backend | FastAPI + WebSocket |
| LLM | Groq (`llama-3.1-8b-instant`) |
| STT | Groq Whisper (`whisper-large-v3-turbo`) |
| TTS | ElevenLabs (`eleven_v3`) |
| Clima | Open-Meteo (gratis, sin API key) |
| Avatar | Live2D Cubism 4 + pixi-live2d-display |
| Seguimiento ocular | MediaPipe FaceMesh |
| Frontend | HTML/CSS/JS + Bootstrap 5 + Bootstrap Icons (UI bilingüe ES/EN) |
## Requisitos
- Python 3.9+
- API keys de Groq y ElevenLabs
- Navegador con micrófono (Chrome, Firefox, Safari)
## Instalación
```bash
cd waifu
pip install -r requirements.txt
cp .env.example .env
# Edita .env con tus claves API
python main.py
```
Abrir `http://localhost:8000` en el navegador.
Al primer arranque se descarga automáticamente `live2dcubismcore.min.js` (~202 KB) desde los servidores de Live2D.
> **Seguridad:** Si las claves estuvieron expuestas en código, rótalas en los dashboards de Groq y ElevenLabs.
## Estructura
```
waifu/
├── PLAN.md # Plan de auditoría y mejoras
├── main.py # Backend FastAPI + WebSocket + LLM
├── workspace.py # Herramientas terminal (archivos + shell)
├── websearch.py # Búsqueda web (Serper / DuckDuckGo / Wikipedia)
├── weather.py # Clima Open-Meteo + detección de intención
├── .env.example # Plantilla de variables de entorno
├── requirements.txt
└── static/
├── index.html # UI principal
├── style.css # Tema cyberpunk-anime
├── app.js # WebSocket, audio, chat, wake word, i18n
├── live2d.js # Wrapper Live2D + expresiones + lip-sync
└── live2dcubismcore.min.js # Runtime Cubism 4
```
## Diagrama de funcionamiento
### Arquitectura general
```mermaid
flowchart TB
subgraph Browser["🌐 Navegador"]
UI["Chat · Live2D · Ajustes"]
Mic["Micrófono continuo + VAD"]
Cam["Cámara + FaceMesh"]
Geo["Geolocalización"]
end
subgraph Server["⚙️ Servidor — main.py"]
WS["WebSocket /ws"]
Wake["Wake check «Arisu»"]
STT["Groq Whisper STT"]
Prefetch["Prefetch clima"]
LLM["Groq LLM + historial"]
Tools["Tool calling"]
TTS["ElevenLabs TTS"]
end
subgraph Modules["📦 Módulos"]
W["weather.py"]
S["websearch.py"]
T["workspace.py"]
end
subgraph APIs["☁️ APIs externas"]
Groq["Groq"]
Eleven["ElevenLabs"]
OM["Open-Meteo"]
Web["Serper · DuckDuckGo · Wikipedia"]
end
UI <-->|"texto · chunks · widget"| WS
Mic -->|"PCM 16 kHz · wake_check"| WS
Geo -->|"geo_config"| WS
Cam --> UI
WS --> Wake --> STT
WS --> STT
WS --> Prefetch --> W --> OM
Prefetch -->|"weather_widget"| WS
STT --> LLM
WS -->|"question"| LLM
LLM --> Tools
Tools --> S --> Web
Tools --> T
LLM --> Groq
STT --> Groq
LLM --> TTS --> Eleven
TTS -->|"tts_audio"| WS
```
### Flujo de una conversación
```mermaid
sequenceDiagram
autonumber
participant U as Usuario
participant B as Navegador
participant S as Servidor
participant G as Groq
participant X as Open-Meteo / Web / Terminal
participant E as ElevenLabs
alt Voz con «Arisu»
U->>B: «Arisu, ¿clima en Madrid?»
B->>S: wake_check (PCM base64)
S->>G: Whisper
G-->>S: transcripción
S-->>B: wake_ok + text
Note over B: Si no hay pregunta en wake_ok,<br/>graba la siguiente frase (post-buffer)
else Micrófono manual
U->>B: Hablar → Detener
B->>S: PCM binario
S->>G: Whisper
G-->>S: texto
S-->>B: transcript
else Texto escrito
U->>B: Escribe en el chat
end
B->>S: question
opt Pregunta de clima
S->>X: Open-Meteo
X-->>S: datos
S-->>B: weather_widget
end
S->>G: LLM (+ historial + datos clima)
loop Herramientas si el LLM las necesita
S->>X: web_search / workspace
X-->>S: resultados
S-->>B: tool_event · tool_result
S->>G: continúa con resultados
end
G-->>S: respuesta con [tags]
S-->>B: thinking → chunk × N → done
opt TTS activado
S->>E: texto con tags
E-->>S: MP3
S-->>B: tts_audio
B->>B: lip-sync Live2D + expresiones
end
```
## Uso
| Acción | Cómo |
|--------|------|
| Activación por voz | Di **«Arisu»** y luego tu pregunta (activo por defecto; ⚙️ para desactivar) |
| Hablar manualmente | Clic en **Hablar**, habla, clic en **Detener** (o barra espaciadora) |
| Escribir | Campo de texto → Enter o botón Enviar |
| Cancelar respuesta | Botón **Detener** o tecla `Escape` |
| Limpiar chat | Icono papelera en el header |
| Activar terminal | ⚙️ → Modo terminal + Directorio base |
| Cambiar modelo Live2D | ⚙️ → Modelo |
| Cambiar cámara/mic | ⚙️ → Cámara / Micrófono |
| Idioma UI | ⚙️ → Idioma UI (Español / English) |
| Idioma voz (STT) | ⚙️ → Idioma voz |
| Activar/desactivar TTS | ⚙️ → Reproducir voz |
### Activación por voz «Arisu»
Compatible con **Safari** (no usa Web Speech API). Flujo:
1. El micrófono escucha continuamente con VAD (detección de voz).
2. Al detectar habla, envía audio al servidor → Whisper busca la palabra «Arisu».
3. Si la frase incluye pregunta tras «Arisu» (*«Arisu, qué clima hace en Madrid»*), se envía directamente.
4. Si solo dice «Arisu», graba tu siguiente frase automáticamente.
El audio que llega mientras el servidor transcribe se guarda en un buffer para no perder la pregunta.
## Clima
Pregunta por el tiempo y verás una **tarjeta visual** en el chat con icono, temperatura, mín/máx, humedad y viento.
Ejemplos:
- *«¿Qué clima hace hoy en Tokio?»*
- *«Arisu, clima en Madrid»*
- *«¿Hace calor hoy?»* (usa geolocalización del navegador si la permites)
El servidor detecta la intención de clima, consulta [Open-Meteo](https://open-meteo.com) y muestra el widget **sin depender del tool-calling del LLM** (evita errores con modelos pequeños).
## Búsqueda web
Arisu puede buscar en internet cuando no sabe algo o necesita datos actuales. El LLM usa la herramienta `web_search` automáticamente.
| Fuente | Cuándo |
|--------|--------|
| **Serper** (Google) | Si configuras `SERPER_API_KEY` en `.env` |
| **DuckDuckGo** | Siempre (gratis) |
| **Wikipedia** | Fallback en el idioma de la sesión |
La fecha actual del sistema se inyecta en el prompt del LLM para consultas de «hoy» o noticias recientes.
Verás en el chat: *Buscando en la web* mientras consulta.
## Modo terminal (workspace)
Arisu puede crear archivos y ejecutar comandos **solo dentro de un directorio base** que tú elijas.
1. Abre ⚙️ **Ajustes**
2. Activa **Modo terminal**
3. Escribe la ruta absoluta, p. ej. `/Users/tu/proyectos/mi-app`
4. Pide por voz o texto: *"Crea un programa Python que sume dos números"*
### Herramientas disponibles (LLM)
| Herramienta | Función |
|-------------|---------|
| `web_search` | Buscar en internet (siempre activa) |
| `list_directory` | Listar archivos y carpetas |
| `read_file` | Leer un archivo de texto |
| `write_file` | Crear o sobrescribir un archivo |
| `create_directory` | Crear carpetas |
| `run_command` | Ejecutar comandos shell en el workspace |
> El clima **no** usa tool-calling del LLM; se resuelve en el servidor vía `weather.py`.
### Seguridad
- Todas las rutas deben estar **dentro** del directorio base (sin `../`)
- Comandos peligrosos bloqueados (`sudo`, `rm -rf /`, etc.)
- Timeout de 45 s por comando
- **Solo úsalo en carpetas de desarrollo**, nunca en `/` o tu home completo
## Memoria conversacional
Cada conexión WebSocket mantiene un historial de hasta 20 mensajes (≈10 turnos). Arisu recuerda el contexto dentro de la sesión. Usa **Limpiar chat** para resetear.
Persistencia: sesión WebSocket + preferencias UI en `localStorage`. No usa base de datos.
## Modelos Live2D disponibles
- **Mao** — chica con uniforme escolar (por defecto)
- **Natori** — chica con traje casual
- **Haru** — chica con vestido
- **Rice** — personaje AR de Live2D Garage
## Audio tags de ElevenLabs
| Tag | Voz | Expresión |
|-----|-----|-----------|
| `[laughs]` | Risa | Cara muy feliz, mejillas rojas |
| `[giggles]` | Risita | Cara feliz, ojos sonrientes |
| `[excited]` | Emocionada | Cara muy expresiva |
| `[whispers]` | Susurro | Expresión calmada |
| `[sighs]` | Suspiro | Expresión neutral |
| `[gasps]` | Sorpresa | Expresión sorprendida |
## Pipeline de audio
```
Micrófono → ScriptProcessor → Float32 → Downsample 16 kHz → Int16 PCM
→ WebSocket binario → WAV → Groq Whisper → texto
→ Groq LLM (streaming + historial + herramientas) → chunks con tags
→ ElevenLabs TTS (opcional) → MP3 base64
→ AudioContext + AnalyserNode → lip-sync Live2D
```
## Mensajes WebSocket
| Dirección | Tipo | Significado |
|-----------|------|---------------|
| cliente→servidor | `audio_config` | Idioma STT, sample_rate, tts_enabled |
| cliente→servidor | `geo_config` | Lat/lon del navegador (clima local) |
| cliente→servidor | `question` | Texto del usuario |
| cliente→servidor | `wake_check` | Audio PCM base64 para detectar «Arisu» |
| cliente→servidor | `workspace_config` | Activar terminal + ruta base |
| cliente→servidor | `cancel` | Cancelar respuesta en curso |
| cliente→servidor | `clear_history` | Borrar historial de sesión |
| cliente→servidor | binario | PCM-16LE a 16 kHz (grabación manual) |
| servidor→cliente | `transcript` | Resultado Whisper |
| servidor→cliente | `wake_ok` | «Arisu» detectado (`text` opcional = pregunta incluida) |
| servidor→cliente | `no_wake` | No se detectó «Arisu» |
| servidor→cliente | `thinking` | LLM iniciado |
| servidor→cliente | `chunk` | Delta streaming |
| servidor→cliente | `done` | LLM terminado |
| servidor→cliente | `cancelled` | Respuesta cancelada |
| servidor→cliente | `busy` | Servidor ocupado |
| servidor→cliente | `tts_audio` | MP3 en base64 |
| servidor→cliente | `tts_error` | ElevenLabs falló |
| servidor→cliente | `no_speech` | Audio demasiado corto o silencioso |
| servidor→cliente | `tool_event` | Herramienta en ejecución |
| servidor→cliente | `tool_result` | Resultado de herramienta |
| servidor→cliente | `weather_widget` | Datos de clima para tarjeta visual |
| servidor→cliente | `workspace_ok` | Workspace validado |
| servidor→cliente | `workspace_error` | Workspace inválido |
| servidor→cliente | `history_cleared` | Historial borrado |
| servidor→cliente | `error` | Error genérico |
## Variables de entorno
```env
GROQ_API_KEY=gsk_...
ELEVENLABS_API_KEY=sk_...
# Opcional
SERPER_API_KEY= # Búsqueda Google vía Serper
APP_TIMEZONE=America/Mexico_City # Zona horaria para «hoy»
GROQ_MODEL=llama-3.1-8b-instant
GROQ_STT_MODEL=whisper-large-v3-turbo
ELEVEN_VOICE_ID=B8gJV1IhpuegLxdpXFOE
ELEVEN_MODEL=eleven_v3
```