carril verde (Hermes Agent): documentacion, panel, voz local y RAG
Rama JARVIS-GREEN, independiente de master (el nucleo naranja queda intacto). - README propio del carril verde con diagrama de arquitectura y capturas del panel. - verde/: arranque, panel web, puente de voz (escucha local con faster-whisper + habla con la voz del naranja), pruebas (07 voz, 08 escucha), config y notas. - Integracion RAG: nucleo/saber/busca_cli.py + skill buscar-en-apuntes, para que el agente consulte el mismo indice que el nucleo. - Todo local (127.0.0.1); sin datos personales (rutas y modelo de GPU scrubeados).
This commit is contained in:
sito
parent
b1f8118272
commit
1e3e5ca20d
32 changed files with 3697 additions and 161 deletions
213
README.md
213
README.md
|
|
@ -1,184 +1,75 @@
|
|||
# JARVIS
|
||||
# JARVIS — carril verde 🟢
|
||||
|
||||
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.
|
||||
Banco de pruebas de JARVIS montado sobre **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** (Nous Research, MIT): un arnés agéntico completo, **100 % local por configuración**. Esta rama documenta el carril verde; el `master` es el núcleo naranja.
|
||||
|
||||
|
||||
|
||||
|
||||
-76B900)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Para qué sirve
|
||||
|
||||
|
||||
JARVIS tiene tres carriles: **cian** (Newelle, congelado), **naranja** (el núcleo propio) y **verde** (este). El verde responde a una pregunta: *¿un arnés agéntico de fábrica aporta algo que el núcleo naranja no tenga?* En concreto, las tres cosas que al naranja le faltan y que Hermes trae de serie:
|
||||
|
||||
*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/`.*
|
||||
- **Skills que el agente se crea y mejora solo.**
|
||||
- **Canales de mensajería** (Telegram, Discord, Signal, WhatsApp, Slack).
|
||||
- **Memoria** de largo plazo entre sesiones.
|
||||
|
||||
No es el asistente de diario —para eso está el naranja, que es más rápido—; es el laboratorio para decidir qué ideas de Hermes merece la pena llevar al núcleo.
|
||||
|
||||
## El panel
|
||||
|
||||
Hermes no es un chatbot: es una plataforma. El panel web (`verde/panel-verde.sh`, en `127.0.0.1:9119`) da chat, sesiones, ficheros, modelos, logs, cron, skills, MCP, canales y webhooks.
|
||||
|
||||
|
||||
|
||||
**82 skills** en 14 categorías, entre ellas la integración con el RAG del naranja:
|
||||
|
||||
|
||||
|
||||
## 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 | ¿Sale algo de la máquina? |
|
||||
|---|---|---|---|
|
||||
| Arnés | Hermes Agent | MIT | por configuración, no |
|
||||
| Cerebro | Ollama · `qwen3.5:4b-verde` (64k ctx) | Apache-2.0 | **no** — `127.0.0.1:11434` |
|
||||
| Oír | faster-whisper `small` (local, CPU) | MIT | **no** |
|
||||
| Hablar | Piper · `davefx` (misma voz que el naranja) | MIT | **no** |
|
||||
| Saber | RAG del naranja vía `busca_cli` | — | **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.
|
||||
## La integración con el RAG
|
||||
|
||||
## Portabilidad
|
||||
El agente consulta el **mismo índice que el núcleo naranja** (~19.500 entradas: metodología de pentesting, man pages, catálogo de herramientas y software, apps instaladas). Se hace con la skill local `buscar-en-apuntes` (en `verde/skills/`), que el agente activa cuando le preguntas por herramientas, comandos o "qué dicen mis apuntes sobre X", y responde citando la fuente en vez de inventar. Motor: `nucleo/saber/busca_cli.py`.
|
||||
|
||||
Diseñado para correr en **cualquier Linux**, no en un equipo concreto:
|
||||
## La voz, y en local
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 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` |
|
||||
El TUI de Hermes no trae micrófono y su STT nativo es para notas de voz de mensajería (que saldrían de la máquina). El carril lo puentea en local:
|
||||
|
||||
**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).
|
||||
- **Escucha** — `verde/escucha-verde.sh` (pulsar-para-hablar): graba → `faster-whisper` en CPU → se lo pasa al agente. Prueba: `verde/pruebas/08_escucha.sh`.
|
||||
- **Habla** — `verde/voz-verde.sh`: el mismo Piper y la misma voz que el naranja. Prueba: `verde/pruebas/07_voz.sh`.
|
||||
|
||||
### 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](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).
|
||||
## Arranque
|
||||
|
||||
```bash
|
||||
git clone https://gitea.laenre.net/hacklab/JARVIS.git
|
||||
cd JARVIS
|
||||
./install.sh # comprueba servicios, crea el venv y el modelo de Ollama
|
||||
# 1. Instalar Hermes Agent (ver su repo) y el modelo del verde
|
||||
ollama create qwen3.5:4b-verde -f verde/qwen3.5-4b-verde.Modelfile
|
||||
|
||||
# 2. Medir, configurar y dictaminar (encuentra el techo de contexto en tu GPU)
|
||||
./verde/arrancar.sh
|
||||
|
||||
# 3. El panel web, o el TUI en verde
|
||||
./verde/panel-verde.sh # dashboard en 127.0.0.1:9119
|
||||
./verde/verde-launcher.sh # TUI
|
||||
|
||||
# 4. Las pruebas (ninguna abre el TUI)
|
||||
./verde/pruebas/ejecutar.sh
|
||||
```
|
||||
|
||||
`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`.
|
||||
## El aviso que importa
|
||||
|
||||
Después:
|
||||
**Local por configuración, no por construcción.** El agente tiene terminal y web, y **decide por su cuenta**: en una prueba, pidiéndole un cartel ASCII, se fue a una API de terceros porque una librería no estaba instalada. Cerebro, voz, oído y memoria son locales y comprobados; lo que no está garantizado es **lo que el agente haga con la terminal que le has dado**. Está todo en `verde/NOTAS.md`.
|
||||
|
||||
```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 precio
|
||||
|
||||
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.
|
||||
Hermes exige ≥64k de contexto, lo que obliga a bajar media red del 4B a la CPU: el precio es el **tiempo de respuesta** (minutos por turno en frío). Es el dato que decide si el carril compensa frente al naranja. Medido y anotado en `verde/NOTAS.md`.
|
||||
|
||||
### 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.
|
||||
Software libre. Ver `verde/README.md`, `verde/NOTAS.md` y `verde/ESCALERA.md` para el detalle.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue