diff --git a/README.md b/README.md index 2cd4ebf..c90f53b 100644 --- a/README.md +++ b/README.md @@ -1,184 +1,46 @@ -# JARVIS +# JARVIS-AZUL 🔵 -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 **primer** carril de JARVIS, montado sobre **[Newelle](https://github.com/qwersyk/Newelle)** (el asistente de escritorio para GNOME, GPL). Hoy está **congelado**: sirvió para arrancar rápido y aprender qué se quería, y esas lecciones dieron pie al núcleo naranja. Esta rama lo documenta; el `master` es el núcleo naranja. -![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 del carril azul](azul/docs/arquitectura.svg) -![Arquitectura de JARVIS](docs/stack.svg) +## Para qué sirvió -![El panel de JARVIS](docs/panel.png) +JARVIS tiene tres carriles: **azul** (Newelle, este, congelado), **naranja** (el núcleo propio) y **verde** (Hermes Agent). El azul fue el punto de partida: en vez de escribir un asistente desde cero, se cogió Newelle —una app de GNOME que ya trae chat con LLM local, RAG de documentos, memoria, TTS, búsqueda web y extensiones— y se le puso encima la identidad de JARVIS. -*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/`.* +Fue la forma más rápida de tener algo que funcionara y, sobre todo, de **descubrir qué faltaba**. Lo que se aprendió aquí es lo que define hoy al naranja. + +## El interfaz + +![Newelle — la base del carril azul](azul/docs/newelle.png) + +*El interfaz de Newelle, base del carril azul. JARVIS lo corría **en local** con Ollama (no con el proveedor que aparece de ejemplo en la captura).* ## 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 | +| Capa | Pieza | Licencia | ¿Nube? | +|---|---|---|---| +| Front-end | Newelle (GNOME, Flatpak) | GPL | no | +| Cerebro | Ollama · modelo `qwen` local | Apache-2.0 | **no** — `127.0.0.1` | +| Hablar | Piper (voz clonada) | MIT | **no** | +| Oír | Whisper local | MIT | **no** | +| Saber | Documentos locales de Newelle (RAG) | — | **no** | -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. +## Lo que JARVIS le puso encima -## Portabilidad +Newelle es genérico; JARVIS lo personalizó (los ficheros viven en `config/` del núcleo): -Diseñado para correr en **cualquier Linux**, no en un equipo concreto: +- **Persona y prompt** propios (`set_persona.py`). +- **Voz** por Piper, la misma cadena de audio que usa el naranja (`jarvis-piper.sh`, `jarvis-voz.sh`). +- **Modelo** local afinado (`qwen3.5-4b-jarvis.Modelfile`, `apuntar_modelo_jarvis.py`). +- **Herramientas** propias. -| | | -|---|---| -| 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` | +## Por qué se congeló -**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). +Newelle es potente, pero va empaquetado como **Flatpak sobre GNOME**, y ese sandbox limita lo que el asistente puede tocar en la máquina. Se quería más: **control total del núcleo** —latencia baja, acciones rápidas que no pasan por el modelo, un HUD propio, root gestionado a demanda—. Nada de eso encajaba bien dentro de la app de escritorio de otro. -### Ajuste en tarjetas pequeñas (4 GB) +Así que el azul se congeló y nació el **carril naranja**, un núcleo escrito a medida. El azul se queda como referencia y como reconocimiento: fue el que enseñó el camino. -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](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 -``` - -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: - -```bash -./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](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](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](ROADMAP.md) (más gestores de ventanas, más -acciones, probar otros modelos, el RAG...) y cómo empezar en -[CONTRIBUTING.md](CONTRIBUTING.md). No hay que compilar nada: es Python, bash y -una página web. - -## Licencia - -[GPL-3.0](LICENSE). Software libre y copyleft: si lo modificas y lo distribuyes, -el resultado sigue siendo libre. +Newelle es de [@qwersyk](https://github.com/qwersyk/Newelle) (GPL). Este carril es esa base con la capa de JARVIS encima. Para el núcleo actual, ver la rama `master`; para el banco de pruebas agéntico, la rama `JARVIS-GREEN`. diff --git a/azul/docs/arquitectura.svg b/azul/docs/arquitectura.svg new file mode 100644 index 0000000..c61aed8 --- /dev/null +++ b/azul/docs/arquitectura.svg @@ -0,0 +1,89 @@ + + + + + + + + + + + + + JARVIS · carril azul + Newelle + — el primer carril, sobre una app de escritorio GNOME + + + + ❄ CONGELADO + reemplazado por el naranja + + + + TÚ + + + Voz y texto + en la ventana de Newelle + chat GTK · micrófono + + + + + NEWELLE (GNOME) + app de escritorio · orquesta el asistente + + Sus funciones (interruptores) + + Documentos locales (RAG) + Memoria de largo plazo + TTS + Virtualización de comandos + Búsqueda web + Extensiones (Python) + + + Lo que puso JARVIS encima + + Persona + prompt propio + Voz clonada (Piper) + Modelo qwen local + Herramientas propias + + + + + + Por qué se congeló + Newelle es potente y va sobre GNOME + Flatpak. Pero el + sandbox limita lo que el asistente puede tocar en la + máquina, y se quería control total del núcleo: latencia, + acciones rápidas sin pasar por el modelo, el HUD propio. + → nació el carril naranja (núcleo a medida). + + + EN TU MÁQUINA + + + Cerebro + Ollama · qwen local + 127.0.0.1 · sin nube + + + + Voz + Piper (habla) · Whisper (oye) + local, la misma cadena de audio + + + + + + + + + Software libre (GPL) · corría 100 % en local + el punto de partida: rápido de montar, con RAG, memoria y voz de serie + la lección que se llevó el naranja: buenas ideas, pero el sandbox y la latencia pedían un núcleo propio + diff --git a/azul/docs/newelle.png b/azul/docs/newelle.png new file mode 100644 index 0000000..71034b4 Binary files /dev/null and b/azul/docs/newelle.png differ