# 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.

![Linux](https://img.shields.io/badge/Linux-cualquier%20distro-FCC624?logo=linux&logoColor=black)
![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
![Ollama](https://img.shields.io/badge/Ollama-qwen3.5%3A4b-000000?logo=ollama&logoColor=white)
![GPU](https://img.shields.io/badge/GPU-opcional%20(NVIDIA%2FAMD%2FCPU)-76B900)
![whisper.cpp](https://img.shields.io/badge/whisper.cpp-STT-555555)
![Piper](https://img.shields.io/badge/Piper-TTS-555555)
![License](https://img.shields.io/badge/licencia-GPL--3.0-blue)

![Arquitectura de JARVIS](docs/stack.svg)

![El panel de JARVIS](docs/panel.png)

*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](docs/demo.webm) (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 o PulseAudio |

**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`](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**.

### Probado en

NVIDIA T1200 (4 GB), 62 GB RAM, Debian 12 con GNOME/X11. Es el equipo del autor,
el caso más ajustado; en una torre con más VRAM sobra sitio.

## Instalación

Necesita, en la máquina: [Ollama](https://ollama.com), whisper.cpp (compilado
para tu plataforma, ver [`config/README_whisper_gpu.md`](config/README_whisper_gpu.md))
y [Piper](https://github.com/rhasspy/piper).

```bash
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:

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

## 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](docs/rag.md).

## Órdenes con root

Algunas acciones necesitan `sudo`. El manejo es explícito y con límites, no un
"root para siempre":

- La contraseña **nunca se escribe en disco**. Vive en memoria del proceso solo
  si activas el permiso de sesión, y se pasa a `sudo -S` por la entrada estándar.
- El permiso de sesión **caduca a los 15 minutos** de la última orden, y también
  al cerrar el panel.
- **Cada** orden con root muestra su comando exacto en un diálogo antes de
  ejecutarlo. El permiso de sesión solo ahorra re-teclear la contraseña; nunca
  salta el ver y aprobar. **La voz no puede autoaprobar root.**

Con el candado echado, el asistente no obedece órdenes que toquen el sistema:
las pide desbloquear primero.

## Privacidad

Es la premisa, y se verifica. Ver [PRIVACIDAD.md](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.

## Licencia

[GPL-3.0](LICENSE). Software libre y copyleft: si lo modificas y lo distribuyes,
el resultado sigue siendo libre.