Asistente personal de voz y chat que corre entero en tu propia red. Sin nube, sin claves de API, sin telemetría.
ANIMA es un asistente personal que habla y escucha en español, y que además tiene cuerpo: una pantalla TFT física en tu mesa muestra lo que está pensando. Todo el cómputo ocurre en tu PC. El teléfono es solo una ventana; el modelo nunca sale de tu casa.
| 🗣️ Habla y escucha | Pulsa el micrófono y mantén una conversación continua: ANIMA detecta cuándo callas y responde sola. |
| 🧠 Modelo local | Ollama sirve el LLM en 127.0.0.1:11434. Tú eliges el modelo en un .env. |
| ✋ Interrumpible | Habla mientras responde y se calla al instante: nunca te quedas esperando a que termine. |
| 📱 PWA instalable | Se añade a la pantalla de inicio del móvil como cualquier app. |
| 📺 Cuerpo físico | Una NodeMCU con TFT ST7735 renderiza estado y respuestas en tiempo real. |
| 🏠 Solo tu red | El ASR y el LLM escuchan únicamente en loopback. Nada se expone a Internet. |
ANIMA · Asistente de IA local con voz y pantalla TFT ESP8266
Demostración en hardware real: inteligencia artificial local, interacción por voz y pantalla física.
El Chat API es el único componente que el móvil y la placa conocen. Traduce entre el mundo HTTP/WebSocket de los clientes y los servicios internos, y serializa las peticiones al modelo para que dos dispositivos no se pisen.
Tres piezas independientes que se ejecutan juntas. Cada una tiene su propio README con el detalle de instalación.
| Directorio | Qué es | Arranque |
|---|---|---|
anima-ollama-tft/ |
Chat API FastAPI, PWA instalable y firmware ESP8266 para la TFT | uvicorn app:app --port 8000 |
anima-voice-server/ |
Motor de voz local: Whisper para transcribir, Piper para hablar | uvicorn voice_service:app --port 8001 |
anima-stack.py |
Lanzador único que levanta y supervisa los tres servicios | python3 anima-stack.py |
- Python 3.12 o superior
- Ollama instalado y con un modelo descargado
- Linux (probado en Pop!_OS). En macOS funciona igual; en Windows necesitas WSL para el motor de voz.
# 1. El modelo que ANIMA usa por defecto (~9 GB)
ollama pull qwen2.5-coder:14b
# 2. Preparar los dos entornos virtuales (solo la primera vez)
python3 -m venv anima-ollama-tft/server/.venv \
&& anima-ollama-tft/server/.venv/bin/pip install -r anima-ollama-tft/server/requirements.txt
python3 -m venv anima-voice-server/.venv \
&& anima-voice-server/.venv/bin/pip install -r anima-voice-server/requirements.txt
# 3. Descargar el modelo de voz Piper (73 MB)
mkdir -p anima-voice-server/models
curl -L -o anima-voice-server/models/es_ES-sharvard-medium.onnx \
https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/sharvard/medium/es_ES-sharvard-medium.onnx
# 4. Levantar todo el stack de una vez
python3 anima-stack.pyEl lanzador arranca Ollama si no está activo, la Chat API en el puerto 8000 y la Voice API en el 8001, unifica los logs en una sola terminal y reutiliza los servicios que ya estuvieran corriendo en lugar de duplicarlos. Después, abre http://127.0.0.1:8000.
Note
anima-stack.py comprueba que ambos entornos virtuales existen antes de arrancar: por eso los pasos 2 y 3 van antes. Si prefieres arrancar cada servicio a mano, sigue las instrucciones de anima-ollama-tft/README.md y anima-voice-server/README.md.
Tip
El lanzador deduce la ruta del proyecto a partir de su propia ubicación, así que funciona en cualquier carpeta donde clones el repositorio. Si necesitas apuntar a otra copia, exporta ANIMA_ROOT antes de ejecutarlo.
Chat API + PWA (puerto 8000)
cd anima-ollama-tft/server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # ajusta OLLAMA_MODEL si usas otro modelo
uvicorn app:app --host 0.0.0.0 --port 8000Comprueba que responde:
curl http://127.0.0.1:8000/health
# {"ok":true,"ollama":"connected","model":"qwen2.5-coder:14b","model_available":true,...}Voice API (puerto 8001)
cd anima-voice-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Descargar el modelo de voz Piper (73 MB); el .onnx.json ya está en el repo
curl -L -o models/es_ES-sharvard-medium.onnx \
https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/sharvard/medium/es_ES-sharvard-medium.onnx
WHISPER_MODEL=small WHISPER_DEVICE=cpu WHISPER_COMPUTE_TYPE=int8 \
uvicorn voice_service:app --host 127.0.0.1 --port 8001Whisper se descarga su propio modelo la primera vez que transcribe algo.
Firmware de la TFT (NodeMCU ESP8266)
cd anima-ollama-tft/firmware
cp include/secrets.example.h include/secrets.h # pon tu WiFi y la IP del PC
pio run --target upload # PlatformIOLa placa se conecta a ws://IP_DEL_PC:8000/ws y se reconecta sola cada 3 s si el PC se apaga.
El contrato entre componentes es pequeño a propósito:
| Canal | Ruta | Para qué |
|---|---|---|
| HTTP | POST /api/chat |
Enviar mensaje + historial, recibir respuesta |
| HTTP | POST /api/voice/transcribe |
Audio del navegador → texto (Whisper) |
| HTTP | POST /api/voice/speak |
Texto → WAV (Piper) |
| HTTP | GET /health |
¿Está Ollama arriba y el modelo disponible? |
| WebSocket | /ws |
Notificar a la TFT: status y response |
Ejemplo del contrato de chat:
curl -X POST http://127.0.0.1:8000/api/chat \
-H 'Content-Type: application/json' \
-d '{"message":"Responde solo: ANIMA online"}'{ "ok": true, "answer": "ANIMA online" }Los eventos que recibe la placa por el WebSocket:
{ "type": "status", "value": "thinking" }
{ "type": "response", "text": "ANIMA online" }
{ "type": "error", "text": "Error consultando Ollama" }Este proyecto está pensado para tu red doméstica, y su configuración por defecto refleja esa intención:
- Ollama y Whisper escuchan solo en
127.0.0.1. No son accesibles desde otros dispositivos de la red, ni siquiera desde el móvil. - El único puerto abierto en LAN es el 8000. Es el que necesita el teléfono y la placa.
- No hay telemetría ni servicios externos. La única conexión saliente es la descarga inicial de modelos.
- Los secretos están fuera del repositorio. Ni
.envnisecrets.hse versionan; sus plantillas.examplesí.
Warning
No expongas los puertos 8000 ni 11434 directamente a Internet. Para acceder desde fuera de casa, usa una VPN. Si necesitas HTTPS para instalar la PWA desde el móvil, pon un proxy inverso (Caddy, Nginx) delante del 8000 — el micrófono del navegador exige un contexto seguro.
ANIMA funciona de extremo a extremo: chat, voz y pantalla física. Lo que hay es honesto sobre lo que es — un proyecto personal, no un producto.
| Área | Estado |
|---|---|
| Chat con contexto e historial local | ✅ Funcional |
| Voz (ASR + TTS en español) | ✅ Funcional |
| Modo conversación con turnos por silencio | ✅ Funcional |
| Interrupción de ANIMA al hablar | ✅ Funcional |
| PWA instalable con shell offline | ✅ Funcional |
| Firmware TFT con reconexión | ✅ Funcional |
| Modo reposo de la TFT (reposo estático + salvapantallas animado) | ✅ Funcional |
| Tests automatizados | ✅ 17 pruebas con Node (node tests/*.test.mjs): 13 del modo conversación y 4 de inactividad |
| Autenticación |
Detalles conocidos a tener en cuenta
- HTTPS para el micrófono. Los navegadores solo conceden acceso al micrófono en contextos seguros. Por
http://127.0.0.1funciona; porhttp://192.168.x.xel botón de voz no aparecerá. - Un modelo a la vez. La Chat API serializa las peticiones con un lock: si dos móviles preguntan a la vez, la segunda espera. Es deliberado, para que la TFT no muestre estados contradictorios.
- La interrupción exige voz sostenida. Al hablar mientras ANIMA responde se necesita superar un umbral más alto durante ~330 ms. Es a propósito: con un umbral bajo, el eco del altavoz cortaría la respuesta sola en equipos sin cancelación de eco.
- Hay tres copias de
voice_service.py(anima-voice-server/,anima-ollama-tft/server/yanima-ollama-tft/voice/): hoy son funcionalmente equivalentes y la canónica es la deanima-voice-server; unificarlas es trabajo pendiente. Ver la nota al final deanima-voice-server/README.md. qwen2.5-coder:14bes el valor por defecto, pero está pensado para programar. Para conversación general,llama3.1:8bomistral-nemoresponden mejor y ocupan menos.
| Capa | Tecnología |
|---|---|
| Backend | Python 3.12 · FastAPI · Uvicorn · httpx |
| LLM | Ollama (qwen2.5-coder:14b por defecto) |
| Voz | faster-whisper (ASR) · Piper (TTS) |
| Frontend | HTML/CSS/JS sin build · Service Worker · Web App Manifest |
| Firmware | C++ · PlatformIO · ESP8266 · Adafruit ST7735 |
| Marca | Paleta #00151c · #35e6ce · #9af7e9 |
El material de marca vive en docs/branding/, y los originales que consume la PWA están en anima-ollama-tft/server/static/branding/ e icons/.
| Archivo | Uso |
|---|---|
anima-banner.png |
Cabecera de README (1600×400) |
anima-mark-compact.png |
Icono de cabecera para los READMEs de subproyecto |
anima-icon-256.png |
Avatar de repositorio / redes |
arquitectura.png |
Diagrama de arquitectura |
La paleta oficial: fondo #00151c, turquesa de marca #35e6ce, menta #9af7e9. El logotipo —un perfil femenino trazado con líneas de circuito— no se debe recolorear ni deformar. El diagrama se regenera con python3 docs/branding/make-diagram.py.
anima-asisstant/
├── anima-stack.py # Lanzador unificado con supervisión
├── tests/ # Pruebas Node de la PWA (sin navegador)
├── anima-ollama-tft/ # Chat API + PWA + firmware
│ ├── server/ # FastAPI, estáticos, .env
│ │ ├── app.py # Rutas de chat, voz y WebSocket
│ │ └── static/ # PWA, branding e iconos
│ ├── voice/ # Copia local del motor de voz
│ └── firmware/ # PlatformIO para la NodeMCU
├── anima-voice-server/ # ASR + TTS locales (copia canónica)
│ ├── voice_service.py # Endpoints /transcribe y /speak
│ └── models/ # Modelos Piper (los pesos no se versionan)
└── docs/branding/ # Material de marca y diagramas
MIT. Consulta LICENSE para el texto completo.
ANIMA · hecha para funcionar en casa, con tu hardware y tus datos.
