# Extender el asistente ## Añadir una herramienta Las herramientas son el punto de extensión pensado para lo que venga después: ejecutar órdenes, consultar cosas, encender luces. Una herramienta se describe a sí misma en JSON Schema y sabe ejecutarse; el registro se encarga del resto. Implementa `asist_core::tools::Tool`: ```rust use asist_core::error::{Error, Result}; use asist_core::tools::Tool; use serde_json::{json, Value}; pub struct Temperatura; impl Tool for Temperatura { fn name(&self) -> &str { "temperatura_cpu" } // La lee el modelo, así que se escribe para él: concreta y en español. fn description(&self) -> &str { "Devuelve la temperatura actual de la CPU en grados. Úsala cuando \ pregunten si el equipo está caliente." } fn parameters(&self) -> Value { json!({ "type": "object", "properties": {}, "required": [] }) } fn call(&self, _args: &Value) -> Result { let raw = std::fs::read_to_string("/sys/class/thermal/thermal_zone0/temp") .map_err(|e| Error::Tool { tool: self.name().into(), message: e.to_string() })?; let grados = raw.trim().parse::().unwrap_or(0.0) / 1000.0; Ok(format!("{grados:.1} grados")) } // Ponlo a true si cambia algo fuera del proceso. fn is_side_effecting(&self) -> bool { false } } ``` Y regístrala. Si no depende de nada, en `ToolRegistry::from_config` (`crates/asist-core/src/tools.rs`); si necesita la red, el modelo o un dispositivo, en `crates/asist-app/src/registry.rs`, que es donde se montan `buscar_en_internet` y `mirar_por_la_camara`: ```rust let mut tools = ToolRegistry::from_config(&config.tools); tools.register(std::sync::Arc::new(Temperatura)); ``` Si tarda más de un segundo, dale una frase de acuse. Se pronuncia antes de ejecutar y es lo que evita que la espera se lea como un cuelgue: ```rust fn acknowledgement(&self) -> Option<&str> { Some("Déjame que lo mire.") } ``` Tres cosas que conviene saber antes de escribir la primera: - **El error nunca tumba el turno.** `dispatch` convierte un fallo en texto y se lo devuelve al modelo, que lo explica o reintenta. - **La salida se lee en voz alta.** Devuelve una frase, no una tabla. El registro recorta a 2000 caracteres, pero mucho antes de eso ya aburre. - **Con este modelo, más herramientas es peor.** Con tres declaradas elige bien entre ellas (15 de 16 medido), pero le cuesta abstenerse: busca en internet cosas que ya sabe. Apartados 3 y 5 de [RENDIMIENTO.md](RENDIMIENTO.md). ## Ejecutar órdenes del sistema Ya está implementado y apagado (`tools.shell = false`). Encenderlo es un cambio de postura de seguridad, no una comodidad: lo que llega a esa herramienta viene, en última instancia, de lo que se oye por el micrófono. Las cuatro barreras que tiene, y que conviene no quitar: 1. **Apagada por defecto**, y la configuración se niega a arrancar con la lista blanca vacía. 2. **Lista blanca sobre el ejecutable.** Se compara `argv[0]` exacto, y las rutas se rechazan: `/bin/echo` no cuela aunque `echo` esté permitido. 3. **Sin shell de por medio.** Los argumentos van al `execve` tal cual, así que `; rm -rf /` es un argumento literal y no otra orden. 4. **Plazo máximo**, tras el cual el proceso se mata. ```toml [tools] shell = true shell_allowlist = ["date", "uptime", "free", "df", "ls"] shell_timeout_secs = 10 shell_dry_run = true # estrena la lista sin ejecutar nada shell_working_dir = "/home/elvis" ``` Empieza con `shell_dry_run = true`: registra lo que el modelo habría ejecutado sin llegar a hacerlo, que es la forma barata de descubrir qué pide de verdad. ## Buscar en internet Ya está montado, con tres buscadores intercambiables. ```toml [search] enabled = true backend = "tavily" # "tavily", "ddgs" o "searxng" api_key_env = "TAVILY_API_KEY" command = ["../scripts/buscar-ddgs.sh", "{consulta}", "{max}"] base_url = "" # para searxng: "http://127.0.0.1:8888" max_results = 5 ``` Cuál elegir, con las mismas dos preguntas medidas contra cada uno: | | «capital de Australia» | «qué tiempo hace hoy en Buenos Aires» | Clave | |---|---|---|---| | **tavily** | 0,54 s · *«El capital de Australia es Canberra…»* | 2,88 s · *«Hoy en Buenos Aires, cielo claro, máxima de 15°C…»* | sí | | **ddgs** | 2,24 s · fragmentos de tres páginas | 3,59 s · fragmentos de tres páginas | no | La diferencia que importa no es el tiempo sino la forma: **Tavily devuelve una respuesta ya redactada** y el asistente sólo tiene que leerla, mientras que ddgs devuelve fragmentos que el modelo tiene que resumir. Con 2B eso sale bien la mayoría de las veces —medido en el pipeline completo, «Hoy en Buenos Aires hace soleado esta mañana y por la tarde tendremos nubes con temperaturas alrededor de 9°C»— pero es una oportunidad más de equivocarse. Con clave, tavily. Sin clave, ddgs. ### Sobre DuckDuckGo `scripts/buscar-ddgs.sh` se apoya en la librería [`ddgs`](https://github.com/deedy5/ddgs), que es la misma que hay debajo de `duckduckgo-mcp`. Consulta DuckDuckGo, Brave, Mojeek, Startpage y alguno más, sin clave. Conviene instalarla de forma permanente para que cada búsqueda no pague la resolución del paquete: ```bash uv tool install ddgs # el guion también funciona con uvx, pero más lento ``` Dos caminos que parecen equivalentes y **no funcionan**, comprobados aquí: - `curl` contra `html.duckduckgo.com/html/` devuelve **HTTP 202** con una página anti-bot (`anomaly.js`) y ni un solo resultado. - La API sin clave `api.duckduckgo.com` (Instant Answer) devuelve vacío para casi todo lo que no sea una entidad de enciclopedia: probada con «capital de Australia» y con «qué tiempo hace en Buenos Aires», ambas sin nada. La librería sí funciona porque rota buscadores y cabeceras. ### Cualquier otro buscador El backend `ddgs` es en realidad un **backend de comando**: ejecuta un programa y lee JSON de su salida estándar. `{consulta}` y `{max}` se sustituyen antes de ejecutar, y el extractor acepta tanto la lista suelta que devuelve ddgs como la forma `{answer, results}`, con los campos nombrados a la manera de cada uno (`href` o `url`, `body` o `content`). Así que meter otro buscador —o un puente a un servidor MCP, que es un proceso que habla JSON-RPC por stdio— no es tocar Rust, sino escribir un guion: ```toml command = ["/ruta/a/mi-buscador.sh", "{consulta}", "{max}"] ``` Los argumentos van al `execve` tal cual, sin shell que los interprete: la consulta sale de lo que se ha oído por el micrófono y no puede acabar ejecutándose. ## Mirar por la cámara También montado. El servidor carga el proyector multimodal (`--mmproj`), así que el mismo modelo que conversa describe la imagen. ```toml [camera] enabled = true device = "/dev/video0" width = 640 # la resolución manda en la latencia: 2,9 s aquí, 7,8 s a 720p height = 480 warmup_frames = 5 # deja que se asiente la exposición automática save_dir = "" # vacío = no se guarda ningún fotograma ``` Tres decisiones que conviene no deshacer sin pensarlo: - **La pregunta viaja hasta la cámara.** El modelo rellena `pregunta` con lo que quiere averiguar, y esa pregunta acompaña a la imagen. Pedir una descripción genérica y luego interrogarla pierde el detalle que se buscaba. - **La imagen no entra en el historial.** Una foto ocupa cientos de tokens de contexto y arrastrarla turno tras turno saldría carísimo para lo poco que aporta una vez descrita. Lo que vuelve a la conversación es el texto. - **No se guarda nada en disco.** `save_dir` existe sólo para depurar qué está viendo el modelo; por defecto está vacío. Para ver la pantalla en vez de la cámara, `grim` ya está instalado: sería la misma herramienta cambiando cómo se obtienen los bytes del JPEG. ## Cambiar de motor Cada etapa habla con su motor a través de un único tipo, así que sustituir uno no toca el resto: | Etapa | Tipo | Fichero | |---|---|---| | Voz a texto | `asist_asr::Recognizer` | `crates/asist-asr/src/lib.rs` | | Modelo | `asist_llm::LlmClient` | `crates/asist-llm/src/client.rs` | | Texto a voz | `asist_tts::TtsClient` | `crates/asist-tts/src/lib.rs` | | Visión | `asist_llm::LlmClient::look` | `crates/asist-llm/src/client.rs` | | Buscar y mirar | `asist_tools` | `crates/asist-tools/src/` | El cliente HTTP (`asist_core::http`) es propio y mínimo a propósito: todo es HTTP plano contra localhost, y lo que ninguna librería genérica da cómodo es **abortar una respuesta a media descarga**, que es justo lo que sostiene la interrupción. Hay un segundo cliente, `ureq`, sólo en `asist-tools`: un buscador está detrás de HTTPS, y ahí hace falta TLS y no hace falta cortar a media descarga. Son dos clientes porque resuelven dos problemas distintos, no por descuido. ## Añadir una etapa al pipeline El orquestador (`crates/asist-app/src/pipeline.rs`) es una cadena de hilos unidos por canales. Para meter una etapa nueva —clasificar la intención, filtrar palabrotas, registrar la conversación— añade un hilo con `spawn_named` y un canal, y respeta las dos reglas que sostienen el conjunto: 1. **Nada bloquea al que va delante.** Si vas más lento que tu emisor, descarta trabajo; no acumules retraso. 2. **Comprueba el turno antes de gastar esfuerzo.** `session.is_current(turn)` dice si lo que estás a punto de hacer sigue interesando a alguien, o si el usuario ya ha dicho otra cosa. ## Cambiar la voz ```bash # Graba unos segundos de la voz que quieras y transcríbelos a mano. scripts/clonar-voz.sh grabacion.wav transcripcion.txt mivoz ``` Deja `assets/voices/mivoz.{spk,rvq,txt}`. Apunta ahí `[tts.reference]` en la configuración. Los latentes se extraen una vez; en cada arranque se manda lo ya extraído y no la grabación. También sirven las voces del propio modelo: quita `[tts.reference]` y pon `tts.voice` con un nombre de `GET /v1/audio/voices`. ## Ideas que el diseño ya admite - **Palabra de activación.** El segmentador ya entrega intervenciones sueltas: bastaría con filtrar por la transcripción antes de abrir turno. - **Memoria entre sesiones.** `Conversation` es serializable en la práctica; guardarla y recargarla al arrancar es un cambio pequeño. - **Multimodal.** El servidor ya carga `mmproj`, así que el modelo puede ver imágenes; faltaría meterlas en el mensaje de usuario.