JARVIS/README.md

JARVIS

Asistente de voz 100 % local para Linux. Ni el micrófono, ni las conversaciones, ni el modelo salen de la máquina. Sin cuentas, sin claves, sin nube. Núcleo propio, en castellano, que corre en cualquier Linux —de un portátil modesto a una torre— y aprovecha la GPU si la hay, o la CPU si no.

El panel: telemetría del sistema, el reactor, lo que oye y hace, el catálogo de acciones, y las métricas de rendimiento del propio asistente. Hay un vídeo de ejemplo (47 s) en docs/.

El stack

Capa	Pieza	Papel
Oír	whisper.cpp	STT en castellano (GPU si hay, si no CPU)
Pensar	Ollama · qwen3.5:4b	el cerebro, con tool-calling
Saber	model2vec + búsqueda híbrida	RAG sobre los apuntes del usuario
Hablar	Piper (o voz clonada con XTTS)	TTS local
Cara	panel web · WebSocket · Canvas	el HUD, con el reactor y las métricas
Manos	catálogo de acciones + shell	lo que ejecuta en la máquina

Todo corre en 127.0.0.1. No hay ninguna llamada a la nube en el uso normal; lo único que puede salir es una búsqueda web si el modelo decide usarla, y se avisa.

Portabilidad

Diseñado para correr en cualquier Linux, no en un equipo concreto:

Distro	cualquiera. install.sh detecta apt / dnf / pacman / zypper
GPU	opcional. Ollama reparte el modelo entre GPU y CPU solo: va con NVIDIA (CUDA), AMD (ROCm) o solo CPU. Ningún parámetro está atado a una tarjeta
Escritorio	GNOME, KDE, lo que sea. Las acciones de ventanas necesitan X11 + xdotool; en Wayland esas órdenes se desactivan solas y el resto funciona igual
Audio	PipeWire, PulseAudio o ALSA. El micro prueba pw-record, parec y arecord, la primera que haya; la voz prueba paplay, pw-play y aplay
whisper	el binario se toma del build local o del PATH. Los modelos se buscan solos, o los fijas con JARVIS_WHISPER_MODELOS=/ruta

Requisito real: que quepa el modelo. qwen3.5:4b va cómodo desde ~4 GB de VRAM; con menos, usa un modelo más pequeño (qwen3.5:2b) o tira de CPU (hay RAM de sobra). whisper.cpp se compila para tu plataforma —CUDA, ROCm, Metal o CPU—; la guía está en config/README_whisper_gpu.md.

Ajuste en tarjetas pequeñas (4 GB)

Solo si vas MUY justo de VRAM y el cerebro y whisper se pelean por ella: fijar num_gpu 24 en el Modelfile reserva sitio a whisper. Está explicado en los comentarios del propio Modelfile. En una torre con una tarjeta normal no hace falta tocar nada.

Instalación

Necesita, en la máquina: Ollama, whisper.cpp (compilado para tu plataforma, ver config/README_whisper_gpu.md) y Piper.

git clone https://gitea.laenre.net/hacklab/JARVIS.git
cd JARVIS
./install.sh          # comprueba servicios, crea el venv y el modelo de Ollama

install.sh no descarga modelos pesados ni toca el sistema sin avisar: solo prepara el entorno de Python y crea qwen3.5:4b-jarvis a partir del Modelfile.

Después:

./nucleo/saber/indexa.py     # (opcional) indexa tus apuntes para el RAG
./nucleo/arranca.sh          # el asistente y el panel, en 127.0.0.1

El RAG funciona nada más clonar: el repo trae un índice público pre-construido, así que no hace falta indexar para que sepa de metodología, comandos y herramientas.

Comprobar el RAG

Si la búsqueda de conocimiento no responde bien, este diagnóstico revisa la cadena entera y marca en verde/rojo cada eslabón —dependencias, índice, embedder, búsqueda y Ollama— con una línea de qué hacer si algo falla:

./probar_rag.sh              # comprobaciones rápidas
./probar_rag.sh --eval       # además mide la calidad de recuperación (hit@k)
./probar_rag.sh --verboso    # enseña el primer resultado de cada búsqueda

No necesita nada arrancado y sale con código distinto de cero si hay algún fallo duro, así que sirve también para CI.

Qué le puedes pedir

Habla en castellano, natural. 150 acciones en el catálogo, agrupadas:

Grupo	Nº	Ejemplos
sistema	59	"cuánto espacio queda", "la memoria", "la carga de CPU", "la temperatura"
firefox	54	"abre el Gmail", "abre YouTube", "abre el GitHub", "abre Maps"
ventanas	12	"manda la ventana a la izquierda", "maximiza", "centra la ventana"
ficheros	11	"busca un fichero llamado…", "lee el fichero…", "cuánto ocupa la carpeta…"
pentest	8	"escanea la red", "los puertos del host…", "resuelve el dominio…", "el whois de…"
oasis	6	"está corriendo Oasis", "cuántas conexiones tiene"

Si lo que pides no está en el catálogo, el modelo lo resuelve con un comando de shell (de solo lectura por defecto). Y si pregunta cómo se hace algo técnico, puede buscar en tus apuntes (RAG) antes de responder.

El RAG es lo que hace que el asistente dé el comando que tú ya has probado en vez de inventarse los flags. Y no es un adorno: medido sobre un conjunto de preguntas de pentesting, la recuperación sube de hit@1 48 % → 82 % y hit@5 77 % → 95 %. El método, el pipeline y esos números están en docs/rag.md.

Y JARVIS elige su propio cerebro: si una pregunta es más dura de lo normal puede cambiar a un modelo más potente (elegir_modelo), y volver al rápido para lo simple. Dile "usa un modelo más potente" o fija uno con JARVIS_MODELO.

Órdenes con root — importante

Algunas órdenes que gestionan el sistema (instalar un paquete, reiniciar un servicio, montar un disco) necesitan sudo. Conviene saber cómo se maneja, porque es donde un asistente de voz puede hacer daño:

• No pide la contraseña al arrancar. Molestar de entrada echa para atrás, y la mayoría de lo que se le pide no necesita root. Arranca y funciona sin nada.
• Se pide solo cuando hace falta, y una vez. La primera vez que una orden necesita sudo, aparece un diálogo pidiendo tu contraseña. La tecleas, la repites, y a partir de ahí el permiso queda abierto para la sesión.
• Caduca a los 15 minutos de inactividad, y al cerrar el panel. No es un "root para siempre".
• La contraseña nunca se escribe en disco: vive solo en la memoria del proceso mientras dura la sesión, y se pasa a sudo -S por la entrada estándar.
• La voz no puede autoaprobar root. El permiso de sesión ahorra re-teclear la contraseña, nunca salta el pedirla la primera vez.

Si prefieres el modo seguro (bloquear el panel y pedir la contraseña al abrir, para que nadie que pase por delante dé órdenes), arranca con --candado.

Privacidad

Es la premisa, y se verifica. Ver PRIVACIDAD.md. Este repositorio no incluye los apuntes indexados ni el diario de conversación: son del usuario, y el .gitignore los bloquea.

Estructura

nucleo/           el asistente (oido, cerebro, boca, manos, cara, saber)
config/           configuración: modelo, voz, whisper
voz/              clonado de voz con XTTS y caché de frases
entrena/          fine-tuning con QLoRA
install.sh        el instalador

Estado y limitaciones

Proyecto en desarrollo. En el radar: acabar de generalizar los scripts de voz/ (algunos aún asumen la disposición del autor), las acciones de ventanas sobre Wayland (hoy solo X11), y el fine-tuning de entrena/, pendiente de un ajuste para modelos multimodales.

Contribuir

Se agradecen los commits: es software libre y hay mucho por hacer. Las ideas acotadas están en ROADMAP.md (más gestores de ventanas, más acciones, probar otros modelos, el RAG...) y cómo empezar en CONTRIBUTING.md. No hay que compilar nada: es Python, bash y una página web.

Licencia

GPL-3.0. Software libre y copyleft: si lo modificas y lo distribuyes, el resultado sigue siendo libre.