219 lines
8.6 KiB
Markdown
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
|
|
```
|