332 lines
11 KiB
Markdown
332 lines
11 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
|
||
```
|
||
|
||
## 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
|
||
```
|