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

219 lines
8.6 KiB
Markdown

# 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
```
## 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
```