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