aboutsummaryrefslogtreecommitdiffstats
path: root/crates
diff options
context:
space:
mode:
Diffstat (limited to 'crates')
-rw-r--r--crates/asist-app/Cargo.toml28
-rw-r--r--crates/asist-app/src/main.rs474
-rw-r--r--crates/asist-app/src/pipeline.rs634
-rw-r--r--crates/asist-app/src/render.rs258
-rw-r--r--crates/asist-app/src/session.rs160
-rw-r--r--crates/asist-app/src/supervisor.rs228
-rw-r--r--crates/asist-app/tests/integracion.rs266
-rw-r--r--crates/asist-asr/Cargo.toml15
-rw-r--r--crates/asist-asr/src/lib.rs401
-rw-r--r--crates/asist-audio/Cargo.toml12
-rw-r--r--crates/asist-audio/src/capture.rs153
-rw-r--r--crates/asist-audio/src/lib.rs148
-rw-r--r--crates/asist-audio/src/playback.rs287
-rw-r--r--crates/asist-audio/src/vad.rs403
-rw-r--r--crates/asist-core/Cargo.toml15
-rw-r--r--crates/asist-core/src/config.rs508
-rw-r--r--crates/asist-core/src/error.rs82
-rw-r--r--crates/asist-core/src/event.rs127
-rw-r--r--crates/asist-core/src/http.rs351
-rw-r--r--crates/asist-core/src/lib.rs17
-rw-r--r--crates/asist-core/src/telemetry.rs255
-rw-r--r--crates/asist-core/src/text.rs330
-rw-r--r--crates/asist-core/src/tools.rs563
-rw-r--r--crates/asist-llm/Cargo.toml12
-rw-r--r--crates/asist-llm/src/chat.rs275
-rw-r--r--crates/asist-llm/src/client.rs342
-rw-r--r--crates/asist-llm/src/lib.rs12
-rw-r--r--crates/asist-tts/Cargo.toml12
-rw-r--r--crates/asist-tts/src/lib.rs256
29 files changed, 6624 insertions, 0 deletions
diff --git a/crates/asist-app/Cargo.toml b/crates/asist-app/Cargo.toml
new file mode 100644
index 0000000..6a5daee
--- /dev/null
+++ b/crates/asist-app/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "asist-app"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[[bin]]
+name = "asistente"
+path = "src/main.rs"
+
+[dev-dependencies]
+asist-core.workspace = true
+asist-asr.workspace = true
+asist-llm.workspace = true
+asist-tts.workspace = true
+
+[dependencies]
+asist-core.workspace = true
+asist-audio.workspace = true
+asist-asr.workspace = true
+asist-llm.workspace = true
+asist-tts.workspace = true
+anyhow.workspace = true
+crossbeam-channel.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
diff --git a/crates/asist-app/src/main.rs b/crates/asist-app/src/main.rs
new file mode 100644
index 0000000..2788d97
--- /dev/null
+++ b/crates/asist-app/src/main.rs
@@ -0,0 +1,474 @@
+//! Asistente de voz local: escucha, piensa y responde hablando.
+//!
+//! Une tres motores que ya existen —Canary para oír, llama.cpp para pensar y
+//! qwentts para hablar— en un pipeline de hilos y canales donde ninguna etapa
+//! espera a la siguiente.
+
+mod pipeline;
+mod render;
+mod session;
+mod supervisor;
+
+use std::path::PathBuf;
+use std::time::Duration;
+
+use anyhow::{bail, Context, Result};
+use crossbeam_channel::unbounded;
+
+use asist_asr::Recognizer;
+use asist_audio::{Capture, CaptureBlock, Playback};
+use asist_core::config::Config;
+use asist_core::event::Event;
+use asist_core::tools::ToolRegistry;
+use asist_llm::LlmClient;
+use asist_tts::TtsClient;
+
+use pipeline::Pipeline;
+use render::Renderer;
+use session::Session;
+use supervisor::Supervisor;
+
+fn main() -> Result<()> {
+ let args = Args::parse()?;
+ if args.help {
+ println!("{USAGE}");
+ return Ok(());
+ }
+ init_logging(&args);
+
+ let mut config = Config::load(&args.config)
+ .with_context(|| format!("no se pudo cargar {}", args.config.display()))?;
+ args.apply(&mut config);
+
+ match args.command {
+ Command::Run => run(config, &args),
+ Command::Devices => devices(),
+ Command::Check => check(&config),
+ }
+}
+
+fn run(config: Config, args: &Args) -> Result<()> {
+ let session = Session::new();
+
+ // Los clientes se crean antes de arrancar nada: así se detecta lo que ya
+ // esté escuchando y no se levanta un servidor por duplicado.
+ let llm = LlmClient::new(config.llm_authority(), &config.llm);
+ let tts = TtsClient::new(config.tts_authority(), &config.tts);
+ let (llm_up, tts_up) = (llm.healthy(), tts.healthy());
+
+ let mut supervisor = Supervisor::new(&args.log_dir)?;
+ supervisor.start(&config, llm_up, tts_up)?;
+
+ let timeout = Duration::from_secs(config.supervisor.startup_timeout_secs);
+ eprintln!("Esperando a los motores (hasta {} s)…", timeout.as_secs());
+ llm.wait_ready(timeout).map_err(|e| {
+ anyhow::anyhow!(
+ "{e}\nRevisa {}",
+ supervisor.log_path("llama-server").display()
+ )
+ })?;
+ tts.wait_ready(timeout).map_err(|e| {
+ anyhow::anyhow!(
+ "{e}\nRevisa {}",
+ supervisor.log_path("tts-server").display()
+ )
+ })?;
+ llm.warn_if_thinking_template();
+
+ if let Some(reference) = &config.tts.reference {
+ tts.register_voice(reference)
+ .context("no se pudo registrar la voz clonada")?;
+ }
+ // Se paga aquí la construcción de los grafos del sintetizador, unos 3,5 s
+ // que si no se los comería el primer turno de verdad.
+ if let Err(err) = tts.warmup() {
+ tracing::warn!(target: "tts", %err, "falló el precalentado; el primer turno irá lento");
+ }
+
+ eprintln!("Cargando el modelo de voz a texto…");
+ let recognizer = Recognizer::load(&config.asr)?;
+
+ let playback = Playback::open(&config.audio)?;
+ let (capture_tx, capture_rx) = unbounded::<CaptureBlock>();
+ let capture = Capture::open(&config.audio, capture_tx.clone())?;
+
+ let tools = ToolRegistry::from_config(&config.tools);
+ if tools.is_empty() {
+ eprintln!("Herramientas: ninguna");
+ } else {
+ eprintln!("Herramientas: {}", tools.names().join(", "));
+ }
+ if config.tools.shell {
+ eprintln!(
+ "Ejecución de órdenes ACTIVA — permitidas: {}{}",
+ config.tools.shell_allowlist.join(", "),
+ if config.tools.shell_dry_run {
+ " (simulación)"
+ } else {
+ ""
+ }
+ );
+ }
+
+ let pipeline = Pipeline::spawn(
+ &config,
+ session.clone(),
+ recognizer,
+ llm,
+ tts,
+ tools,
+ playback.handle(),
+ capture_rx,
+ capture_tx,
+ capture.format,
+ )?;
+
+ eprintln!(
+ "\nListo. Micrófono: {} · Altavoz: {} ({} Hz)\nHabla cuando quieras. Enter para salir.\n",
+ capture.device_name, playback.device_name, playback.sample_rate
+ );
+
+ // Enter cierra, pero sólo si hay alguien delante para pulsarlo. Con la
+ // entrada redirigida —bajo systemd, en un contenedor, con `< /dev/null`—
+ // `read_line` devuelve EOF al instante y el asistente se cerraría nada
+ // más arrancar. En ese caso se espera a una señal.
+ if stdin_is_tty() {
+ let session = session.clone();
+ std::thread::spawn(move || {
+ let mut line = String::new();
+ let _ = std::io::stdin().read_line(&mut line);
+ session.request_stop();
+ });
+ } else {
+ eprintln!("(entrada no interactiva: para cerrar, manda SIGINT o SIGTERM)");
+ install_signal_handler(session.clone());
+ }
+
+ let mut renderer = Renderer::new(config.asr.partials);
+ let metrics = std::sync::Arc::clone(&pipeline.metrics);
+ let mut next_health_check = std::time::Instant::now() + Duration::from_secs(5);
+ loop {
+ match pipeline.events.recv_timeout(Duration::from_millis(150)) {
+ Ok(event) => {
+ let shutdown = matches!(event, Event::Shutdown);
+ renderer.apply(&event);
+ if shutdown {
+ break;
+ }
+ }
+ Err(crossbeam_channel::RecvTimeoutError::Timeout) => {}
+ Err(crossbeam_channel::RecvTimeoutError::Disconnected) => break,
+ }
+ if session.is_stopping() {
+ break;
+ }
+ // Si un servidor se muere a mitad de sesión, todos los turnos
+ // siguientes fallarían con un error de transporte sin explicar por
+ // qué. Mejor decirlo una vez, con el registro a mano, y cerrar.
+ if std::time::Instant::now() >= next_health_check {
+ next_health_check = std::time::Instant::now() + Duration::from_secs(5);
+ if let Some((name, code)) = supervisor.crashed() {
+ renderer.finish();
+ eprintln!(
+ "\n{name} ha terminado inesperadamente (código {}). Revisa {}",
+ code.map(|c| c.to_string())
+ .unwrap_or_else(|| "desconocido".into()),
+ supervisor.log_path(name).display()
+ );
+ break;
+ }
+ }
+ }
+
+ renderer.finish();
+ capture.stop();
+ pipeline.shutdown();
+ playback.stop();
+ supervisor.shutdown();
+
+ if metrics.turns() > 0 {
+ eprintln!("\n{}", metrics.summary());
+ }
+ Ok(())
+}
+
+/// Lista los dispositivos de audio, para poder nombrarlos en la configuración.
+fn devices() -> Result<()> {
+ use asist_audio::describe;
+ use cpal_reexport::traits::HostTrait;
+ let host = cpal_reexport::default_host();
+
+ let default_in = host.default_input_device().map(|d| describe(&d));
+ println!("Entradas:");
+ for device in host.input_devices()? {
+ let name = describe(&device);
+ let mark = if Some(&name) == default_in.as_ref() {
+ " (por defecto)"
+ } else {
+ ""
+ };
+ println!(" {name}{mark}");
+ }
+
+ let default_out = host.default_output_device().map(|d| describe(&d));
+ println!("\nSalidas:");
+ for device in host.output_devices()? {
+ let name = describe(&device);
+ let mark = if Some(&name) == default_out.as_ref() {
+ " (por defecto)"
+ } else {
+ ""
+ };
+ println!(" {name}{mark}");
+ }
+ Ok(())
+}
+
+/// Comprueba que está todo en su sitio, sin abrir el micrófono.
+fn check(config: &Config) -> Result<()> {
+ let mut problems = Vec::new();
+ let ok = |label: &str, detail: String| println!(" ok {label:<22} {detail}");
+
+ let paths: [(&str, &std::path::Path); 6] = [
+ ("modelo asr", &config.asr.model_dir),
+ ("binario llama", &config.supervisor.llama.binary),
+ ("modelo llm", &config.supervisor.llama.model),
+ ("plantilla chat", &config.supervisor.llama.chat_template),
+ ("binario tts", &config.supervisor.tts.binary),
+ ("modelo tts", &config.supervisor.tts.model),
+ ];
+ println!("Ficheros:");
+ for (label, path) in paths {
+ if path.exists() {
+ ok(label, path.display().to_string());
+ } else {
+ println!(" FALTA {label:<22} {}", path.display());
+ problems.push(format!("falta {label}: {}", path.display()));
+ }
+ }
+
+ if let Some(reference) = &config.tts.reference {
+ println!("Voz de referencia «{}»:", reference.name);
+ for (label, path) in [
+ ("hablante (.spk)", &reference.speaker),
+ ("códigos (.rvq)", &reference.codes),
+ ("transcripción", &reference.transcript),
+ ] {
+ if path.exists() {
+ ok(label, path.display().to_string());
+ } else {
+ println!(" FALTA {label:<22} {}", path.display());
+ problems.push(format!("falta {label}"));
+ }
+ }
+ }
+
+ println!("Servidores:");
+ let llm = LlmClient::new(config.llm_authority(), &config.llm);
+ let tts = TtsClient::new(config.tts_authority(), &config.tts);
+ for (label, up, authority) in [
+ ("llama-server", llm.healthy(), config.llm_authority()),
+ ("tts-server", tts.healthy(), config.tts_authority()),
+ ] {
+ println!(
+ " {:<5} {label:<22} {authority}",
+ if up { "ok" } else { "-" }
+ );
+ }
+ if llm.healthy() {
+ llm.warn_if_thinking_template();
+ }
+ if tts.healthy() {
+ match tts.voices() {
+ Ok(voices) if voices.contains(&config.tts.voice) => {
+ println!(" ok voz «{}» registrada", config.tts.voice);
+ }
+ Ok(voices) => println!(
+ " - voz «{}» aún no registrada (hay: {})",
+ config.tts.voice,
+ voices.join(", ")
+ ),
+ Err(err) => println!(" - no se pudieron listar las voces: {err}"),
+ }
+ }
+
+ if problems.is_empty() {
+ println!("\nTodo listo.");
+ Ok(())
+ } else {
+ bail!(
+ "{} problema(s):\n - {}",
+ problems.len(),
+ problems.join("\n - ")
+ )
+ }
+}
+
+// cpal se usa aquí sólo para listar dispositivos; llega a través de asist-audio.
+use asist_audio::cpal as cpal_reexport;
+
+const USAGE: &str = "\
+asistente — asistente de voz local
+
+USO:
+ asistente [ORDEN] [OPCIONES]
+
+ÓRDENES:
+ run Escucha y responde (por defecto)
+ check Comprueba ficheros, modelos y servidores, y sale
+ devices Lista los dispositivos de audio
+
+OPCIONES:
+ -c, --config <RUTA> Fichero de configuración [config/asistente.toml]
+ --log-dir <RUTA> Carpeta de los registros de los servidores [logs/]
+ --voice <NOMBRE> Voz del sintetizador
+ --no-manage No lanzar los servidores; suponerlos ya arriba
+ --no-partials Sin transcripción provisional (ahorra CPU)
+ --barge-in Permitir cortar al asistente hablando encima
+ --shell Activar la ejecución de órdenes del sistema
+ -v, --verbose Registro de depuración (equivale a RUST_LOG=debug)
+ -h, --help Esta ayuda
+
+VARIABLES:
+ RUST_LOG Filtro de registro, p. ej. «info,tts=debug,latencia=info»
+";
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Command {
+ Run,
+ Check,
+ Devices,
+}
+
+struct Args {
+ command: Command,
+ config: PathBuf,
+ log_dir: PathBuf,
+ voice: Option<String>,
+ no_manage: bool,
+ no_partials: bool,
+ barge_in: bool,
+ shell: bool,
+ verbose: bool,
+ help: bool,
+}
+
+impl Args {
+ fn parse() -> Result<Self> {
+ let mut args = Self {
+ command: Command::Run,
+ config: PathBuf::from("config/asistente.toml"),
+ log_dir: PathBuf::from("logs"),
+ voice: None,
+ no_manage: false,
+ no_partials: false,
+ barge_in: false,
+ shell: false,
+ verbose: false,
+ help: false,
+ };
+ let mut raw = std::env::args().skip(1);
+ while let Some(arg) = raw.next() {
+ match arg.as_str() {
+ "run" => args.command = Command::Run,
+ "check" => args.command = Command::Check,
+ "devices" => args.command = Command::Devices,
+ "-c" | "--config" => {
+ args.config = raw.next().context("--config necesita una ruta")?.into()
+ }
+ "--log-dir" => {
+ args.log_dir = raw.next().context("--log-dir necesita una ruta")?.into()
+ }
+ "--voice" => args.voice = Some(raw.next().context("--voice necesita un nombre")?),
+ "--no-manage" => args.no_manage = true,
+ "--no-partials" => args.no_partials = true,
+ "--barge-in" => args.barge_in = true,
+ "--shell" => args.shell = true,
+ "-v" | "--verbose" => args.verbose = true,
+ "-h" | "--help" => args.help = true,
+ other => bail!("opción desconocida: {other}\n\n{USAGE}"),
+ }
+ }
+ Ok(args)
+ }
+
+ /// La línea de órdenes manda sobre el fichero.
+ fn apply(&self, config: &mut Config) {
+ if let Some(voice) = &self.voice {
+ config.tts.voice = voice.clone();
+ }
+ if self.no_manage {
+ config.supervisor.manage = false;
+ }
+ if self.no_partials {
+ config.asr.partials = false;
+ }
+ if self.barge_in {
+ config.vad.barge_in = true;
+ }
+ if self.shell {
+ config.tools.shell = true;
+ }
+ }
+}
+
+/// ¿Hay una persona al otro lado de la entrada estándar?
+fn stdin_is_tty() -> bool {
+ #[cfg(unix)]
+ {
+ unsafe extern "C" {
+ fn isatty(fd: i32) -> i32;
+ }
+ unsafe { isatty(0) == 1 }
+ }
+ #[cfg(not(unix))]
+ true
+}
+
+/// Cierre ordenado ante SIGINT/SIGTERM.
+///
+/// Importa más de lo que parece: matar el proceso en seco deja a los
+/// servidores hijos con la memoria de la GPU tomada.
+#[cfg(unix)]
+fn install_signal_handler(session: Session) {
+ use std::sync::OnceLock;
+ static SESSION: OnceLock<Session> = OnceLock::new();
+ let _ = SESSION.set(session);
+
+ extern "C" fn on_signal(_: i32) {
+ if let Some(session) = SESSION.get() {
+ session.request_stop();
+ }
+ }
+ unsafe extern "C" {
+ fn signal(sig: i32, handler: extern "C" fn(i32)) -> usize;
+ }
+ unsafe {
+ signal(2, on_signal); // SIGINT
+ signal(15, on_signal); // SIGTERM
+ }
+}
+
+#[cfg(not(unix))]
+fn install_signal_handler(_session: Session) {}
+
+fn init_logging(args: &Args) {
+ use tracing_subscriber::{fmt, EnvFilter};
+ // ONNX Runtime informa a nivel INFO de cada transformación del grafo:
+ // varios cientos de líneas que tapan la transcripción. Se silencia salvo
+ // que se pida expresamente por RUST_LOG.
+ let default = if args.verbose {
+ "debug,ort=warn"
+ } else {
+ "info,ort=warn"
+ };
+ let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(default));
+ fmt()
+ .with_env_filter(filter)
+ // Al terminal de texto van la transcripción y la respuesta; el registro
+ // va a stderr para que se puedan separar con una redirección.
+ .with_writer(std::io::stderr)
+ .with_target(true)
+ .without_time()
+ .init();
+}
diff --git a/crates/asist-app/src/pipeline.rs b/crates/asist-app/src/pipeline.rs
new file mode 100644
index 0000000..9e9037e
--- /dev/null
+++ b/crates/asist-app/src/pipeline.rs
@@ -0,0 +1,634 @@
+//! El orquestador: los hilos del asistente y los canales que los unen.
+//!
+//! ```text
+//! micrófono ──muestras──> segmentador ──intervención──> ASR ──texto──┐
+//! (cpal, tiempo real) (VAD, turnos) (Canary) │
+//! v
+//! altavoz <──muestras── síntesis <──frases── conversación <──────────┘
+//! (cpal, anillo) (qwentts) (llama.cpp + herramientas)
+//! ```
+//!
+//! Cada caja es un hilo y cada flecha un canal. Dos consecuencias que valen
+//! por todo el diseño:
+//!
+//! * **Nada bloquea al que va delante.** El micrófono nunca espera al ASR, y
+//! el modelo nunca espera al sintetizador; quien va sobrado descarta trabajo
+//! en lugar de acumular retraso.
+//! * **Se responde por frases, no por respuestas.** La conversación entrega
+//! cada frase al sintetizador en cuanto está cerrada, así que el asistente
+//! empieza a hablar mientras el modelo sigue escribiendo. Es lo que separa
+//! una latencia de medio segundo de una de cinco.
+
+use std::sync::Arc;
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+use crossbeam_channel::{bounded, unbounded, Receiver, Select, Sender};
+
+use asist_asr::{AsrJob, AsrResult, Recognizer};
+use asist_audio::{
+ CaptureBlock, Gate, InputFormat, PlaybackHandle, Segmenter, VoiceEvent, ASR_SAMPLE_RATE,
+};
+use asist_core::config::Config;
+use asist_core::error::Result;
+use asist_core::event::{Event, InterruptReason, TurnId};
+use asist_core::telemetry::{Metrics, Stage, TurnTimer};
+use asist_core::text::SentenceSplitter;
+use asist_core::tools::ToolRegistry;
+use asist_llm::chat::Conversation;
+use asist_llm::{Delta, LlmClient, Message};
+use asist_tts::TtsClient;
+
+use crate::session::Session;
+
+/// Una frase pendiente de sintetizar.
+#[derive(Debug)]
+pub struct SpeakJob {
+ pub turn: TurnId,
+ pub index: usize,
+ pub text: String,
+ /// Origen desde el que se mide la latencia percibida del turno.
+ pub turn_started: Instant,
+}
+
+/// Los hilos en marcha, para poder esperarlos al cerrar.
+pub struct Pipeline {
+ handles: Vec<JoinHandle<()>>,
+ pub events: Receiver<Event>,
+ pub metrics: Arc<Metrics>,
+ session: Session,
+ capture_tx: Option<Sender<CaptureBlock>>,
+}
+
+impl Pipeline {
+ /// Monta el pipeline entero. `capture_rx` viene del micrófono.
+ #[allow(clippy::too_many_arguments)]
+ pub fn spawn(
+ config: &Config,
+ session: Session,
+ recognizer: Recognizer,
+ llm: LlmClient,
+ tts: TtsClient,
+ tools: ToolRegistry,
+ playback: PlaybackHandle,
+ capture_rx: Receiver<CaptureBlock>,
+ capture_tx: Sender<CaptureBlock>,
+ input_format: InputFormat,
+ ) -> Result<Self> {
+ let (event_tx, event_rx) = unbounded::<Event>();
+ let (asr_tx, asr_rx) = unbounded::<AsrJob>();
+ let (result_tx, result_rx) = unbounded::<AsrResult>();
+ // Acotado a propósito: si la síntesis se atasca, el hilo de
+ // conversación debe notarlo y frenar en lugar de acumular frases que
+ // llegarán tarde a un turno que quizá ya se ha interrumpido.
+ let (speak_tx, speak_rx) = bounded::<SpeakJob>(8);
+
+ let metrics = Arc::new(Metrics::default());
+ let mut handles = Vec::new();
+
+ handles.push(spawn_named("segmentador", {
+ let config = config.clone();
+ let session = session.clone();
+ let events = event_tx.clone();
+ let playback = playback.clone();
+ move || {
+ run_segmenter(
+ &config,
+ session,
+ capture_rx,
+ asr_tx,
+ events,
+ playback,
+ input_format,
+ )
+ }
+ }));
+
+ handles.push(spawn_named("asr", move || {
+ recognizer.run(asr_rx, result_tx)
+ }));
+
+ handles.push(spawn_named("conversación", {
+ let config = config.clone();
+ let session = session.clone();
+ let events = event_tx.clone();
+ let metrics = Arc::clone(&metrics);
+ move || {
+ run_brain(
+ &config, session, llm, tools, result_rx, speak_tx, events, metrics,
+ )
+ }
+ }));
+
+ handles.push(spawn_named("síntesis", {
+ let session = session.clone();
+ let events = event_tx;
+ move || run_speech(session, tts, speak_rx, playback, events)
+ }));
+
+ Ok(Self {
+ handles,
+ events: event_rx,
+ metrics,
+ session,
+ capture_tx: Some(capture_tx),
+ })
+ }
+
+ /// Cierra en orden: se corta lo que suena, se suelta el emisor del
+ /// micrófono y con eso la cadena de hilos se desmonta sola.
+ pub fn shutdown(mut self) {
+ self.session.request_stop();
+ self.capture_tx.take();
+ for handle in self.handles.drain(..) {
+ let _ = handle.join();
+ }
+ }
+}
+
+fn spawn_named(name: &str, body: impl FnOnce() + Send + 'static) -> JoinHandle<()> {
+ thread::Builder::new()
+ .name(name.to_string())
+ .spawn(body)
+ .expect("no se pudo crear un hilo del pipeline")
+}
+
+// ---------------------------------------------------------------------------
+// Segmentador: micrófono -> intervenciones
+// ---------------------------------------------------------------------------
+
+fn run_segmenter(
+ config: &Config,
+ session: Session,
+ capture: Receiver<CaptureBlock>,
+ asr: Sender<AsrJob>,
+ events: Sender<Event>,
+ playback: PlaybackHandle,
+ input_format: InputFormat,
+) {
+ let mut segmenter = Segmenter::new(&config.vad);
+ let mut turn = session.current();
+
+ while let Ok(block) = capture.recv() {
+ if session.is_stopping() {
+ break;
+ }
+ // El micrófono se cierra mientras suena el altavoz. Con barge-in
+ // activo no se cierra, sólo sube el listón de volumen.
+ segmenter.set_gate(if session.is_speaking() || playback.is_active() {
+ Gate::Speaking
+ } else {
+ Gate::Open
+ });
+
+ // El dispositivo se abre a 16 kHz mono siempre que puede, y entonces
+ // esto no hace nada; cuando no puede, es aquí donde se convierte.
+ let mono = asist_audio::to_mono_at(&block.samples, input_format, ASR_SAMPLE_RATE);
+
+ for event in segmenter.push(&mono) {
+ match event {
+ VoiceEvent::BargeIn => {
+ // Se corta antes de abrir el turno nuevo: así lo que
+ // quedaba en el anillo no se cuela por encima.
+ playback.stop();
+ session.interrupt();
+ let _ = events.send(Event::Interrupted {
+ turn: session.current(),
+ reason: InterruptReason::UserSpoke,
+ });
+ }
+ VoiceEvent::Started => {
+ turn = session.begin_turn();
+ let _ = events.send(Event::SpeechStarted { turn, at: block.at });
+ }
+ VoiceEvent::Audio(samples) => {
+ if config.asr.partials
+ && asr
+ .send(AsrJob::Window {
+ turn,
+ samples,
+ at: block.at,
+ })
+ .is_err()
+ {
+ return;
+ }
+ }
+ VoiceEvent::Ended(utterance) => {
+ let at = Instant::now();
+ if asr
+ .send(AsrJob::Utterance {
+ turn,
+ samples: utterance.samples,
+ at,
+ })
+ .is_err()
+ {
+ return;
+ }
+ }
+ VoiceEvent::Discarded => {
+ if asr.send(AsrJob::Reset { turn }).is_err() {
+ return;
+ }
+ }
+ }
+ }
+ }
+ // Lo que quedara a medias al cerrar todavía merece transcribirse.
+ if let Some(utterance) = segmenter.flush() {
+ let _ = asr.send(AsrJob::Utterance {
+ turn,
+ samples: utterance.samples,
+ at: Instant::now(),
+ });
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Conversación: transcripción -> frases
+// ---------------------------------------------------------------------------
+
+#[allow(clippy::too_many_arguments)]
+fn run_brain(
+ config: &Config,
+ session: Session,
+ llm: LlmClient,
+ tools: ToolRegistry,
+ results: Receiver<AsrResult>,
+ speak: Sender<SpeakJob>,
+ events: Sender<Event>,
+ metrics: Arc<Metrics>,
+) {
+ let prompts = Prompts::new(config, &tools);
+ let mut chat = Conversation::new(prompts.deciding.clone(), config.general.history_turns);
+
+ while let Ok(result) = results.recv() {
+ if session.is_stopping() {
+ break;
+ }
+ match result {
+ AsrResult::Partial {
+ turn,
+ committed,
+ volatile,
+ ..
+ } => {
+ let _ = events.send(Event::Partial {
+ turn,
+ committed,
+ volatile,
+ });
+ }
+ AsrResult::Empty { turn } => {
+ let _ = events.send(Event::Discarded { turn });
+ }
+ AsrResult::Error { turn, message } => {
+ let _ = events.send(Event::Warning { turn, message });
+ }
+ AsrResult::Final {
+ turn,
+ text,
+ audio_secs,
+ decode,
+ spoken_at,
+ } => {
+ // Una transcripción de un turno superado llega tarde: el
+ // usuario ya ha dicho otra cosa.
+ if !session.is_current(turn) {
+ tracing::debug!(target: "brain", turno = turn.0, "transcripción obsoleta");
+ continue;
+ }
+ let mut timer = TurnTimer::new(turn);
+ timer.input_secs = audio_secs;
+ timer.record(Stage::Asr, decode);
+
+ let _ = events.send(Event::Transcript {
+ turn,
+ text: text.clone(),
+ audio_secs,
+ decode,
+ });
+
+ chat.push(Message::user(text));
+ answer(
+ config, &session, &llm, &tools, &prompts, &mut chat, &speak, &events,
+ &mut timer, spoken_at,
+ );
+
+ if config.general.report_latency {
+ tracing::info!(target: "latencia", "\n{}", timer.report());
+ }
+ metrics.record_turn(&timer);
+ }
+ }
+ }
+}
+
+/// Las dos instrucciones de sistema entre las que alterna un turno.
+///
+/// Que sean dos no es un capricho de diseño sino un resultado medido: con
+/// Qwen3.5-2B, cualquier indicación de estilo junto a la guía de herramientas
+/// hace que el modelo deje de llamarlas y se invente el dato (8/8 aciertos con
+/// la guía sola, 0/8 con la persona de asistente de voz añadida). Así que la
+/// pasada en que el modelo *decide* si actuar lleva la guía a solas, y la
+/// instrucción de voz se reserva para redactar lo que se va a pronunciar.
+struct Prompts {
+ /// Para la pasada en que el modelo decide si llamar a una herramienta.
+ deciding: String,
+ /// Para redactar la respuesta hablada, ya con los resultados en la mano.
+ speaking: String,
+ /// `false` cuando no hay herramientas: entonces ambas son la misma.
+ two_phase: bool,
+}
+
+impl Prompts {
+ fn new(config: &Config, tools: &ToolRegistry) -> Self {
+ let speaking = config.general.system_prompt.trim().to_string();
+ let two_phase = config.tools.enabled && config.tools.dedicated_prompt && !tools.is_empty();
+ Self {
+ deciding: if two_phase {
+ config.general.tools_prompt.trim().to_string()
+ } else {
+ speaking.clone()
+ },
+ speaking,
+ two_phase,
+ }
+ }
+}
+
+/// Genera la respuesta de un turno, resolviendo herramientas si el modelo las
+/// pide, y va soltando frases al sintetizador según se cierran.
+#[allow(clippy::too_many_arguments)]
+fn answer(
+ config: &Config,
+ session: &Session,
+ llm: &LlmClient,
+ tools: &ToolRegistry,
+ prompts: &Prompts,
+ chat: &mut Conversation,
+ speak: &Sender<SpeakJob>,
+ events: &Sender<Event>,
+ timer: &mut TurnTimer,
+ turn_started: Instant,
+) {
+ let turn = timer.turn;
+ let tools = (!tools.is_empty() && config.tools.enabled).then_some(tools);
+ let mut splitter = SentenceSplitter::new();
+ let mut spoken = String::new();
+
+ for round in 0..=config.llm.max_tool_rounds {
+ let llm_started = Instant::now();
+ let mut first_token = None;
+
+ let outcome = llm.stream(chat, tools, session.llm_cancel(), |delta| {
+ if !session.is_current(turn) {
+ return false;
+ }
+ match delta {
+ Delta::Text(text) => {
+ if first_token.is_none() {
+ first_token = Some(llm_started.elapsed());
+ let _ = events.send(Event::ReplyStarted {
+ turn,
+ ttft: llm_started.elapsed(),
+ });
+ }
+ let _ = events.send(Event::ReplyDelta {
+ turn,
+ text: text.clone(),
+ });
+ spoken.push_str(text);
+ // Aquí está el solape: cada frase cerrada sale hacia el
+ // sintetizador sin esperar al resto de la respuesta.
+ for sentence in splitter.push(text) {
+ let index = splitter.emitted() - 1;
+ let _ = events.send(Event::Sentence {
+ turn,
+ index,
+ text: sentence.clone(),
+ });
+ if speak
+ .send(SpeakJob {
+ turn,
+ index,
+ text: sentence,
+ turn_started,
+ })
+ .is_err()
+ {
+ return false;
+ }
+ }
+ true
+ }
+ Delta::ToolCalls(_) => true,
+ }
+ });
+
+ if let Some(ttft) = first_token {
+ timer.record(Stage::LlmFirstToken, ttft);
+ timer.record(Stage::LlmRest, llm_started.elapsed().saturating_sub(ttft));
+ }
+
+ let outcome = match outcome {
+ Ok(outcome) => outcome,
+ Err(err) => {
+ let _ = events.send(Event::Failed {
+ turn,
+ message: err.to_string(),
+ });
+ return;
+ }
+ };
+
+ if !session.is_current(turn) {
+ return;
+ }
+
+ if outcome.tool_calls.is_empty() {
+ if let Some(rest) = splitter.flush() {
+ let index = splitter.emitted() - 1;
+ let _ = events.send(Event::Sentence {
+ turn,
+ index,
+ text: rest.clone(),
+ });
+ let _ = speak.send(SpeakJob {
+ turn,
+ index,
+ text: rest,
+ turn_started,
+ });
+ }
+ timer.sentences = splitter.emitted();
+ chat.push(Message::assistant(outcome.text.clone()));
+ // El turno siguiente vuelve a empezar decidiendo.
+ if prompts.two_phase {
+ chat.set_system(&prompts.deciding);
+ }
+ let _ = events.send(Event::ReplyDone {
+ turn,
+ text: outcome.text,
+ });
+ return;
+ }
+
+ // El modelo ha pedido herramientas: se ejecutan, se le devuelve el
+ // resultado y se le vuelve a preguntar.
+ if round == config.llm.max_tool_rounds {
+ let _ = events.send(Event::Warning {
+ turn,
+ message: format!(
+ "el modelo siguió pidiendo herramientas tras {} vueltas; se corta",
+ config.llm.max_tool_rounds
+ ),
+ });
+ return;
+ }
+
+ let tools = tools.expect("no puede haber llamadas sin herramientas registradas");
+ chat.push(Message::tool_request(
+ outcome.text.clone(),
+ outcome.tool_calls.clone(),
+ ));
+ let tools_started = Instant::now();
+ for call in &outcome.tool_calls {
+ let _ = events.send(Event::ToolRequested {
+ turn,
+ name: call.name.clone(),
+ arguments: call.arguments.clone(),
+ });
+ let result = tools.dispatch(call);
+ let _ = events.send(Event::ToolFinished {
+ turn,
+ name: result.name.clone(),
+ ok: result.ok,
+ output: result.output.clone(),
+ took: result.took,
+ });
+ chat.push(Message::tool_result(&result));
+ timer.tool_calls += 1;
+ }
+ timer.record(Stage::Tools, tools_started.elapsed());
+
+ // Con el resultado ya en la conversación, la siguiente vuelta sólo
+ // tiene que redactar: es el momento de recuperar la instrucción de
+ // voz, que en la pasada anterior habría impedido la llamada.
+ if prompts.two_phase {
+ chat.set_system(&prompts.speaking);
+ }
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Síntesis: frases -> altavoz
+// ---------------------------------------------------------------------------
+
+fn run_speech(
+ session: Session,
+ tts: TtsClient,
+ jobs: Receiver<SpeakJob>,
+ playback: PlaybackHandle,
+ events: Sender<Event>,
+) {
+ // Un `Select` en vez de `recv()` a secas para poder despertar
+ // periódicamente y bajar la bandera de «hablando» cuando el anillo se
+ // vacía: si no, el micrófono seguiría cerrado tras la última frase.
+ let mut select = Select::new();
+ let job_index = select.recv(&jobs);
+ let mut speaking_turn: Option<TurnId> = None;
+
+ loop {
+ let job = match select.select_timeout(Duration::from_millis(100)) {
+ Ok(op) if op.index() == job_index => match op.recv(&jobs) {
+ Ok(job) => Some(job),
+ Err(_) => break,
+ },
+ Ok(_) => None,
+ Err(_) => None,
+ };
+
+ let Some(job) = job else {
+ // Sin trabajo: si ya no queda audio, el turno ha terminado de sonar.
+ if let Some(turn) = speaking_turn {
+ if !playback.is_active() || playback.queued_secs() <= 0.0 {
+ session.set_speaking(false);
+ speaking_turn = None;
+ let _ = events.send(Event::AudioFinished { turn });
+ }
+ }
+ if session.is_stopping() {
+ break;
+ }
+ continue;
+ };
+
+ // Una frase de un turno ya superado no debe llegar a oírse.
+ if !session.is_current(job.turn) {
+ tracing::debug!(target: "tts", turno = job.turn.0, "frase obsoleta, descartada");
+ continue;
+ }
+
+ session.set_speaking(true);
+ speaking_turn = Some(job.turn);
+ if job.index == 0 {
+ playback.reset_played();
+ }
+
+ let turn = job.turn;
+ let first_of_turn = job.index == 0;
+ let mut announced = false;
+ let result = tts.speak(&job.text, session.tts_cancel(), |samples| {
+ if !session.is_current(turn) {
+ return false;
+ }
+ playback.push_tts(samples);
+ if first_of_turn && !announced && playback.has_played() {
+ announced = true;
+ let _ = events.send(Event::AudioStarted {
+ turn,
+ latency: job.turn_started.elapsed(),
+ });
+ }
+ true
+ });
+
+ match result {
+ Ok(outcome) => {
+ if outcome.cancelled {
+ let _ = events.send(Event::Interrupted {
+ turn,
+ reason: InterruptReason::UserSpoke,
+ });
+ continue;
+ }
+ // La cuenta del primer audio puede no haberse dado si el
+ // anillo aún no había servido nada cuando llegó el bloque.
+ if first_of_turn && !announced {
+ let _ = events.send(Event::AudioStarted {
+ turn,
+ latency: job.turn_started.elapsed(),
+ });
+ }
+ if outcome.rtf() > 1.0 {
+ tracing::warn!(
+ target: "tts",
+ rtf = outcome.rtf(),
+ "la síntesis va por detrás del tiempo real; la voz se cortará a trozos"
+ );
+ }
+ }
+ Err(err) => {
+ let _ = events.send(Event::Failed {
+ turn,
+ message: err.to_string(),
+ });
+ }
+ }
+ }
+
+ playback.stop();
+ session.set_speaking(false);
+}
diff --git a/crates/asist-app/src/render.rs b/crates/asist-app/src/render.rs
new file mode 100644
index 0000000..7fd1e86
--- /dev/null
+++ b/crates/asist-app/src/render.rs
@@ -0,0 +1,258 @@
+//! Presentación en el terminal.
+//!
+//! Una sola línea viva que se reescribe con la transcripción provisional, y
+//! líneas fijas para lo que ya es definitivo. La distinción importa: ver que
+//! el asistente te está oyendo *mientras* hablas es lo que hace que la espera
+//! se note menos de lo que dura.
+
+use std::io::Write;
+use std::time::Duration;
+
+use asist_core::event::{Event, InterruptReason};
+
+const RESET: &str = "\x1b[0m";
+const DIM: &str = "\x1b[2m";
+const BOLD: &str = "\x1b[1m";
+const CYAN: &str = "\x1b[36m";
+const GREEN: &str = "\x1b[32m";
+const YELLOW: &str = "\x1b[33m";
+const RED: &str = "\x1b[31m";
+
+pub struct Renderer {
+ width: usize,
+ line_open: bool,
+ color: bool,
+ show_partials: bool,
+ reply: String,
+}
+
+impl Renderer {
+ pub fn new(show_partials: bool) -> Self {
+ Self {
+ width: terminal_width(),
+ line_open: false,
+ // Sin terminal interactivo, los códigos de color sólo ensucian
+ // el fichero de registro.
+ color: std::env::var_os("NO_COLOR").is_none() && is_tty(),
+ show_partials,
+ reply: String::new(),
+ }
+ }
+
+ fn paint(&self, code: &str, text: &str) -> String {
+ if self.color {
+ format!("{code}{text}{RESET}")
+ } else {
+ text.to_string()
+ }
+ }
+
+ /// Borra la línea viva para poder escribir encima algo definitivo.
+ fn close_line(&mut self) {
+ if self.line_open {
+ print!("\r\x1b[K");
+ self.line_open = false;
+ }
+ }
+
+ fn live(&mut self, text: &str) {
+ let mut shown: String = text.chars().collect();
+ if shown.chars().count() > self.width.saturating_sub(4) {
+ let keep = self.width.saturating_sub(7);
+ let skip = shown.chars().count() - keep;
+ shown = format!("…{}", shown.chars().skip(skip).collect::<String>());
+ }
+ print!("\r\x1b[K{shown}");
+ let _ = std::io::stdout().flush();
+ self.line_open = true;
+ }
+
+ pub fn apply(&mut self, event: &Event) {
+ match event {
+ Event::SpeechStarted { .. } => {
+ self.reply.clear();
+ if self.show_partials {
+ self.live(&self.paint(DIM, "escuchando…"));
+ }
+ }
+ Event::Partial {
+ committed,
+ volatile,
+ ..
+ } => {
+ if !self.show_partials {
+ return;
+ }
+ let line = format!(
+ "{} {}",
+ self.paint(DIM, committed),
+ self.paint(DIM, volatile)
+ );
+ self.live(&line);
+ }
+ Event::Transcript {
+ text,
+ audio_secs,
+ decode,
+ ..
+ } => {
+ self.close_line();
+ println!(
+ "{} {} {}",
+ self.paint(BOLD, "tú >"),
+ text,
+ self.paint(
+ DIM,
+ &format!("({audio_secs:.1} s, asr {} ms)", decode.as_millis())
+ )
+ );
+ }
+ Event::Discarded { .. } => {
+ self.close_line();
+ }
+ Event::ReplyStarted { ttft, .. } => {
+ self.close_line();
+ print!("{} ", self.paint(CYAN, "asistente >"));
+ let _ = std::io::stdout().flush();
+ tracing::debug!(target: "render", ttft_ms = ttft.as_millis(), "primer token");
+ }
+ Event::ReplyDelta { text, .. } => {
+ self.reply.push_str(text);
+ print!("{text}");
+ let _ = std::io::stdout().flush();
+ }
+ Event::ReplyDone { .. } => {
+ println!();
+ }
+ Event::ToolRequested {
+ name, arguments, ..
+ } => {
+ self.close_line();
+ println!(
+ "{} {name} {}",
+ self.paint(YELLOW, "herramienta >"),
+ self.paint(DIM, &short(arguments, 120))
+ );
+ }
+ Event::ToolFinished {
+ name,
+ ok,
+ output,
+ took,
+ ..
+ } => {
+ let mark = if *ok {
+ self.paint(GREEN, "ok")
+ } else {
+ self.paint(RED, "error")
+ };
+ println!(
+ "{} {name} {mark} {}",
+ self.paint(YELLOW, "herramienta <"),
+ self.paint(
+ DIM,
+ &format!("{} · {} ms", short(output, 120), took.as_millis())
+ )
+ );
+ }
+ Event::AudioStarted { latency, .. } => {
+ tracing::info!(
+ target: "latencia",
+ ms = latency.as_millis(),
+ "primer audio (latencia percibida)"
+ );
+ if self.color {
+ println!(
+ "{}",
+ self.paint(DIM, &format!(" ▸ voz en {}", human(*latency)))
+ );
+ }
+ }
+ Event::Sentence { index, text, .. } => {
+ tracing::debug!(target: "render", frase = index, %text, "a sintetizar");
+ }
+ Event::AudioFinished { .. } => {}
+ Event::Interrupted { reason, .. } => {
+ self.close_line();
+ let why = match reason {
+ InterruptReason::UserSpoke => "te has adelantado",
+ InterruptReason::Requested => "cortado",
+ };
+ println!("{}", self.paint(YELLOW, &format!(" ▪ {why}")));
+ }
+ Event::Warning { message, .. } => {
+ self.close_line();
+ println!("{} {message}", self.paint(YELLOW, "aviso >"));
+ }
+ Event::Failed { message, .. } => {
+ self.close_line();
+ println!("{} {message}", self.paint(RED, "error >"));
+ }
+ Event::Shutdown => {
+ self.close_line();
+ }
+ }
+ }
+
+ pub fn finish(&mut self) {
+ self.close_line();
+ let _ = std::io::stdout().flush();
+ }
+}
+
+fn short(text: &str, max: usize) -> String {
+ let text = text.replace('\n', " ");
+ if text.chars().count() <= max {
+ return text;
+ }
+ text.chars().take(max).collect::<String>() + "…"
+}
+
+fn human(d: Duration) -> String {
+ if d.as_millis() < 1000 {
+ format!("{} ms", d.as_millis())
+ } else {
+ format!("{:.1} s", d.as_secs_f32())
+ }
+}
+
+fn terminal_width() -> usize {
+ std::env::var("COLUMNS")
+ .ok()
+ .and_then(|v| v.parse().ok())
+ .unwrap_or(100)
+}
+
+fn is_tty() -> bool {
+ #[cfg(unix)]
+ {
+ unsafe extern "C" {
+ fn isatty(fd: i32) -> i32;
+ }
+ unsafe { isatty(1) == 1 }
+ }
+ #[cfg(not(unix))]
+ true
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn el_texto_largo_se_recorta_con_puntos_suspensivos() {
+ assert_eq!(short("abcdefghij", 5), "abcde…");
+ assert_eq!(short("abc", 5), "abc");
+ }
+
+ #[test]
+ fn los_saltos_de_linea_no_rompen_la_linea_viva() {
+ assert_eq!(short("a\nb", 10), "a b");
+ }
+
+ #[test]
+ fn las_duraciones_se_leen_en_la_unidad_adecuada() {
+ assert_eq!(human(Duration::from_millis(430)), "430 ms");
+ assert_eq!(human(Duration::from_millis(2500)), "2.5 s");
+ }
+}
diff --git a/crates/asist-app/src/session.rs b/crates/asist-app/src/session.rs
new file mode 100644
index 0000000..b74a4f3
--- /dev/null
+++ b/crates/asist-app/src/session.rs
@@ -0,0 +1,160 @@
+//! Estado compartido entre los hilos del pipeline.
+//!
+//! Sólo hay dos cosas que de verdad tienen que compartirse: qué turno es el
+//! vigente, y las banderas que permiten cortar lo que está en marcha. Todo lo
+//! demás viaja por canales. Mantener esta superficie pequeña es lo que hace
+//! que la interrupción sea razonable de seguir: cortar es subir el turno y
+//! levantar dos banderas.
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::Arc;
+
+use asist_core::event::TurnId;
+use asist_core::http::Cancel;
+
+#[derive(Clone)]
+pub struct Session {
+ inner: Arc<Inner>,
+}
+
+struct Inner {
+ /// Turno que se está atendiendo. Cualquier trabajo de un turno anterior
+ /// que aparezca por un canal es basura y se tira.
+ current: AtomicU64,
+ /// El asistente está hablando (o a punto de hacerlo).
+ speaking: AtomicBool,
+ /// Cierre solicitado.
+ stopping: AtomicBool,
+ /// Corta la respuesta del modelo en curso.
+ llm: Cancel,
+ /// Corta la síntesis en curso.
+ tts: Cancel,
+}
+
+impl Default for Session {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+impl Session {
+ pub fn new() -> Self {
+ Self {
+ inner: Arc::new(Inner {
+ current: AtomicU64::new(0),
+ speaking: AtomicBool::new(false),
+ stopping: AtomicBool::new(false),
+ llm: Cancel::new(),
+ tts: Cancel::new(),
+ }),
+ }
+ }
+
+ pub fn current(&self) -> TurnId {
+ TurnId(self.inner.current.load(Ordering::SeqCst))
+ }
+
+ /// Abre un turno nuevo y devuelve su identificador.
+ pub fn begin_turn(&self) -> TurnId {
+ let id = TurnId(self.inner.current.fetch_add(1, Ordering::SeqCst) + 1);
+ self.inner.llm.reset();
+ self.inner.tts.reset();
+ id
+ }
+
+ /// ¿Sigue siendo `turn` el turno vigente?
+ ///
+ /// Lo consultan los hilos antes de gastar trabajo: una frase que
+ /// pertenece a un turno ya superado no debe sintetizarse ni oírse.
+ pub fn is_current(&self, turn: TurnId) -> bool {
+ turn == self.current()
+ }
+
+ /// Corta todo lo que esté en marcha para el turno actual.
+ pub fn interrupt(&self) {
+ self.inner.llm.cancel();
+ self.inner.tts.cancel();
+ self.inner.speaking.store(false, Ordering::SeqCst);
+ }
+
+ pub fn llm_cancel(&self) -> &Cancel {
+ &self.inner.llm
+ }
+
+ pub fn tts_cancel(&self) -> &Cancel {
+ &self.inner.tts
+ }
+
+ pub fn set_speaking(&self, speaking: bool) {
+ self.inner.speaking.store(speaking, Ordering::SeqCst);
+ }
+
+ pub fn is_speaking(&self) -> bool {
+ self.inner.speaking.load(Ordering::SeqCst)
+ }
+
+ pub fn request_stop(&self) {
+ self.inner.stopping.store(true, Ordering::SeqCst);
+ self.interrupt();
+ }
+
+ pub fn is_stopping(&self) -> bool {
+ self.inner.stopping.load(Ordering::SeqCst)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn cada_turno_recibe_un_identificador_creciente() {
+ let session = Session::new();
+ assert_eq!(session.begin_turn(), TurnId(1));
+ assert_eq!(session.begin_turn(), TurnId(2));
+ assert_eq!(session.current(), TurnId(2));
+ }
+
+ #[test]
+ fn el_trabajo_de_un_turno_viejo_deja_de_ser_vigente() {
+ let session = Session::new();
+ let primero = session.begin_turn();
+ session.begin_turn();
+ assert!(
+ !session.is_current(primero),
+ "el turno viejo debe descartarse"
+ );
+ }
+
+ #[test]
+ fn abrir_turno_rearma_las_cancelaciones() {
+ let session = Session::new();
+ session.begin_turn();
+ session.interrupt();
+ assert!(session.llm_cancel().is_cancelled());
+
+ session.begin_turn();
+ assert!(
+ !session.llm_cancel().is_cancelled(),
+ "un turno nuevo no puede heredar la cancelación del anterior"
+ );
+ }
+
+ #[test]
+ fn interrumpir_calla_y_cancela_las_dos_etapas() {
+ let session = Session::new();
+ session.begin_turn();
+ session.set_speaking(true);
+ session.interrupt();
+ assert!(session.tts_cancel().is_cancelled());
+ assert!(!session.is_speaking());
+ }
+
+ #[test]
+ fn pedir_el_cierre_tambien_interrumpe() {
+ let session = Session::new();
+ session.request_stop();
+ assert!(session.is_stopping());
+ assert!(session.llm_cancel().is_cancelled());
+ }
+}
diff --git a/crates/asist-app/src/supervisor.rs b/crates/asist-app/src/supervisor.rs
new file mode 100644
index 0000000..17360da
--- /dev/null
+++ b/crates/asist-app/src/supervisor.rs
@@ -0,0 +1,228 @@
+//! Arranque y parada de los servidores locales.
+//!
+//! El asistente puede levantar `llama-server` y `tts-server` él mismo, para
+//! que ponerlo en marcha sea un solo comando. Los procesos se lanzan en su
+//! propio grupo y se paran con SIGTERM antes de recurrir a SIGKILL: matar en
+//! seco a llama-server deja la GPU ocupada hasta que el driver la recupera.
+
+use std::path::Path;
+use std::process::{Child, Command, Stdio};
+use std::time::{Duration, Instant};
+
+use asist_core::config::{Config, LlamaProcess, TtsProcess};
+use asist_core::error::{Error, Result};
+
+pub struct Supervisor {
+ children: Vec<Managed>,
+ log_dir: std::path::PathBuf,
+}
+
+struct Managed {
+ name: &'static str,
+ child: Child,
+}
+
+impl Supervisor {
+ pub fn new(log_dir: impl AsRef<Path>) -> Result<Self> {
+ let log_dir = log_dir.as_ref().to_path_buf();
+ std::fs::create_dir_all(&log_dir)?;
+ Ok(Self {
+ children: Vec::new(),
+ log_dir,
+ })
+ }
+
+ /// Lanza los servidores que la configuración pida y que no estén ya arriba.
+ ///
+ /// Reutilizar uno que ya escucha es deliberado: durante el desarrollo se
+ /// reinicia el asistente muchas veces y volver a cargar los modelos
+ /// cuesta más de un minuto.
+ pub fn start(&mut self, config: &Config, llm_up: bool, tts_up: bool) -> Result<()> {
+ if !config.supervisor.manage {
+ return Ok(());
+ }
+ if llm_up {
+ tracing::info!(target: "supervisor", "llama-server ya está escuchando, se reutiliza");
+ } else {
+ let command = llama_command(&config.supervisor.llama, config)?;
+ self.spawn("llama-server", command)?;
+ }
+ if tts_up {
+ tracing::info!(target: "supervisor", "tts-server ya está escuchando, se reutiliza");
+ } else {
+ let command = tts_command(&config.supervisor.tts, config)?;
+ self.spawn("tts-server", command)?;
+ }
+ Ok(())
+ }
+
+ fn spawn(&mut self, name: &'static str, mut command: Command) -> Result<()> {
+ let log_path = self.log_dir.join(format!("{name}.log"));
+ let log = std::fs::File::create(&log_path)?;
+ let errors = log.try_clone()?;
+
+ // La salida va al fichero: los modelos escupen cientos de líneas y
+ // taparían la transcripción en pantalla. Cuando algo falla, el
+ // mensaje de error apunta aquí.
+ command
+ .stdin(Stdio::null())
+ .stdout(Stdio::from(log))
+ .stderr(Stdio::from(errors));
+
+ let child = command.spawn().map_err(|e| {
+ Error::Config(format!(
+ "no se pudo lanzar {name} ({:?}): {e}",
+ command.get_program()
+ ))
+ })?;
+ tracing::info!(
+ target: "supervisor",
+ proceso = name,
+ pid = child.id(),
+ registro = %log_path.display(),
+ "lanzado"
+ );
+ self.children.push(Managed { name, child });
+ Ok(())
+ }
+
+ /// Comprueba si alguno se ha muerto solo, y devuelve su nombre.
+ pub fn crashed(&mut self) -> Option<(&'static str, Option<i32>)> {
+ for managed in &mut self.children {
+ if let Ok(Some(status)) = managed.child.try_wait() {
+ return Some((managed.name, status.code()));
+ }
+ }
+ None
+ }
+
+ pub fn log_path(&self, name: &str) -> std::path::PathBuf {
+ self.log_dir.join(format!("{name}.log"))
+ }
+
+ /// Para todo lo lanzado. SIGTERM primero para que liberen la GPU.
+ pub fn shutdown(&mut self) {
+ for managed in &mut self.children {
+ terminate(&mut managed.child, managed.name);
+ }
+ self.children.clear();
+ }
+}
+
+impl Drop for Supervisor {
+ fn drop(&mut self) {
+ self.shutdown();
+ }
+}
+
+fn terminate(child: &mut Child, name: &str) {
+ if matches!(child.try_wait(), Ok(Some(_))) {
+ return;
+ }
+ // SIGTERM directo: `Child::kill` manda SIGKILL, que no da al servidor
+ // ocasión de soltar la memoria de la GPU.
+ #[cfg(unix)]
+ unsafe {
+ libc_kill(child.id() as i32, 15);
+ }
+ #[cfg(not(unix))]
+ let _ = child.kill();
+
+ let deadline = Instant::now() + Duration::from_secs(10);
+ while Instant::now() < deadline {
+ match child.try_wait() {
+ Ok(Some(_)) => {
+ tracing::info!(target: "supervisor", proceso = name, "detenido");
+ return;
+ }
+ Ok(None) => std::thread::sleep(Duration::from_millis(100)),
+ Err(_) => break,
+ }
+ }
+ tracing::warn!(target: "supervisor", proceso = name, "no respondió a SIGTERM, se fuerza");
+ let _ = child.kill();
+ let _ = child.wait();
+}
+
+#[cfg(unix)]
+unsafe fn libc_kill(pid: i32, signal: i32) {
+ // Se declara aquí el único símbolo de libc que hace falta, en vez de
+ // arrastrar el crate entero por una llamada.
+ unsafe extern "C" {
+ fn kill(pid: i32, sig: i32) -> i32;
+ }
+ unsafe {
+ kill(pid, signal);
+ }
+}
+
+fn require(path: &Path, what: &str) -> Result<()> {
+ if path.exists() {
+ return Ok(());
+ }
+ Err(Error::Config(format!(
+ "falta {what}: {}. Ejecuta scripts/bootstrap.sh para compilar los \
+ motores y enlazar los modelos",
+ path.display()
+ )))
+}
+
+fn llama_command(process: &LlamaProcess, config: &Config) -> Result<Command> {
+ require(&process.binary, "el binario de llama-server")?;
+ require(&process.model, "el modelo del LLM")?;
+
+ let mut command = Command::new(&process.binary);
+ command
+ .arg("--model")
+ .arg(&process.model)
+ .arg("--host")
+ .arg(&config.llm.host)
+ .arg("--port")
+ .arg(config.llm.port.to_string());
+
+ if process.mmproj.exists() {
+ command.arg("--mmproj").arg(&process.mmproj);
+ }
+ // Sin esto, la plantilla del modelo abre <think> y no lo cierra nunca: el
+ // asistente se pasa entre 7 y 9 s razonando antes de la primera palabra.
+ if process.chat_template.exists() {
+ command
+ .arg("--jinja")
+ .arg("--chat-template-file")
+ .arg(&process.chat_template);
+ } else {
+ tracing::warn!(
+ target: "supervisor",
+ ruta = %process.chat_template.display(),
+ "no está la plantilla sin razonamiento: el modelo tardará varios \
+ segundos en empezar a hablar"
+ );
+ }
+ command.args(&process.extra_args);
+ Ok(command)
+}
+
+fn tts_command(process: &TtsProcess, config: &Config) -> Result<Command> {
+ require(&process.binary, "el binario de tts-server")?;
+ require(&process.model, "el modelo hablante del TTS")?;
+ require(&process.codec, "el codec del TTS")?;
+
+ let mut command = Command::new(&process.binary);
+ command
+ .arg("--model")
+ .arg(&process.model)
+ .arg("--codec")
+ .arg(&process.codec)
+ .arg("--host")
+ .arg(&config.tts.host)
+ .arg("--port")
+ .arg(config.tts.port.to_string())
+ .arg("--lang")
+ .arg(&config.tts.language)
+ // El ajuste con más efecto de todo el sistema: de fábrica son 24 s, que
+ // en la práctica significa no devolver nada hasta terminar la frase.
+ .arg("--codec-chunk-dur")
+ .arg(process.codec_chunk_dur.to_string());
+ command.args(&process.extra_args);
+ Ok(command)
+}
diff --git a/crates/asist-app/tests/integracion.rs b/crates/asist-app/tests/integracion.rs
new file mode 100644
index 0000000..91a074a
--- /dev/null
+++ b/crates/asist-app/tests/integracion.rs
@@ -0,0 +1,266 @@
+//! Pruebas contra los servidores de verdad.
+//!
+//! Se saltan solas cuando no hay nada escuchando, para que `cargo test` siga
+//! siendo útil sin 5 GB de modelos cargados. Con los servidores arriba
+//! comprueban lo que las pruebas unitarias no pueden: que el protocolo que se
+//! ha escrito es el que los servidores hablan, y que las latencias siguen
+//! donde se midieron.
+//!
+//! Para ejecutarlas: scripts/servidores.sh arrancar && cargo test -- --ignored
+
+use std::path::PathBuf;
+use std::sync::{Mutex, MutexGuard, OnceLock};
+use std::time::{Duration, Instant};
+
+use asist_core::config::Config;
+use asist_core::http::Cancel;
+use asist_core::tools::ToolRegistry;
+use asist_llm::chat::Conversation;
+use asist_llm::{Delta, LlmClient, Message};
+use asist_tts::TtsClient;
+
+/// Las pruebas se turnan la GPU.
+///
+/// Los dos servidores comparten una tarjeta de 4 GB, y medido: con la prueba
+/// de síntesis corriendo a la vez, el primer token del LLM pasa de ~0,5 s a
+/// ~5 s. En paralelo esto no mide latencia, mide quién llegó primero. El
+/// pipeline de verdad no tiene el problema porque la síntesis no arranca
+/// hasta que el modelo cierra su primera frase.
+fn en_exclusiva() -> MutexGuard<'static, ()> {
+ static GPU: OnceLock<Mutex<()>> = OnceLock::new();
+ GPU.get_or_init(|| Mutex::new(()))
+ .lock()
+ .unwrap_or_else(|e| e.into_inner())
+}
+
+fn config() -> Config {
+ let path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../config/asistente.toml");
+ Config::load(path).expect("no se pudo cargar la configuración")
+}
+
+/// Devuelve los clientes, o `None` si los servidores no están arriba.
+fn clientes() -> Option<(Config, LlmClient, TtsClient)> {
+ let config = config();
+ let llm = LlmClient::new(config.llm_authority(), &config.llm);
+ let tts = TtsClient::new(config.tts_authority(), &config.tts);
+ if !llm.healthy() || !tts.healthy() {
+ eprintln!("servidores no disponibles; prueba omitida");
+ return None;
+ }
+ Some((config, llm, tts))
+}
+
+#[test]
+fn el_llm_responde_en_streaming_sin_razonar_en_voz_alta() {
+ let _gpu = en_exclusiva();
+ let Some((config, llm, _)) = clientes() else {
+ return;
+ };
+
+ let mut chat = Conversation::new(&config.general.system_prompt, 4);
+ chat.push(Message::user("Saluda en una frase corta."));
+
+ let started = Instant::now();
+ let mut ttft = None;
+ let outcome = llm
+ .stream(&chat, None, &Cancel::new(), |delta| {
+ if let Delta::Text(_) = delta {
+ ttft.get_or_insert_with(|| started.elapsed());
+ }
+ true
+ })
+ .expect("la petición al LLM falló");
+
+ assert!(!outcome.text.trim().is_empty(), "respuesta vacía");
+ // La plantilla con <think> sin cerrar deja esto en 7-9 s. Si esta prueba
+ // se cae, casi seguro que llama-server arrancó sin --chat-template-file.
+ let ttft = ttft.expect("no llegó ningún fragmento con texto");
+ assert!(
+ ttft < Duration::from_secs(3),
+ "el primer token tardó {ttft:?}: ¿arrancó llama-server con la plantilla sin razonamiento?"
+ );
+ assert!(
+ !outcome.text.contains("<think>"),
+ "el razonamiento se está colando en la respuesta: {}",
+ outcome.text
+ );
+}
+
+#[test]
+fn el_llm_puede_pedir_una_herramienta() {
+ let _gpu = en_exclusiva();
+ let Some((config, llm, _)) = clientes() else {
+ return;
+ };
+
+ let tools = ToolRegistry::from_config(&config.tools);
+ let mut chat = Conversation::new(
+ "Eres un asistente. Usa las herramientas disponibles cuando hagan falta.",
+ 4,
+ );
+ chat.push(Message::user(
+ "¿Qué hora es exactamente? Usa la herramienta.",
+ ));
+
+ let outcome = llm
+ .stream(&chat, Some(&tools), &Cancel::new(), |_| true)
+ .expect("la petición al LLM falló");
+
+ if outcome.tool_calls.is_empty() {
+ // Un modelo de 2B no siempre acierta a llamar; lo que se comprueba es
+ // que el ida y vuelta funciona, no que el modelo sea listo.
+ eprintln!("el modelo no pidió herramienta: {}", outcome.text);
+ return;
+ }
+ let call = &outcome.tool_calls[0];
+ assert_eq!(call.name, "hora_actual");
+ let result = tools.dispatch(call);
+ assert!(result.ok, "la herramienta falló: {}", result.output);
+ assert!(!result.output.trim().is_empty());
+}
+
+#[test]
+fn la_sintesis_empieza_a_sonar_antes_de_terminar() {
+ let _gpu = en_exclusiva();
+ let Some((config, _, tts)) = clientes() else {
+ return;
+ };
+
+ if let Some(reference) = &config.tts.reference {
+ tts.register_voice(reference)
+ .expect("no se registró la voz");
+ }
+ // Sin precalentar, la primera síntesis carga los grafos y mide el arranque
+ // del servidor en vez del régimen normal.
+ tts.warmup().expect("falló el precalentado");
+
+ let mut bloques = 0usize;
+ let outcome = tts
+ .speak(
+ "Hola, esto es una prueba de latencia del sintetizador de voz.",
+ &Cancel::new(),
+ |samples| {
+ if !samples.is_empty() {
+ bloques += 1;
+ }
+ true
+ },
+ )
+ .expect("la síntesis falló");
+
+ assert!(outcome.samples > 0, "no se recibió audio");
+ assert!(
+ bloques > 1,
+ "el audio llegó de una sola vez ({bloques} bloque): revisa --codec-chunk-dur, \
+ que de fábrica son 24 s y bloquean el streaming"
+ );
+ let ttfb = outcome.ttfb.expect("sin marca de primer bloque");
+ assert!(
+ ttfb < Duration::from_secs(2),
+ "el primer audio tardó {ttfb:?}; con --codec-chunk-dur 1.0 se midió 585 ms"
+ );
+ eprintln!(
+ "ttfb={:?} audio={:.2}s rtf={:.2}",
+ ttfb,
+ outcome.audio_secs(),
+ outcome.rtf()
+ );
+}
+
+#[test]
+fn una_sintesis_se_puede_cortar_a_media_frase() {
+ let _gpu = en_exclusiva();
+ let Some((config, _, tts)) = clientes() else {
+ return;
+ };
+ if let Some(reference) = &config.tts.reference {
+ let _ = tts.register_voice(reference);
+ }
+
+ // Es la operación que sostiene el barge-in: si no se pudiera cortar, el
+ // asistente seguiría hablando encima del usuario hasta acabar la frase.
+ let cancel = Cancel::new();
+ let mut recibidos = 0usize;
+ let outcome = tts
+ .speak(
+ "Esta es una frase larga que no debería llegar a escucharse entera \
+ porque se va a cortar en cuanto empiece a sonar el primer bloque.",
+ &cancel,
+ |samples| {
+ recibidos += samples.len();
+ // Cortar en el primer bloque.
+ false
+ },
+ )
+ .expect("la síntesis falló");
+
+ assert!(outcome.cancelled, "debió quedar marcada como cancelada");
+ assert!(
+ outcome.audio_secs() < 3.0,
+ "se recibieron {:.1} s de audio: el corte no surtió efecto",
+ outcome.audio_secs()
+ );
+}
+
+#[test]
+fn la_voz_clonada_queda_registrada() {
+ let _gpu = en_exclusiva();
+ let Some((config, _, tts)) = clientes() else {
+ return;
+ };
+ let Some(reference) = &config.tts.reference else {
+ eprintln!("sin voz de referencia configurada; prueba omitida");
+ return;
+ };
+ tts.register_voice(reference)
+ .expect("no se registró la voz");
+ let voces = tts.voices().expect("no se pudieron listar las voces");
+ assert!(
+ voces.contains(&reference.name),
+ "«{}» no aparece entre {voces:?}",
+ reference.name
+ );
+}
+
+#[test]
+#[ignore = "carga el modelo de ASR (~200 MB) y decodifica; lento"]
+fn el_asr_transcribe_lo_que_sintetiza_el_tts() {
+ let _gpu = en_exclusiva();
+ // El bucle completo sin micrófono: se sintetiza una frase conocida y se
+ // comprueba que el reconocedor la recupera. Es la única prueba que ejerce
+ // ASR y TTS contra el mismo audio.
+ let Some((config, _, tts)) = clientes() else {
+ return;
+ };
+ if let Some(reference) = &config.tts.reference {
+ let _ = tts.register_voice(reference);
+ }
+
+ let frase = "hola qué tal estás hoy";
+ let mut audio: Vec<f32> = Vec::new();
+ tts.speak(frase, &Cancel::new(), |samples| {
+ audio.extend_from_slice(samples);
+ true
+ })
+ .expect("la síntesis falló");
+ assert!(!audio.is_empty(), "no se generó audio");
+
+ let recognizer =
+ asist_asr::Recognizer::load(&config.asr).expect("no se pudo cargar el modelo de ASR");
+ let texto = recognizer
+ .transcribe(&audio, asist_tts::SAMPLE_RATE)
+ .expect("la transcripción falló")
+ .to_lowercase();
+
+ eprintln!("dicho: «{frase}» / oído: «{texto}»");
+ // No se exige una coincidencia exacta —24 kHz remuestreados a 16 kHz y un
+ // modelo de 180M dan para lo que dan—, sino que reconozca algo.
+ let acertadas = frase
+ .split_whitespace()
+ .filter(|palabra| texto.contains(palabra))
+ .count();
+ assert!(
+ acertadas >= 2,
+ "sólo se reconocieron {acertadas} palabras de «{frase}» en «{texto}»"
+ );
+}
diff --git a/crates/asist-asr/Cargo.toml b/crates/asist-asr/Cargo.toml
new file mode 100644
index 0000000..e9b8345
--- /dev/null
+++ b/crates/asist-asr/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "asist-asr"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+asist-core.workspace = true
+asist-audio.workspace = true
+canary-rs.workspace = true
+# Sólo para fijar la versión; ver la nota del Cargo.toml del workspace.
+ort.workspace = true
+crossbeam-channel.workspace = true
+tracing.workspace = true
diff --git a/crates/asist-asr/src/lib.rs b/crates/asist-asr/src/lib.rs
new file mode 100644
index 0000000..8212ceb
--- /dev/null
+++ b/crates/asist-asr/src/lib.rs
@@ -0,0 +1,401 @@
+//! Reconocimiento de voz sobre Canary (ONNX).
+//!
+//! El hecho que da forma a este crate: **decodificar una ventana cuesta más
+//! que grabarla**. En esta máquina, 6 s de ventana tardan cerca de 800 ms en
+//! decodificarse y sólo avanzan 400 ms de audio. Cualquier diseño que procese
+//! todas las ventanas en orden se va quedando atrás del hablante sin límite.
+//!
+//! La salida es tirar trabajo: el hilo de decodificación vacía su cola entera,
+//! se queda sólo con la ventana más reciente y descarta el resto. La latencia
+//! queda acotada por una decodificación en lugar de crecer sin freno, y lo que
+//! se pierde son transcripciones provisionales que iban a ser sobreescritas.
+
+use std::time::{Duration, Instant};
+
+use crossbeam_channel::{Receiver, Sender};
+
+use asist_core::config::AsrConfig;
+use asist_core::error::{Error, Result};
+use asist_core::event::TurnId;
+
+pub use canary_rs::{Canary, CanarySession, ExecutionConfig, ExecutionProvider, StreamConfig};
+
+/// Trabajo que llega al decodificador.
+#[derive(Debug)]
+pub enum AsrJob {
+ /// Audio nuevo para la ventana deslizante.
+ Window {
+ turn: TurnId,
+ samples: Vec<f32>,
+ at: Instant,
+ },
+ /// Intervención cerrada, para transcribir entera.
+ Utterance {
+ turn: TurnId,
+ samples: Vec<f32>,
+ at: Instant,
+ },
+ /// La intervención no tenía nada: reinicia el estado de la ventana.
+ Reset { turn: TurnId },
+}
+
+/// Lo que el decodificador devuelve.
+#[derive(Debug, Clone)]
+pub enum AsrResult {
+ Partial {
+ turn: TurnId,
+ committed: String,
+ volatile: String,
+ /// Ventanas descartadas por obsoletas antes de esta.
+ dropped: usize,
+ decode: Duration,
+ },
+ Final {
+ turn: TurnId,
+ text: String,
+ audio_secs: f32,
+ decode: Duration,
+ /// Instante en que el usuario dejó de hablar. Es el origen del que se
+ /// mide la latencia percibida, y no puede tomarse aquí: para cuando la
+ /// transcripción está lista ya ha pasado casi un segundo.
+ spoken_at: Instant,
+ },
+ Empty {
+ turn: TurnId,
+ },
+ Error {
+ turn: TurnId,
+ message: String,
+ },
+}
+
+/// Motor cargado y listo para decodificar.
+pub struct Recognizer {
+ model: Canary,
+ config: AsrConfig,
+}
+
+impl Recognizer {
+ /// Carga el modelo desde `config.model_dir`.
+ pub fn load(config: &AsrConfig) -> Result<Self> {
+ if !config.model_dir.is_dir() {
+ return Err(Error::Asr(format!(
+ "no existe la carpeta del modelo: {}. Ejecuta scripts/bootstrap.sh",
+ config.model_dir.display()
+ )));
+ }
+ let started = Instant::now();
+ let model = Canary::from_pretrained(
+ config.model_dir.to_string_lossy().as_ref(),
+ Some(execution_config(config)),
+ )
+ .map_err(|e| Error::Asr(format!("no se pudo cargar Canary: {e}")))?;
+
+ tracing::info!(
+ target: "asr",
+ carpeta = %config.model_dir.display(),
+ proveedor = %config.execution_provider,
+ ms = started.elapsed().as_millis(),
+ "modelo cargado"
+ );
+ Ok(Self {
+ model,
+ config: config.clone(),
+ })
+ }
+
+ /// Sesión suelta para transcribir de una vez (pruebas y comprobaciones).
+ pub fn transcribe(&self, samples: &[f32], sample_rate: u32) -> Result<String> {
+ let mut session = self.model.session();
+ session
+ .transcribe_samples(
+ samples,
+ sample_rate as usize,
+ 1,
+ &self.config.source_lang,
+ &self.config.target_lang,
+ )
+ .map(|r| normalize(&r.text))
+ .map_err(|e| Error::Asr(e.to_string()))
+ }
+
+ /// Bucle del decodificador. Se ejecuta en su propio hilo hasta que se
+ /// cierre `jobs`.
+ pub fn run(self, jobs: Receiver<AsrJob>, out: Sender<AsrResult>) {
+ let mut stream = match self.model.stream(
+ self.config.source_lang.clone(),
+ self.config.target_lang.clone(),
+ stream_config(&self.config),
+ ) {
+ Ok(stream) => stream,
+ Err(err) => {
+ let _ = out.send(AsrResult::Error {
+ turn: TurnId::default(),
+ message: format!("no se pudo abrir el flujo: {err}"),
+ });
+ return;
+ }
+ };
+ let mut session = self.model.session();
+ let mut committed = String::new();
+ let step_samples = (self.config.step * 16_000.0).max(1.0) as usize;
+
+ while let Some(batch) = drain(&jobs) {
+ // Todo el audio que se quedó detrás de un cierre de intervención
+ // pertenece a un turno que ya se va a transcribir entero: gastar
+ // una ventana en él sería trabajo condenado a sobreescribirse.
+ let mut pending: Vec<f32> = Vec::new();
+ let mut pending_turn = TurnId::default();
+ let mut newest = Instant::now();
+ let mut dropped = 0usize;
+
+ for job in batch {
+ match job {
+ AsrJob::Window { turn, samples, at } => {
+ pending_turn = turn;
+ pending.extend_from_slice(&samples);
+ newest = at;
+ }
+ AsrJob::Reset { turn } => {
+ dropped += pending.len() / step_samples;
+ pending.clear();
+ stream.reset();
+ committed.clear();
+ if out.send(AsrResult::Empty { turn }).is_err() {
+ return;
+ }
+ }
+ AsrJob::Utterance { turn, samples, at } => {
+ dropped += pending.len() / step_samples;
+ pending.clear();
+ stream.reset();
+ committed.clear();
+ let result = decode_final(&mut session, &self.config, turn, &samples, at);
+ if out.send(result).is_err() {
+ return;
+ }
+ }
+ }
+ }
+
+ if pending.is_empty() || !self.config.partials {
+ continue;
+ }
+ // Sólo sobrevive la ventana más nueva; lo anterior ya no describe
+ // lo que se está diciendo ahora.
+ dropped += (pending.len() / step_samples).saturating_sub(1);
+
+ let started = Instant::now();
+ let chunks = match stream.push_samples(&pending, 16_000, 1) {
+ Ok(chunks) => chunks,
+ Err(err) => {
+ let _ = out.send(AsrResult::Error {
+ turn: pending_turn,
+ message: err.to_string(),
+ });
+ continue;
+ }
+ };
+ let Some(chunk) = chunks.last() else { continue };
+ if is_degenerate(&chunk.result.text) {
+ continue;
+ }
+
+ append_delta(&mut committed, chunk.delta_text.trim());
+ let volatile = volatile_tail(&committed, chunk.result.text.trim());
+ let decode = started.elapsed();
+ tracing::debug!(
+ target: "asr",
+ turno = pending_turn.0,
+ ms = decode.as_millis(),
+ retraso_ms = newest.elapsed().as_millis(),
+ descartadas = dropped,
+ "ventana"
+ );
+ if out
+ .send(AsrResult::Partial {
+ turn: pending_turn,
+ committed: committed.clone(),
+ volatile,
+ dropped,
+ decode,
+ })
+ .is_err()
+ {
+ return;
+ }
+ }
+ }
+}
+
+fn decode_final(
+ session: &mut CanarySession,
+ config: &AsrConfig,
+ turn: TurnId,
+ samples: &[f32],
+ at: Instant,
+) -> AsrResult {
+ let started = Instant::now();
+ let audio_secs = samples.len() as f32 / 16_000.0;
+ match session.transcribe_samples(samples, 16_000, 1, &config.source_lang, &config.target_lang) {
+ Ok(result) => {
+ let text = normalize(&result.text);
+ let decode = started.elapsed();
+ tracing::debug!(
+ target: "asr",
+ turno = turn.0,
+ ms = decode.as_millis(),
+ audio_s = audio_secs,
+ rtf = decode.as_secs_f32() / audio_secs.max(0.001),
+ retraso_ms = at.elapsed().as_millis(),
+ "transcripción final"
+ );
+ if text.is_empty() {
+ AsrResult::Empty { turn }
+ } else {
+ AsrResult::Final {
+ turn,
+ text,
+ audio_secs,
+ decode,
+ spoken_at: at,
+ }
+ }
+ }
+ Err(err) => AsrResult::Error {
+ turn,
+ message: err.to_string(),
+ },
+ }
+}
+
+fn execution_config(config: &AsrConfig) -> ExecutionConfig {
+ let provider = match config.execution_provider.trim().to_lowercase().as_str() {
+ "cuda" => ExecutionProvider::Cuda,
+ "tensorrt" => ExecutionProvider::TensorRT,
+ "rocm" => ExecutionProvider::ROCm,
+ "openvino" => ExecutionProvider::OpenVINO,
+ "webgpu" => ExecutionProvider::WebGPU,
+ "coreml" => ExecutionProvider::CoreML,
+ "directml" => ExecutionProvider::DirectML,
+ _ => ExecutionProvider::Cpu,
+ };
+ ExecutionConfig::new()
+ .with_execution_provider(provider)
+ .with_threads(config.inter_threads, config.intra_threads)
+}
+
+fn stream_config(config: &AsrConfig) -> StreamConfig {
+ StreamConfig::new()
+ .with_window_duration(config.window)
+ .with_step_duration(config.step)
+ .with_emit_partial(true)
+ .with_pad_partial(false)
+ .with_stability_window(config.stability)
+ // El motivo de todo el diseño: nunca arrastrar una cola de ventanas viejas.
+ .with_max_windows_per_push(1)
+}
+
+/// Recoge de golpe todo lo encolado, bloqueando hasta que llegue lo primero.
+fn drain(jobs: &Receiver<AsrJob>) -> Option<Vec<AsrJob>> {
+ let mut batch = vec![jobs.recv().ok()?];
+ while let Ok(job) = jobs.try_recv() {
+ batch.push(job);
+ }
+ Some(batch)
+}
+
+/// Une el texto estable con el fragmento nuevo respetando los espacios.
+pub fn append_delta(committed: &mut String, delta: &str) {
+ if delta.is_empty() {
+ return;
+ }
+ let needs_space = !committed.is_empty()
+ && !committed.ends_with(' ')
+ && !delta.starts_with(|c: char| c.is_ascii_punctuation());
+ if needs_space {
+ committed.push(' ');
+ }
+ committed.push_str(delta);
+}
+
+/// Parte de la ventana actual que aún no es estable.
+pub fn volatile_tail(committed: &str, window: &str) -> String {
+ // La ventana repite el final de lo ya fijado; lo interesante es lo que
+ // sobra por detrás.
+ match window.rfind(last_words(committed, 3).as_str()) {
+ Some(idx) if !committed.is_empty() => window[idx + last_words(committed, 3).len()..]
+ .trim_start()
+ .to_string(),
+ _ => window.to_string(),
+ }
+}
+
+fn last_words(text: &str, n: usize) -> String {
+ let words: Vec<&str> = text.split_whitespace().collect();
+ words[words.len().saturating_sub(n)..].join(" ")
+}
+
+/// Canary a veces se atasca repitiendo un token cuando la ventana es casi
+/// silencio. Mostrarlo confundiría más que ayudar.
+pub fn is_degenerate(text: &str) -> bool {
+ let words: Vec<&str> = text.split_whitespace().collect();
+ if words.len() < 6 {
+ return false;
+ }
+ let distinct: std::collections::HashSet<&&str> = words.iter().collect();
+ distinct.len() * 4 <= words.len()
+}
+
+/// Arregla el espaciado de la puntuación que a veces deja el decodificador.
+pub fn normalize(text: &str) -> String {
+ let mut out = String::with_capacity(text.len());
+ for c in text.trim().chars() {
+ if matches!(c, ',' | '.' | '!' | '?' | ';' | ':') {
+ while out.ends_with(' ') {
+ out.pop();
+ }
+ }
+ out.push(c);
+ }
+ out
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn el_delta_se_une_con_espacio_salvo_ante_puntuacion() {
+ let mut s = String::from("hola");
+ append_delta(&mut s, "mundo");
+ assert_eq!(s, "hola mundo");
+ append_delta(&mut s, ",");
+ assert_eq!(s, "hola mundo,");
+ append_delta(&mut s, "");
+ assert_eq!(s, "hola mundo,");
+ }
+
+ #[test]
+ fn la_cola_volatil_es_lo_que_sobra_tras_lo_fijado() {
+ assert_eq!(volatile_tail("hola qué tal", "hola qué tal estás"), "estás");
+ }
+
+ #[test]
+ fn sin_texto_fijado_toda_la_ventana_es_volatil() {
+ assert_eq!(volatile_tail("", "hola qué tal"), "hola qué tal");
+ }
+
+ #[test]
+ fn se_detecta_la_repeticion_degenerada() {
+ assert!(is_degenerate("sí sí sí sí sí sí sí sí"));
+ assert!(!is_degenerate("hola qué tal estás hoy amigo"));
+ assert!(!is_degenerate("sí sí"), "una frase corta no es degenerada");
+ }
+
+ #[test]
+ fn la_puntuacion_pierde_el_espacio_de_delante() {
+ assert_eq!(normalize("hola , qué tal ?"), "hola, qué tal?");
+ assert_eq!(normalize(" ya está "), "ya está");
+ }
+}
diff --git a/crates/asist-audio/Cargo.toml b/crates/asist-audio/Cargo.toml
new file mode 100644
index 0000000..b6845fd
--- /dev/null
+++ b/crates/asist-audio/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "asist-audio"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+asist-core.workspace = true
+cpal.workspace = true
+crossbeam-channel.workspace = true
+tracing.workspace = true
diff --git a/crates/asist-audio/src/capture.rs b/crates/asist-audio/src/capture.rs
new file mode 100644
index 0000000..05da992
--- /dev/null
+++ b/crates/asist-audio/src/capture.rs
@@ -0,0 +1,153 @@
+//! Captura desde el micrófono.
+
+use std::time::Instant;
+
+use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
+use cpal::{Sample, SampleFormat, SupportedStreamConfig};
+use crossbeam_channel::Sender;
+
+use asist_core::config::AudioConfig;
+use asist_core::error::{Error, Result};
+
+use crate::{describe, ASR_SAMPLE_RATE};
+
+/// Formato con el que se abrió realmente el dispositivo.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct InputFormat {
+ pub sample_rate: usize,
+ pub channels: usize,
+}
+
+/// Un bloque tal y como sale de la retrollamada, con la marca de tiempo que
+/// permite luego medir cuánto se ha retrasado el pipeline respecto de la voz.
+#[derive(Debug)]
+pub struct CaptureBlock {
+ pub samples: Vec<f32>,
+ pub at: Instant,
+}
+
+pub struct Capture {
+ stream: cpal::Stream,
+ pub format: InputFormat,
+ pub device_name: String,
+}
+
+impl Capture {
+ /// Abre la entrada y empieza a empujar bloques por `tx`.
+ ///
+ /// Prefiere 16 kHz mono porque es justo lo que quiere el modelo: si el
+ /// dispositivo lo acepta, no hay remuestreo en ningún punto del camino.
+ pub fn open(config: &AudioConfig, tx: Sender<CaptureBlock>) -> Result<Self> {
+ let host = cpal::default_host();
+ let device = select_device(&host, &config.input_device)?;
+ let device_name = describe(&device);
+
+ let supported = preferred_config(&device)?;
+ let format = InputFormat {
+ sample_rate: supported.sample_rate() as usize,
+ channels: supported.channels() as usize,
+ };
+ let stream_config: cpal::StreamConfig = supported.clone().into();
+ let on_error = |err| tracing::error!(target: "audio", %err, "flujo de entrada");
+
+ // Dentro de la retrollamada: convertir a f32, enviar y salir. `send`
+ // sobre un canal sin límite no bloquea, que es la única propiedad que
+ // aquí importa.
+ macro_rules! build {
+ ($sample:ty) => {
+ device
+ .build_input_stream(
+ &stream_config,
+ move |data: &[$sample], _: &_| {
+ let samples = data.iter().map(|s| f32::from_sample(*s)).collect();
+ let _ = tx.send(CaptureBlock {
+ samples,
+ at: Instant::now(),
+ });
+ },
+ on_error,
+ None,
+ )
+ .map_err(|e| Error::Audio(format!("no se pudo abrir la entrada: {e}")))?
+ };
+ }
+
+ let stream = match supported.sample_format() {
+ SampleFormat::F32 => build!(f32),
+ SampleFormat::I16 => build!(i16),
+ SampleFormat::U16 => build!(u16),
+ other => {
+ return Err(Error::Audio(format!(
+ "formato de muestra no soportado: {other:?}"
+ )))
+ }
+ };
+ stream
+ .play()
+ .map_err(|e| Error::Audio(format!("no se pudo arrancar la entrada: {e}")))?;
+
+ tracing::info!(
+ target: "audio",
+ dispositivo = %device_name,
+ hz = format.sample_rate,
+ canales = format.channels,
+ remuestreo = format.sample_rate != ASR_SAMPLE_RATE as usize || format.channels != 1,
+ "entrada abierta"
+ );
+
+ Ok(Self {
+ stream,
+ format,
+ device_name,
+ })
+ }
+
+ /// Cierra el dispositivo. Al soltar el emisor, la cadena de hilos se
+ /// desmonta sola de arriba abajo.
+ pub fn stop(self) {
+ drop(self.stream);
+ }
+}
+
+fn select_device(host: &cpal::Host, wanted: &str) -> Result<cpal::Device> {
+ if wanted.is_empty() {
+ return host
+ .default_input_device()
+ .ok_or_else(|| Error::Audio("no hay dispositivo de entrada".into()));
+ }
+ let wanted_lower = wanted.to_lowercase();
+ let devices = host
+ .input_devices()
+ .map_err(|e| Error::Audio(format!("no se pudieron listar las entradas: {e}")))?;
+ let mut seen = Vec::new();
+ for device in devices {
+ let name = describe(&device);
+ if name.to_lowercase().contains(&wanted_lower) {
+ return Ok(device);
+ }
+ seen.push(name);
+ }
+ Err(Error::Audio(format!(
+ "ninguna entrada coincide con «{wanted}». Disponibles: {}",
+ seen.join(", ")
+ )))
+}
+
+fn preferred_config(device: &cpal::Device) -> Result<SupportedStreamConfig> {
+ let native = device
+ .supported_input_configs()
+ .map_err(|e| Error::Audio(format!("no se pudo consultar la entrada: {e}")))?
+ .filter(|range| range.channels() == 1)
+ .filter(|range| {
+ range.min_sample_rate() <= ASR_SAMPLE_RATE && ASR_SAMPLE_RATE <= range.max_sample_rate()
+ })
+ .find(|range| range.sample_format() == SampleFormat::F32)
+ .map(|range| range.with_sample_rate(ASR_SAMPLE_RATE));
+
+ match native {
+ Some(config) => Ok(config),
+ None => device
+ .default_input_config()
+ .map_err(|e| Error::Audio(format!("sin configuración de entrada: {e}"))),
+ }
+}
diff --git a/crates/asist-audio/src/lib.rs b/crates/asist-audio/src/lib.rs
new file mode 100644
index 0000000..f6979ca
--- /dev/null
+++ b/crates/asist-audio/src/lib.rs
@@ -0,0 +1,148 @@
+//! Entrada y salida de audio, y el detector de voz que las separa en turnos.
+//!
+//! La regla que gobierna este crate: **la retrollamada de audio no bloquea
+//! nunca**. cpal la ejecuta en un hilo de tiempo real y cualquier espera ahí
+//! se oye como un chasquido, así que se limita a copiar muestras a un canal
+//! (entrada) o a vaciar un anillo ya rellenado (salida). Todo el trabajo real
+//! —remuestreo, VAD, HTTP— ocurre en hilos normales al otro lado.
+
+pub mod capture;
+pub mod playback;
+pub mod vad;
+
+/// Se reexporta para que el binario pueda listar dispositivos sin volver a
+/// declarar cpal y arriesgarse a resolver otra versión.
+pub use cpal;
+
+pub use capture::{Capture, CaptureBlock, InputFormat};
+pub use playback::{Playback, PlaybackHandle};
+pub use vad::{Gate, Segmenter, Utterance, VoiceEvent};
+
+/// Frecuencia a la que trabaja Canary. La captura se abre directamente aquí
+/// cuando el dispositivo lo permite, lo que quita el remuestreo del camino.
+pub const ASR_SAMPLE_RATE: u32 = 16_000;
+
+/// Frecuencia a la que sintetiza qwentts.
+pub const TTS_SAMPLE_RATE: u32 = 24_000;
+
+/// Nombre legible de un dispositivo.
+///
+/// `DeviceTrait::name` está obsoleto en cpal 0.17 a favor de `description`,
+/// que devuelve una ficha entera; aquí sólo interesa el nombre, y tener un
+/// único sitio donde extraerlo evita repetir el desempaquetado.
+pub fn describe(device: &impl cpal::traits::DeviceTrait) -> String {
+ device
+ .description()
+ .map(|d| d.name().to_string())
+ .unwrap_or_else(|_| "desconocido".into())
+}
+
+/// Nivel RMS de un bloque, la medida con la que el VAD decide.
+pub fn rms(samples: &[f32]) -> f32 {
+ if samples.is_empty() {
+ return 0.0;
+ }
+ let sum: f32 = samples.iter().map(|v| v * v).sum();
+ (sum / samples.len() as f32).sqrt()
+}
+
+/// Mezcla a mono y remuestrea linealmente a `target`.
+///
+/// La interpolación lineal basta: el dispositivo ya entrega la señal limitada
+/// en banda, y un remuestreador decente costaría más que la decodificación a
+/// la que alimenta.
+pub fn to_mono_at(samples: &[f32], format: InputFormat, target: u32) -> Vec<f32> {
+ let mono: Vec<f32> = if format.channels > 1 {
+ samples
+ .chunks(format.channels)
+ .map(|frame| frame.iter().sum::<f32>() / format.channels as f32)
+ .collect()
+ } else {
+ samples.to_vec()
+ };
+
+ if format.sample_rate == target as usize {
+ return mono;
+ }
+ let ratio = target as f64 / format.sample_rate as f64;
+ let out_len = (mono.len() as f64 * ratio) as usize;
+ (0..out_len)
+ .map(|i| {
+ let pos = i as f64 / ratio;
+ let idx = pos as usize;
+ let frac = (pos - idx as f64) as f32;
+ let a = mono.get(idx).copied().unwrap_or(0.0);
+ let b = mono.get(idx + 1).copied().unwrap_or(a);
+ a + (b - a) * frac
+ })
+ .collect()
+}
+
+/// Convierte s16le a f32 en [-1, 1]. Es el formato en el que el TTS entrega.
+pub fn s16le_to_f32(bytes: &[u8], out: &mut Vec<f32>) {
+ for pair in bytes.chunks_exact(2) {
+ let sample = i16::from_le_bytes([pair[0], pair[1]]);
+ out.push(sample as f32 / 32768.0);
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn el_rms_de_una_senal_constante_es_su_amplitud() {
+ assert!((rms(&[0.5; 100]) - 0.5).abs() < 1e-6);
+ assert_eq!(rms(&[]), 0.0);
+ }
+
+ #[test]
+ fn el_estereo_se_mezcla_a_mono_promediando() {
+ let format = InputFormat {
+ sample_rate: 16_000,
+ channels: 2,
+ };
+ let out = to_mono_at(&[1.0, 0.0, 0.5, 0.5], format, 16_000);
+ assert_eq!(out, vec![0.5, 0.5]);
+ }
+
+ #[test]
+ fn el_remuestreo_ajusta_la_duracion() {
+ let format = InputFormat {
+ sample_rate: 48_000,
+ channels: 1,
+ };
+ let out = to_mono_at(&vec![0.0; 4800], format, 16_000);
+ assert_eq!(out.len(), 1600, "48 kHz -> 16 kHz debe dividir por tres");
+ }
+
+ #[test]
+ fn a_la_misma_frecuencia_el_remuestreo_no_toca_nada() {
+ let format = InputFormat {
+ sample_rate: 16_000,
+ channels: 1,
+ };
+ let input = vec![0.1, -0.2, 0.3];
+ assert_eq!(to_mono_at(&input, format, 16_000), input);
+ }
+
+ #[test]
+ fn s16le_recorre_el_rango_completo() {
+ let mut out = Vec::new();
+ s16le_to_f32(&[0x00, 0x00, 0xff, 0x7f, 0x00, 0x80], &mut out);
+ assert_eq!(out[0], 0.0);
+ assert!((out[1] - 1.0).abs() < 1e-4);
+ assert!((out[2] + 1.0).abs() < 1e-6);
+ }
+
+ #[test]
+ fn un_byte_suelto_no_produce_una_muestra_a_medias() {
+ let mut out = Vec::new();
+ s16le_to_f32(&[0x00, 0x00, 0x11], &mut out);
+ assert_eq!(
+ out.len(),
+ 1,
+ "el byte impar se ignora en vez de corromper la muestra"
+ );
+ }
+}
diff --git a/crates/asist-audio/src/playback.rs b/crates/asist-audio/src/playback.rs
new file mode 100644
index 0000000..fcdfe7d
--- /dev/null
+++ b/crates/asist-audio/src/playback.rs
@@ -0,0 +1,287 @@
+//! Reproducción del audio sintetizado.
+//!
+//! El TTS produce a ráfagas —un bloque de codec cada vez— y el altavoz consume
+//! a ritmo constante, así que entre ambos hay un anillo. La retrollamada sólo
+//! vacía el anillo; quien sintetiza sólo lo llena. Cortar la respuesta es
+//! entonces una operación trivial y sin condiciones de carrera: se vacía el
+//! anillo y la voz calla en el siguiente bloque de audio.
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, Condvar, Mutex};
+use std::time::Duration;
+
+use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
+use cpal::SampleFormat;
+
+use asist_core::config::AudioConfig;
+use asist_core::error::{Error, Result};
+
+use crate::{describe, to_mono_at, InputFormat, TTS_SAMPLE_RATE};
+
+/// Estado compartido entre quien sintetiza y la retrollamada del altavoz.
+struct Ring {
+ samples: Mutex<std::collections::VecDeque<f32>>,
+ /// Despierta a quien espera a que se vacíe la cola.
+ drained: Condvar,
+ /// Muestras servidas al altavoz desde que arrancó. Sirve para saber si ya
+ /// ha sonado algo de verdad, que es la latencia que percibe el usuario.
+ played: AtomicU64,
+ /// Hay audio en curso (queda cola o se está alimentando).
+ active: AtomicBool,
+ gain: Mutex<f32>,
+}
+
+impl Ring {
+ fn new(gain: f32) -> Self {
+ Self {
+ samples: Mutex::new(std::collections::VecDeque::new()),
+ drained: Condvar::new(),
+ played: AtomicU64::new(0),
+ active: AtomicBool::new(false),
+ gain: Mutex::new(gain),
+ }
+ }
+
+ fn lock(&self) -> std::sync::MutexGuard<'_, std::collections::VecDeque<f32>> {
+ self.samples.lock().unwrap_or_else(|e| e.into_inner())
+ }
+}
+
+/// Mando a distancia del altavoz: se puede clonar y repartir por los hilos.
+#[derive(Clone)]
+pub struct PlaybackHandle {
+ ring: Arc<Ring>,
+ sample_rate: u32,
+}
+
+impl PlaybackHandle {
+ /// Encola muestras mono ya a la frecuencia del dispositivo.
+ pub fn push(&self, samples: &[f32]) {
+ if samples.is_empty() {
+ return;
+ }
+ let mut queue = self.ring.lock();
+ queue.extend(samples.iter().copied());
+ self.ring.active.store(true, Ordering::SeqCst);
+ }
+
+ /// Encola audio del TTS (24 kHz mono), remuestreando si hace falta.
+ pub fn push_tts(&self, samples: &[f32]) {
+ if self.sample_rate == TTS_SAMPLE_RATE {
+ self.push(samples);
+ return;
+ }
+ let format = InputFormat {
+ sample_rate: TTS_SAMPLE_RATE as usize,
+ channels: 1,
+ };
+ self.push(&to_mono_at(samples, format, self.sample_rate));
+ }
+
+ /// Calla ahora mismo y tira lo que quedaba por sonar.
+ pub fn stop(&self) {
+ let mut queue = self.ring.lock();
+ queue.clear();
+ self.ring.active.store(false, Ordering::SeqCst);
+ self.ring.drained.notify_all();
+ }
+
+ /// Segundos de audio pendientes de sonar.
+ pub fn queued_secs(&self) -> f32 {
+ self.ring.lock().len() as f32 / self.sample_rate as f32
+ }
+
+ /// `true` si ya ha salido audio por el altavoz.
+ pub fn has_played(&self) -> bool {
+ self.ring.played.load(Ordering::SeqCst) > 0
+ }
+
+ pub fn reset_played(&self) {
+ self.ring.played.store(0, Ordering::SeqCst);
+ }
+
+ pub fn is_active(&self) -> bool {
+ self.ring.active.load(Ordering::SeqCst)
+ }
+
+ pub fn set_gain(&self, gain: f32) {
+ *self.ring.gain.lock().unwrap_or_else(|e| e.into_inner()) = gain;
+ }
+
+ /// Espera a que se vacíe la cola, o a que venza el plazo.
+ ///
+ /// Devuelve `true` si terminó de sonar todo y `false` si se agotó el
+ /// tiempo, para que quien llama distinga «ya está» de «sigue sonando».
+ pub fn wait_drained(&self, timeout: Duration) -> bool {
+ let deadline = std::time::Instant::now() + timeout;
+ let mut queue = self.ring.lock();
+ while !queue.is_empty() {
+ let left = deadline.saturating_duration_since(std::time::Instant::now());
+ if left.is_zero() {
+ return false;
+ }
+ let (guard, result) = self
+ .ring
+ .drained
+ .wait_timeout(queue, left.min(Duration::from_millis(50)))
+ .unwrap_or_else(|e| e.into_inner());
+ queue = guard;
+ if result.timed_out() && queue.is_empty() {
+ break;
+ }
+ }
+ self.ring.active.store(false, Ordering::SeqCst);
+ true
+ }
+}
+
+pub struct Playback {
+ stream: cpal::Stream,
+ handle: PlaybackHandle,
+ pub device_name: String,
+ pub sample_rate: u32,
+}
+
+impl Playback {
+ pub fn open(config: &AudioConfig) -> Result<Self> {
+ let host = cpal::default_host();
+ let device = select_device(&host, &config.output_device)?;
+ let device_name = describe(&device);
+
+ let supported = preferred_config(&device)?;
+ let sample_rate = supported.sample_rate();
+ let channels = supported.channels() as usize;
+ let stream_config: cpal::StreamConfig = supported.clone().into();
+
+ let ring = Arc::new(Ring::new(config.output_gain));
+ let on_error = |err| tracing::error!(target: "audio", %err, "flujo de salida");
+
+ // La retrollamada: coger lo que haya, rellenar con silencio lo que
+ // falte y salir. Nunca espera a que llegue audio, porque quedarse
+ // esperando aquí se oye como un corte.
+ macro_rules! build {
+ ($sample:ty, $silence:expr, $convert:expr) => {{
+ let ring = Arc::clone(&ring);
+ device
+ .build_output_stream(
+ &stream_config,
+ move |data: &mut [$sample], _: &_| {
+ let gain = *ring.gain.lock().unwrap_or_else(|e| e.into_inner());
+ let mut queue = ring.lock();
+ let mut served = 0u64;
+ for frame in data.chunks_mut(channels) {
+ match queue.pop_front() {
+ Some(sample) => {
+ let value = (sample * gain).clamp(-1.0, 1.0);
+ // Mono a N canales: la misma muestra en todos.
+ for out in frame.iter_mut() {
+ *out = $convert(value);
+ }
+ served += 1;
+ }
+ None => {
+ for out in frame.iter_mut() {
+ *out = $silence;
+ }
+ }
+ }
+ }
+ if served > 0 {
+ ring.played.fetch_add(served, Ordering::SeqCst);
+ }
+ if queue.is_empty() {
+ ring.drained.notify_all();
+ }
+ },
+ on_error,
+ None,
+ )
+ .map_err(|e| Error::Audio(format!("no se pudo abrir la salida: {e}")))?
+ }};
+ }
+
+ let stream = match supported.sample_format() {
+ SampleFormat::F32 => build!(f32, 0.0f32, |v: f32| v),
+ SampleFormat::I16 => build!(i16, 0i16, |v: f32| (v * 32767.0) as i16),
+ SampleFormat::U16 => {
+ build!(u16, u16::MAX / 2, |v: f32| ((v * 32767.0) as i32 + 32768)
+ as u16)
+ }
+ other => {
+ return Err(Error::Audio(format!(
+ "formato de salida no soportado: {other:?}"
+ )))
+ }
+ };
+ stream
+ .play()
+ .map_err(|e| Error::Audio(format!("no se pudo arrancar la salida: {e}")))?;
+
+ tracing::info!(
+ target: "audio",
+ dispositivo = %device_name,
+ hz = sample_rate,
+ canales = channels,
+ "salida abierta"
+ );
+
+ Ok(Self {
+ stream,
+ handle: PlaybackHandle { ring, sample_rate },
+ device_name,
+ sample_rate,
+ })
+ }
+
+ pub fn handle(&self) -> PlaybackHandle {
+ self.handle.clone()
+ }
+
+ pub fn stop(self) {
+ self.handle.stop();
+ drop(self.stream);
+ }
+}
+
+fn select_device(host: &cpal::Host, wanted: &str) -> Result<cpal::Device> {
+ if wanted.is_empty() {
+ return host
+ .default_output_device()
+ .ok_or_else(|| Error::Audio("no hay dispositivo de salida".into()));
+ }
+ let wanted_lower = wanted.to_lowercase();
+ let devices = host
+ .output_devices()
+ .map_err(|e| Error::Audio(format!("no se pudieron listar las salidas: {e}")))?;
+ let mut seen = Vec::new();
+ for device in devices {
+ let name = describe(&device);
+ if name.to_lowercase().contains(&wanted_lower) {
+ return Ok(device);
+ }
+ seen.push(name);
+ }
+ Err(Error::Audio(format!(
+ "ninguna salida coincide con «{wanted}». Disponibles: {}",
+ seen.join(", ")
+ )))
+}
+
+fn preferred_config(device: &cpal::Device) -> Result<cpal::SupportedStreamConfig> {
+ // 24 kHz nativo evita remuestrear la síntesis; si no, se coge lo de fábrica.
+ let native = device
+ .supported_output_configs()
+ .map_err(|e| Error::Audio(format!("no se pudo consultar la salida: {e}")))?
+ .filter(|range| {
+ range.min_sample_rate() <= TTS_SAMPLE_RATE && TTS_SAMPLE_RATE <= range.max_sample_rate()
+ })
+ .find(|range| range.sample_format() == SampleFormat::F32)
+ .map(|range| range.with_sample_rate(TTS_SAMPLE_RATE));
+
+ match native {
+ Some(config) => Ok(config),
+ None => device
+ .default_output_config()
+ .map_err(|e| Error::Audio(format!("sin configuración de salida: {e}"))),
+ }
+}
diff --git a/crates/asist-audio/src/vad.rs b/crates/asist-audio/src/vad.rs
new file mode 100644
index 0000000..b30f833
--- /dev/null
+++ b/crates/asist-audio/src/vad.rs
@@ -0,0 +1,403 @@
+//! Detección de voz y troceado en intervenciones.
+//!
+//! Está escrito como una máquina de estados pura: se le dan muestras y
+//! devuelve eventos, sin hilos ni canales dentro. Así el comportamiento que
+//! más cuesta depurar a oído —cuándo arranca un turno, cuándo lo corta el
+//! silencio, cuándo se ignora el eco del propio altavoz— se puede probar
+//! entero con audio sintético y sin micrófono.
+
+use std::collections::VecDeque;
+
+use asist_core::config::VadConfig;
+
+use crate::{rms, ASR_SAMPLE_RATE};
+
+/// Una intervención cerrada, lista para transcribir.
+#[derive(Debug, Clone)]
+pub struct Utterance {
+ pub samples: Vec<f32>,
+ pub sample_rate: u32,
+}
+
+impl Utterance {
+ pub fn duration_secs(&self) -> f32 {
+ self.samples.len() as f32 / self.sample_rate as f32
+ }
+}
+
+/// Lo que el segmentador tiene que contar hacia fuera.
+#[derive(Debug, Clone)]
+pub enum VoiceEvent {
+ /// Ha empezado a hablarse.
+ Started,
+ /// Audio nuevo dentro de la intervención en curso, para las
+ /// transcripciones provisionales.
+ Audio(Vec<f32>),
+ /// Intervención terminada y lo bastante larga como para transcribirla.
+ Ended(Utterance),
+ /// Terminada pero demasiado corta: un golpe en la mesa, una tos.
+ Discarded,
+ /// Se ha detectado voz mientras el asistente hablaba, con el barge-in
+ /// activo. El orquestador corta la reproducción al recibirlo.
+ BargeIn,
+}
+
+/// Qué hace el segmentador con el micrófono mientras suena el altavoz.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Gate {
+ /// Nadie está hablando por el altavoz: se escucha con normalidad.
+ Open,
+ /// El asistente habla. Según la configuración, o se ignora la entrada
+ /// (media dúplex) o se exige más volumen para interrumpir (barge-in).
+ Speaking,
+}
+
+pub struct Segmenter {
+ config: VadConfig,
+ frame_samples: usize,
+ preroll_samples: usize,
+ silence_hold_samples: usize,
+ min_utterance_samples: usize,
+ max_utterance_samples: usize,
+
+ pending: Vec<f32>,
+ preroll: VecDeque<f32>,
+ utterance: Vec<f32>,
+ /// Muestras de la intervención que estaban de verdad por encima del
+ /// umbral. El mínimo se mide sobre esto y no sobre `utterance`, que
+ /// arrastra el preroll: si no, 0,1 s de golpe en la mesa más 0,2 s de
+ /// preroll pasan por una intervención válida y disparan un turno entero.
+ voiced: usize,
+ noise_floor: f32,
+ silence_run: usize,
+ speaking: bool,
+ gate: Gate,
+}
+
+impl Segmenter {
+ pub fn new(config: &VadConfig) -> Self {
+ let rate = ASR_SAMPLE_RATE as f32;
+ Self {
+ frame_samples: (rate * config.frame_seconds).max(1.0) as usize,
+ preroll_samples: (rate * config.preroll_seconds) as usize,
+ silence_hold_samples: (rate * config.silence_hold) as usize,
+ min_utterance_samples: (rate * config.min_utterance) as usize,
+ max_utterance_samples: (rate * config.max_utterance) as usize,
+ config: config.clone(),
+ pending: Vec::new(),
+ preroll: VecDeque::new(),
+ utterance: Vec::new(),
+ voiced: 0,
+ noise_floor: 0.0,
+ silence_run: 0,
+ speaking: false,
+ gate: Gate::Open,
+ }
+ }
+
+ /// Abre o cierra el micrófono según hable o no el asistente.
+ pub fn set_gate(&mut self, gate: Gate) {
+ if self.gate == gate {
+ return;
+ }
+ self.gate = gate;
+ // Al volver a abrir tras una respuesta, lo acumulado es la cola del
+ // propio altavoz: arrancar un turno con eso daría un turno fantasma.
+ if gate == Gate::Open {
+ self.pending.clear();
+ self.preroll.clear();
+ self.utterance.clear();
+ self.voiced = 0;
+ self.silence_run = 0;
+ self.speaking = false;
+ }
+ }
+
+ pub fn is_speaking(&self) -> bool {
+ self.speaking
+ }
+
+ pub fn noise_floor(&self) -> f32 {
+ self.noise_floor
+ }
+
+ /// Umbral que separa voz de silencio ahora mismo.
+ pub fn threshold(&self) -> f32 {
+ let base = (self.noise_floor * self.config.threshold_factor)
+ .clamp(self.config.min_threshold, self.config.max_threshold);
+ // Con el altavoz sonando hay que hablar más alto para colarse: el
+ // micrófono se está oyendo a sí mismo.
+ if self.gate == Gate::Speaking {
+ base * self.config.barge_in_factor
+ } else {
+ base
+ }
+ }
+
+ /// Cierra a la fuerza la intervención en curso (cierre del programa).
+ pub fn flush(&mut self) -> Option<Utterance> {
+ if !self.speaking || self.voiced < self.min_utterance_samples {
+ return None;
+ }
+ self.speaking = false;
+ self.voiced = 0;
+ Some(Utterance {
+ samples: std::mem::take(&mut self.utterance),
+ sample_rate: ASR_SAMPLE_RATE,
+ })
+ }
+
+ /// Alimenta audio mono a 16 kHz y recoge lo que haya que hacer.
+ pub fn push(&mut self, samples: &[f32]) -> Vec<VoiceEvent> {
+ let mut events = Vec::new();
+ // En media dúplex el micrófono está apagado de hecho: sin esto, el
+ // asistente se transcribe a sí mismo y se responde solo.
+ if self.gate == Gate::Speaking && !self.config.barge_in {
+ return events;
+ }
+ self.pending.extend_from_slice(samples);
+
+ while self.pending.len() >= self.frame_samples {
+ let frame: Vec<f32> = self.pending.drain(..self.frame_samples).collect();
+ let level = rms(&frame);
+ self.track_noise_floor(level);
+ let threshold = self.threshold();
+
+ if level < threshold && !self.speaking {
+ self.preroll.extend(frame.iter().copied());
+ while self.preroll.len() > self.preroll_samples {
+ self.preroll.pop_front();
+ }
+ continue;
+ }
+
+ if !self.speaking {
+ self.speaking = true;
+ self.utterance.clear();
+ self.voiced = 0;
+ self.utterance.extend(self.preroll.drain(..));
+ if self.gate == Gate::Speaking {
+ events.push(VoiceEvent::BargeIn);
+ }
+ events.push(VoiceEvent::Started);
+ }
+
+ if level < threshold {
+ self.silence_run += frame.len();
+ } else {
+ self.silence_run = 0;
+ self.voiced += frame.len();
+ }
+ self.utterance.extend_from_slice(&frame);
+
+ let ended = self.silence_run >= self.silence_hold_samples;
+ let too_long = self.utterance.len() >= self.max_utterance_samples;
+ if !ended && !too_long {
+ events.push(VoiceEvent::Audio(frame));
+ continue;
+ }
+
+ let long_enough = self.voiced >= self.min_utterance_samples;
+ events.push(if long_enough {
+ VoiceEvent::Ended(Utterance {
+ samples: std::mem::take(&mut self.utterance),
+ sample_rate: ASR_SAMPLE_RATE,
+ })
+ } else {
+ VoiceEvent::Discarded
+ });
+
+ self.utterance.clear();
+ self.voiced = 0;
+ self.preroll.clear();
+ self.silence_run = 0;
+ // Un corte por longitud cae a mitad de frase: se sigue escuchando
+ // como si el usuario no hubiera dejado de hablar, que es la verdad.
+ self.speaking = too_long && !ended;
+ if self.speaking {
+ events.push(VoiceEvent::Started);
+ }
+ }
+ events
+ }
+
+ /// El suelo de ruido sólo baja: una voz sostenida no debe poder arrastrar
+ /// el umbral por encima de sí misma y dejar de detectarse.
+ fn track_noise_floor(&mut self, level: f32) {
+ if self.noise_floor == 0.0 {
+ self.noise_floor = level;
+ } else if level < self.noise_floor * 1.5 {
+ self.noise_floor = self.noise_floor * 0.95 + level * 0.05;
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn config() -> VadConfig {
+ VadConfig {
+ frame_seconds: 0.1,
+ preroll_seconds: 0.2,
+ silence_hold: 0.3,
+ min_utterance: 0.3,
+ max_utterance: 2.0,
+ threshold_factor: 3.0,
+ min_threshold: 0.001,
+ max_threshold: 0.02,
+ barge_in: false,
+ barge_in_factor: 4.0,
+ }
+ }
+
+ fn samples(secs: f32, amplitude: f32) -> Vec<f32> {
+ let n = (ASR_SAMPLE_RATE as f32 * secs) as usize;
+ // Alterna de signo para que el RMS sea la amplitud y no un continuo.
+ (0..n)
+ .map(|i| if i % 2 == 0 { amplitude } else { -amplitude })
+ .collect()
+ }
+
+ fn feed(seg: &mut Segmenter, secs: f32, amplitude: f32) -> Vec<VoiceEvent> {
+ seg.push(&samples(secs, amplitude))
+ }
+
+ #[test]
+ fn el_silencio_no_arranca_ningun_turno() {
+ let mut seg = Segmenter::new(&config());
+ let events = feed(&mut seg, 2.0, 0.0001);
+ assert!(
+ events.is_empty(),
+ "el silencio no debe producir eventos: {events:?}"
+ );
+ }
+
+ #[test]
+ fn la_voz_seguida_de_silencio_cierra_una_intervencion() {
+ let mut seg = Segmenter::new(&config());
+ feed(&mut seg, 1.0, 0.0002); // deja que el suelo de ruido se asiente
+ let mut events = feed(&mut seg, 0.8, 0.3);
+ events.extend(feed(&mut seg, 0.6, 0.0002));
+
+ assert!(matches!(events.first(), Some(VoiceEvent::Started)));
+ let ended = events.iter().find_map(|e| match e {
+ VoiceEvent::Ended(u) => Some(u),
+ _ => None,
+ });
+ let utterance = ended.expect("la intervención debió cerrarse");
+ assert!(
+ utterance.duration_secs() > 0.8,
+ "el preroll debe ir incluido, duró {}",
+ utterance.duration_secs()
+ );
+ }
+
+ #[test]
+ fn un_ruido_corto_se_descarta() {
+ let mut seg = Segmenter::new(&config());
+ feed(&mut seg, 1.0, 0.0002);
+ let mut events = feed(&mut seg, 0.1, 0.3);
+ events.extend(feed(&mut seg, 0.6, 0.0002));
+ // 0,1 s de golpe no llegan al mínimo de 0,3 s de voz, por mucho que el
+ // preroll haga que la intervención dure más.
+ assert!(
+ events.iter().any(|e| matches!(e, VoiceEvent::Discarded)),
+ "esperaba un descarte: {events:?}"
+ );
+ }
+
+ #[test]
+ fn una_intervencion_interminable_se_corta_y_se_sigue_escuchando() {
+ let mut seg = Segmenter::new(&config());
+ feed(&mut seg, 1.0, 0.0002);
+ let events = feed(&mut seg, 3.0, 0.3);
+ assert!(
+ events.iter().any(|e| matches!(e, VoiceEvent::Ended(_))),
+ "a los 2 s debe cortarse: {events:?}"
+ );
+ assert!(
+ seg.is_speaking(),
+ "tras un corte forzado se sigue en mitad de la frase"
+ );
+ }
+
+ #[test]
+ fn en_media_duplex_el_altavoz_no_se_transcribe_a_si_mismo() {
+ let mut seg = Segmenter::new(&config());
+ feed(&mut seg, 1.0, 0.0002);
+ seg.set_gate(Gate::Speaking);
+ let events = feed(&mut seg, 2.0, 0.5);
+ assert!(
+ events.is_empty(),
+ "con barge_in apagado no debe entrar nada mientras habla el asistente: {events:?}"
+ );
+ }
+
+ #[test]
+ fn con_barge_in_hace_falta_hablar_mas_alto_para_cortar() {
+ let mut config = config();
+ config.barge_in = true;
+ config.barge_in_factor = 4.0;
+ let mut seg = Segmenter::new(&config);
+ feed(&mut seg, 1.0, 0.0002);
+ seg.set_gate(Gate::Speaking);
+
+ // Justo por encima del umbral normal pero por debajo del elevado.
+ let eco = seg.threshold() / config.barge_in_factor * 1.5;
+ let events = feed(&mut seg, 0.5, eco);
+ assert!(
+ events.is_empty(),
+ "el eco del altavoz no debe cortar: {events:?}"
+ );
+
+ let voz = seg.threshold() * 2.0;
+ let events = feed(&mut seg, 0.5, voz);
+ assert!(
+ events.iter().any(|e| matches!(e, VoiceEvent::BargeIn)),
+ "una voz clara sí debe cortar: {events:?}"
+ );
+ }
+
+ #[test]
+ fn al_reabrir_el_microfono_se_tira_la_cola_del_altavoz() {
+ let mut config = config();
+ config.barge_in = true;
+ let mut seg = Segmenter::new(&config);
+ feed(&mut seg, 1.0, 0.0002);
+ seg.set_gate(Gate::Speaking);
+ feed(&mut seg, 0.5, 0.9);
+ assert!(seg.is_speaking());
+
+ seg.set_gate(Gate::Open);
+ assert!(
+ !seg.is_speaking(),
+ "reabrir debe descartar lo acumulado; si no, el turno siguiente arranca con eco"
+ );
+ }
+
+ #[test]
+ fn el_suelo_de_ruido_no_sube_con_la_voz() {
+ let mut seg = Segmenter::new(&config());
+ feed(&mut seg, 1.0, 0.0002);
+ let quieto = seg.noise_floor();
+ feed(&mut seg, 2.0, 0.5);
+ assert!(
+ seg.noise_floor() <= quieto * 1.5,
+ "hablar no debe elevar el suelo de ruido ({quieto} -> {})",
+ seg.noise_floor()
+ );
+ }
+
+ #[test]
+ fn el_cierre_entrega_la_intervencion_a_medias() {
+ let mut seg = Segmenter::new(&config());
+ feed(&mut seg, 1.0, 0.0002);
+ feed(&mut seg, 0.5, 0.3);
+ assert!(
+ seg.flush().is_some(),
+ "lo ya hablado no debe perderse al cerrar"
+ );
+ assert!(seg.flush().is_none(), "y no debe entregarse dos veces");
+ }
+}
diff --git a/crates/asist-core/Cargo.toml b/crates/asist-core/Cargo.toml
new file mode 100644
index 0000000..bd8c3ae
--- /dev/null
+++ b/crates/asist-core/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "asist-core"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+crossbeam-channel.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+toml.workspace = true
+tracing.workspace = true
diff --git a/crates/asist-core/src/config.rs b/crates/asist-core/src/config.rs
new file mode 100644
index 0000000..4ca8d8c
--- /dev/null
+++ b/crates/asist-core/src/config.rs
@@ -0,0 +1,508 @@
+//! Configuración del asistente: un TOML con valores por defecto que ya
+//! incorporan lo aprendido midiendo el pipeline (ver `docs/RENDIMIENTO.md`).
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use crate::error::{Error, Result};
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct Config {
+ pub general: General,
+ pub audio: AudioConfig,
+ pub vad: VadConfig,
+ pub asr: AsrConfig,
+ pub llm: LlmConfig,
+ pub tts: TtsConfig,
+ pub tools: ToolsConfig,
+ pub supervisor: SupervisorConfig,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct General {
+ /// Idioma de la conversación; se propaga a ASR y TTS.
+ pub language: String,
+ /// Instrucción de sistema. Pide frases cortas y sin markdown a propósito:
+ /// el TTS lee literalmente los asteriscos y las viñetas.
+ pub system_prompt: String,
+ /// Instrucción de sistema de la pasada en que el modelo decide si usar
+ /// una herramienta.
+ ///
+ /// Va aparte, y **sustituye** a `system_prompt` en esa pasada, por una
+ /// razón medida y no por gusto: con Qwen3.5-2B, añadir cualquier
+ /// indicación de estilo a esta guía —en cualquier posición, incluso dos
+ /// palabras— hace que el modelo deje de llamar a las herramientas y se
+ /// invente el dato. Medido sobre 8 intentos: la guía sola acierta 8/8;
+ /// con «Responde breve.» detrás, 1/8; con la persona de asistente de voz,
+ /// 0/8. Ver docs/RENDIMIENTO.md.
+ pub tools_prompt: String,
+ /// Turnos de historial que se envían al modelo (0 = sin memoria).
+ pub history_turns: usize,
+ /// Imprime un resumen de latencias por turno al terminar cada respuesta.
+ pub report_latency: bool,
+}
+
+impl Default for General {
+ fn default() -> Self {
+ Self {
+ language: "es".into(),
+ system_prompt: concat!(
+ "Eres un asistente de voz en español. Tus respuestas se leen en voz alta, ",
+ "así que responde en una o dos frases cortas, en texto plano corrido. ",
+ "No uses markdown, ni listas, ni asteriscos, ni emojis, ni encabezados. ",
+ "No escribas URLs ni código salvo que te lo pidan explícitamente. ",
+ "Si no sabes algo, dilo en una frase."
+ )
+ .into(),
+ tools_prompt: concat!(
+ "Antes de responder, comprueba si alguna de tus herramientas te da el dato. ",
+ "Si es así, llámala primero y espera su resultado; no contestes de memoria. ",
+ "Sólo cuando tengas el resultado, resúmelo en una frase."
+ )
+ .into(),
+ history_turns: 8,
+ report_latency: true,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct AudioConfig {
+ /// Nombre (o subcadena) del dispositivo de entrada; vacío = el de por defecto.
+ pub input_device: String,
+ /// Ídem para la salida.
+ pub output_device: String,
+ /// Segundos de audio que la reproducción mantiene en cola antes de
+ /// arrancar. Amortigua los baches del TTS sin añadir latencia perceptible.
+ pub playback_prebuffer: f32,
+ /// Ganancia aplicada a la reproducción.
+ pub output_gain: f32,
+}
+
+impl Default for AudioConfig {
+ fn default() -> Self {
+ Self {
+ input_device: String::new(),
+ output_device: String::new(),
+ playback_prebuffer: 0.20,
+ output_gain: 1.0,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct VadConfig {
+ /// Ventana de audio por decisión del detector.
+ pub frame_seconds: f32,
+ /// Audio conservado antes del inicio de voz para no cortar la primera sílaba.
+ pub preroll_seconds: f32,
+ /// Silencio que cierra una intervención.
+ pub silence_hold: f32,
+ /// Intervención más corta que merezca una transcripción final.
+ pub min_utterance: f32,
+ /// Corte forzado, que acota el coste de la decodificación final.
+ pub max_utterance: f32,
+ /// Múltiplo del suelo de ruido a partir del cual se considera voz.
+ pub threshold_factor: f32,
+ pub min_threshold: f32,
+ pub max_threshold: f32,
+ /// Permite hablar encima del asistente para cortarlo.
+ ///
+ /// Desactivado por defecto: con altavoces abiertos el micrófono se oye a sí
+ /// mismo y el asistente se interrumpe solo. Actívalo con auriculares o con
+ /// cancelación de eco del sistema.
+ pub barge_in: bool,
+ /// Con barge-in activo, cuánto más fuerte que el umbral normal debe sonar
+ /// la voz para cortar. Sube el listón frente al eco del altavoz.
+ pub barge_in_factor: f32,
+}
+
+impl Default for VadConfig {
+ fn default() -> Self {
+ Self {
+ frame_seconds: 0.1,
+ preroll_seconds: 0.3,
+ silence_hold: 0.8,
+ min_utterance: 0.3,
+ max_utterance: 20.0,
+ threshold_factor: 3.0,
+ min_threshold: 0.0008,
+ max_threshold: 0.02,
+ barge_in: false,
+ barge_in_factor: 4.0,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct AsrConfig {
+ /// Carpeta del modelo Canary en ONNX.
+ pub model_dir: PathBuf,
+ pub source_lang: String,
+ pub target_lang: String,
+ /// Ventana deslizante de las transcripciones provisionales.
+ pub window: f32,
+ /// Avance de la ventana entre decodificaciones.
+ pub step: f32,
+ /// Ventanas que deben coincidir para dar una palabra por estable.
+ pub stability: usize,
+ /// Emitir transcripciones provisionales. Cuestan CPU y sólo sirven para
+ /// verlas en pantalla: el turno se dispara con la final.
+ pub partials: bool,
+ /// Carga una segunda instancia del modelo para que las decodificaciones
+ /// finales no bloqueen a las provisionales. Duplica la memoria.
+ pub dedicated_final_model: bool,
+ /// Proveedor de ejecución de ONNX Runtime: `cpu`, `cuda`, ...
+ pub execution_provider: String,
+ pub inter_threads: usize,
+ pub intra_threads: usize,
+}
+
+impl Default for AsrConfig {
+ fn default() -> Self {
+ Self {
+ model_dir: PathBuf::from("vendor/canary-rs/models/canary-180m-flash-onnx"),
+ source_lang: "es".into(),
+ target_lang: "es".into(),
+ window: 6.0,
+ step: 0.4,
+ stability: 2,
+ partials: true,
+ dedicated_final_model: false,
+ // CPU a propósito: la GPU de 4 GB está ocupada por el hablante del
+ // TTS, y disputársela sale más caro que decodificar en CPU.
+ execution_provider: "cpu".into(),
+ inter_threads: 2,
+ intra_threads: 4,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct LlmConfig {
+ pub host: String,
+ pub port: u16,
+ pub model: String,
+ pub temperature: f32,
+ pub top_p: f32,
+ pub top_k: i32,
+ pub min_p: f32,
+ pub repeat_penalty: f32,
+ pub max_tokens: u32,
+ /// Vueltas máximas del bucle de herramientas antes de rendirse.
+ pub max_tool_rounds: usize,
+ pub request_timeout_secs: u64,
+}
+
+impl Default for LlmConfig {
+ fn default() -> Self {
+ Self {
+ host: "127.0.0.1".into(),
+ port: 8012,
+ model: String::new(),
+ temperature: 0.7,
+ top_p: 0.9,
+ top_k: 40,
+ min_p: 0.1,
+ repeat_penalty: 1.1,
+ // Una respuesta hablada larga cansa; el recorte también acota el
+ // coste de la síntesis, que es la etapa lenta.
+ max_tokens: 300,
+ max_tool_rounds: 4,
+ request_timeout_secs: 120,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct TtsConfig {
+ pub host: String,
+ pub port: u16,
+ /// Voz registrada en el servidor, o una del modelo.
+ pub voice: String,
+ /// Voz clonada que se registra al arrancar, si se define.
+ pub reference: Option<ReferenceVoice>,
+ pub language: String,
+ pub temperature: f32,
+ pub top_k: i32,
+ pub top_p: f32,
+ pub repetition_penalty: f32,
+ pub max_new_tokens: u32,
+ /// Sintetiza una frase corta al arrancar. La primera petición paga la
+ /// construcción de los grafos: ~3,5 s que conviene no gastar en el
+ /// primer turno real.
+ pub warmup: bool,
+ pub request_timeout_secs: u64,
+}
+
+impl Default for TtsConfig {
+ fn default() -> Self {
+ Self {
+ host: "127.0.0.1".into(),
+ port: 8013,
+ voice: "asistente".into(),
+ reference: None,
+ language: "spanish".into(),
+ temperature: 0.9,
+ top_k: 50,
+ top_p: 1.0,
+ repetition_penalty: 1.05,
+ max_new_tokens: 2048,
+ warmup: true,
+ request_timeout_secs: 180,
+ }
+ }
+}
+
+/// Latentes de una voz clonada, tal y como los produce `qwen-codec --talker`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ReferenceVoice {
+ /// Nombre con el que se registra en el servidor.
+ pub name: String,
+ /// Embedding del hablante (`.spk`).
+ pub speaker: PathBuf,
+ /// Códigos de referencia (`.rvq`), que activan el clonado ICL.
+ pub codes: PathBuf,
+ /// Transcripción de la referencia (`.txt`).
+ pub transcript: PathBuf,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct ToolsConfig {
+ /// Deja que el modelo llame a herramientas.
+ pub enabled: bool,
+ /// Usa `general.tools_prompt` en solitario para la pasada en que el
+ /// modelo decide si llamar a una herramienta, y `general.system_prompt`
+ /// sólo para redactar la respuesta hablada.
+ ///
+ /// Es lo único que hace que las herramientas funcionen de verdad con este
+ /// modelo (ver `tools_prompt`), a cambio de que las respuestas que no
+ /// usan herramienta pierdan la guía de estilo. Se compensa en parte
+ /// porque el limpiador de texto quita el markdown antes de hablar.
+ /// Ponlo a `false` para priorizar el estilo sobre las herramientas.
+ pub dedicated_prompt: bool,
+ /// Habilita la herramienta de ejecución de órdenes del sistema.
+ ///
+ /// Apagada por defecto a conciencia: darle una shell a un modelo que
+ /// obedece a lo que oye por el micrófono es un cambio de postura de
+ /// seguridad, no una opción de comodidad.
+ pub shell: bool,
+ /// Órdenes admitidas, comparadas contra el ejecutable (argv[0]).
+ /// Una lista vacía deniega todo aunque `shell` esté activo.
+ pub shell_allowlist: Vec<String>,
+ /// Segundos que puede durar una orden antes de que se la mate.
+ pub shell_timeout_secs: u64,
+ /// Registra la orden pero no la ejecuta. Útil para estrenar la lista blanca.
+ pub shell_dry_run: bool,
+ /// Directorio de trabajo de las órdenes; vacío = el del proceso.
+ pub shell_working_dir: String,
+}
+
+impl Default for ToolsConfig {
+ fn default() -> Self {
+ Self {
+ enabled: true,
+ dedicated_prompt: true,
+ shell: false,
+ shell_allowlist: vec![
+ "date".into(),
+ "uptime".into(),
+ "free".into(),
+ "df".into(),
+ "ls".into(),
+ ],
+ shell_timeout_secs: 10,
+ shell_dry_run: false,
+ shell_working_dir: String::new(),
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct SupervisorConfig {
+ /// Lanza los servidores en lugar de suponer que ya están arriba.
+ pub manage: bool,
+ /// Segundos de espera a que un servidor conteste a `/health`.
+ pub startup_timeout_secs: u64,
+ pub llama: LlamaProcess,
+ pub tts: TtsProcess,
+}
+
+impl Default for SupervisorConfig {
+ fn default() -> Self {
+ Self {
+ manage: true,
+ startup_timeout_secs: 180,
+ llama: LlamaProcess::default(),
+ tts: TtsProcess::default(),
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct LlamaProcess {
+ pub binary: PathBuf,
+ pub model: PathBuf,
+ pub mmproj: PathBuf,
+ /// Plantilla de chat que se pasa con `--chat-template-file`.
+ ///
+ /// La del modelo abre `<think>` sin cerrarlo nunca, y el asistente se pasa
+ /// entonces varios segundos razonando antes de decir la primera palabra.
+ /// Esta copia deja el bloque cerrado de entrada.
+ pub chat_template: PathBuf,
+ pub extra_args: Vec<String>,
+}
+
+impl Default for LlamaProcess {
+ fn default() -> Self {
+ Self {
+ binary: PathBuf::from("vendor/llama.cpp/build/bin/llama-server"),
+ model: PathBuf::from("models/Qwen3.5-2B.Q5_K_M.gguf"),
+ mmproj: PathBuf::from("models/mmproj-BF16.gguf"),
+ chat_template: PathBuf::from("config/qwen35-no-think.jinja"),
+ extra_args: [
+ "--threads",
+ "10",
+ "--threads-batch",
+ "10",
+ "--batch-size",
+ "512",
+ "--ubatch-size",
+ "256",
+ "--gpu-layers",
+ "10",
+ "--split-mode",
+ "layer",
+ "--tensor-split",
+ "1",
+ "--main-gpu",
+ "0",
+ "--no-mmap",
+ "--ctx-size",
+ "8192",
+ "--parallel",
+ "2",
+ "--cache-ram",
+ "6144",
+ "--rope-freq-base",
+ "1000000",
+ "--rope-freq-scale",
+ "0.25",
+ "--jinja",
+ ]
+ .iter()
+ .map(|s| s.to_string())
+ .collect(),
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct TtsProcess {
+ pub binary: PathBuf,
+ pub model: PathBuf,
+ pub codec: PathBuf,
+ /// Segundos de audio que el codec acumula antes de decodificar un bloque.
+ ///
+ /// El valor de fábrica son 24 s, que en la práctica significa «no
+ /// devuelvas nada hasta terminar la frase entera»: medido, baja el primer
+ /// audio de 4,9 s a 0,6 s. Es el ajuste con más efecto de todo el sistema.
+ pub codec_chunk_dur: f32,
+ pub extra_args: Vec<String>,
+}
+
+impl Default for TtsProcess {
+ fn default() -> Self {
+ Self {
+ binary: PathBuf::from("vendor/qwentts.cpp/build/tts-server"),
+ model: PathBuf::from("models/qwen-talker-1.7b-base-Q8_0.gguf"),
+ codec: PathBuf::from("models/qwen-tokenizer-12hz-Q8_0.gguf"),
+ codec_chunk_dur: 1.0,
+ extra_args: Vec::new(),
+ }
+ }
+}
+
+impl Config {
+ pub fn load(path: impl AsRef<Path>) -> Result<Self> {
+ let path = path.as_ref();
+ let raw = std::fs::read_to_string(path)
+ .map_err(|e| Error::Config(format!("no se pudo leer {}: {e}", path.display())))?;
+ let mut config: Config =
+ toml::from_str(&raw).map_err(|e| Error::Config(format!("{}: {e}", path.display())))?;
+ // Las rutas relativas se resuelven contra la carpeta del TOML, no
+ // contra el directorio desde el que se lanza el binario.
+ if let Some(base) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
+ config.rebase(base);
+ }
+ config.validate()?;
+ Ok(config)
+ }
+
+ /// Reinterpreta las rutas relativas respecto de `base`.
+ pub fn rebase(&mut self, base: &Path) {
+ let fix = |p: &mut PathBuf| {
+ if p.is_relative() {
+ *p = base.join(&*p);
+ }
+ };
+ fix(&mut self.asr.model_dir);
+ fix(&mut self.supervisor.llama.binary);
+ fix(&mut self.supervisor.llama.model);
+ fix(&mut self.supervisor.llama.mmproj);
+ fix(&mut self.supervisor.llama.chat_template);
+ fix(&mut self.supervisor.tts.binary);
+ fix(&mut self.supervisor.tts.model);
+ fix(&mut self.supervisor.tts.codec);
+ if let Some(reference) = self.tts.reference.as_mut() {
+ fix(&mut reference.speaker);
+ fix(&mut reference.codes);
+ fix(&mut reference.transcript);
+ }
+ }
+
+ fn validate(&self) -> Result<()> {
+ if self.vad.silence_hold <= 0.0 {
+ return Err(Error::Config("vad.silence_hold debe ser > 0".into()));
+ }
+ if self.vad.min_utterance >= self.vad.max_utterance {
+ return Err(Error::Config(
+ "vad.min_utterance debe ser menor que vad.max_utterance".into(),
+ ));
+ }
+ if self.asr.step <= 0.0 || self.asr.window <= self.asr.step {
+ return Err(Error::Config(
+ "asr.window debe ser mayor que asr.step, y ambos > 0".into(),
+ ));
+ }
+ if self.tools.shell && self.tools.shell_allowlist.is_empty() {
+ return Err(Error::Config(
+ "tools.shell está activo pero tools.shell_allowlist está vacía: \
+ declara las órdenes permitidas o desactiva tools.shell"
+ .into(),
+ ));
+ }
+ Ok(())
+ }
+
+ pub fn llm_authority(&self) -> String {
+ format!("{}:{}", self.llm.host, self.llm.port)
+ }
+
+ pub fn tts_authority(&self) -> String {
+ format!("{}:{}", self.tts.host, self.tts.port)
+ }
+}
diff --git a/crates/asist-core/src/error.rs b/crates/asist-core/src/error.rs
new file mode 100644
index 0000000..b559bee
--- /dev/null
+++ b/crates/asist-core/src/error.rs
@@ -0,0 +1,82 @@
+use std::fmt;
+
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Un fallo de una etapa del pipeline. El orquestador decide si es fatal o si
+/// basta con abortar el turno en curso, así que el error lleva esa distinción
+/// en lugar de dejarla al criterio de quien lo recibe.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ #[error("configuración inválida: {0}")]
+ Config(String),
+
+ #[error("audio: {0}")]
+ Audio(String),
+
+ #[error("ASR: {0}")]
+ Asr(String),
+
+ #[error("LLM: {0}")]
+ Llm(String),
+
+ #[error("TTS: {0}")]
+ Tts(String),
+
+ #[error("HTTP {status} en {url}: {body}")]
+ Http {
+ status: u16,
+ url: String,
+ body: String,
+ },
+
+ #[error("transporte hacia {url}: {source}")]
+ Transport {
+ url: String,
+ #[source]
+ source: std::io::Error,
+ },
+
+ #[error("herramienta «{tool}»: {message}")]
+ Tool { tool: String, message: String },
+
+ #[error("operación cancelada")]
+ Cancelled,
+
+ #[error(transparent)]
+ Json(#[from] serde_json::Error),
+
+ #[error(transparent)]
+ Io(#[from] std::io::Error),
+}
+
+impl Error {
+ /// Un error fatal tumba el asistente; el resto sólo aborta el turno.
+ ///
+ /// Los servidores locales se caen y se reinician, y el usuario prefiere
+ /// oír «no te he entendido» a que el proceso muera, así que sólo la
+ /// configuración y el audio (que no se pueden reintentar) son fatales.
+ pub fn is_fatal(&self) -> bool {
+ matches!(self, Error::Config(_) | Error::Audio(_))
+ }
+
+ /// `true` cuando reintentar tiene sentido: el servidor aún está cargando
+ /// el modelo, o se ha caído la conexión a mitad de una petición.
+ pub fn is_retryable(&self) -> bool {
+ match self {
+ Error::Transport { .. } => true,
+ Error::Http { status, .. } => *status == 503 || *status == 429 || *status >= 500,
+ _ => false,
+ }
+ }
+}
+
+/// Contexto legible para los `Result` que cruzan una frontera de crate.
+pub trait Context<T> {
+ fn ctx(self, f: impl FnOnce() -> String) -> Result<T>;
+}
+
+impl<T, E: fmt::Display> Context<T> for std::result::Result<T, E> {
+ fn ctx(self, f: impl FnOnce() -> String) -> Result<T> {
+ self.map_err(|e| Error::Config(format!("{}: {}", f(), e)))
+ }
+}
diff --git a/crates/asist-core/src/event.rs b/crates/asist-core/src/event.rs
new file mode 100644
index 0000000..549bec0
--- /dev/null
+++ b/crates/asist-core/src/event.rs
@@ -0,0 +1,127 @@
+use std::time::{Duration, Instant};
+
+/// Identifica un turno de conversación (una intervención del usuario y la
+/// respuesta que provoca). Todo lo que viaja por el bus lo lleva, para que un
+/// resultado que llega tarde no se confunda con el turno que ya está en curso
+/// —el caso típico cuando el usuario interrumpe al asistente.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
+pub struct TurnId(pub u64);
+
+impl std::fmt::Display for TurnId {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ write!(f, "#{}", self.0)
+ }
+}
+
+/// Motivo por el que se corta la reproducción en curso.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InterruptReason {
+ /// El usuario ha empezado a hablar encima del asistente (barge-in).
+ UserSpoke,
+ /// Petición explícita: tecla, señal o cierre.
+ Requested,
+}
+
+/// Todo lo que las etapas se cuentan entre sí. Un único enum mantiene el bus
+/// observable: el renderizador y la telemetría ven exactamente los mismos
+/// eventos que el orquestador, sin canales paralelos que se desincronicen.
+#[derive(Debug, Clone)]
+pub enum Event {
+ /// El VAD ha detectado el arranque de una intervención.
+ SpeechStarted { turn: TurnId, at: Instant },
+
+ /// Transcripción provisional de la ventana deslizante: `committed` ya es
+ /// estable, `volatile` todavía puede cambiar.
+ Partial {
+ turn: TurnId,
+ committed: String,
+ volatile: String,
+ },
+
+ /// Transcripción definitiva de la intervención completa.
+ Transcript {
+ turn: TurnId,
+ text: String,
+ audio_secs: f32,
+ decode: Duration,
+ },
+
+ /// La intervención no contenía nada transcribible.
+ Discarded { turn: TurnId },
+
+ /// Primer fragmento de texto que devuelve el modelo.
+ ReplyStarted { turn: TurnId, ttft: Duration },
+
+ /// Un trozo de respuesta según llega del modelo.
+ ReplyDelta { turn: TurnId, text: String },
+
+ /// Una frase completa lista para sintetizar.
+ Sentence {
+ turn: TurnId,
+ index: usize,
+ text: String,
+ },
+
+ /// Respuesta completa del modelo para este turno.
+ ReplyDone { turn: TurnId, text: String },
+
+ /// El modelo ha pedido ejecutar una herramienta.
+ ToolRequested {
+ turn: TurnId,
+ name: String,
+ arguments: String,
+ },
+
+ /// Resultado de esa ejecución.
+ ToolFinished {
+ turn: TurnId,
+ name: String,
+ ok: bool,
+ output: String,
+ took: Duration,
+ },
+
+ /// Primer audio audible del turno: la métrica que de verdad percibe quien habla.
+ AudioStarted { turn: TurnId, latency: Duration },
+
+ /// Se ha terminado de reproducir todo lo del turno.
+ AudioFinished { turn: TurnId },
+
+ /// Se ha cortado la reproducción.
+ Interrupted {
+ turn: TurnId,
+ reason: InterruptReason,
+ },
+
+ /// Aviso no fatal; el turno continúa.
+ Warning { turn: TurnId, message: String },
+
+ /// Fallo que aborta el turno.
+ Failed { turn: TurnId, message: String },
+
+ /// Cierre ordenado.
+ Shutdown,
+}
+
+impl Event {
+ pub fn turn(&self) -> Option<TurnId> {
+ match self {
+ Event::SpeechStarted { turn, .. }
+ | Event::Partial { turn, .. }
+ | Event::Transcript { turn, .. }
+ | Event::Discarded { turn }
+ | Event::ReplyStarted { turn, .. }
+ | Event::ReplyDelta { turn, .. }
+ | Event::Sentence { turn, .. }
+ | Event::ReplyDone { turn, .. }
+ | Event::ToolRequested { turn, .. }
+ | Event::ToolFinished { turn, .. }
+ | Event::AudioStarted { turn, .. }
+ | Event::AudioFinished { turn }
+ | Event::Interrupted { turn, .. }
+ | Event::Warning { turn, .. }
+ | Event::Failed { turn, .. } => Some(*turn),
+ Event::Shutdown => None,
+ }
+ }
+}
diff --git a/crates/asist-core/src/http.rs b/crates/asist-core/src/http.rs
new file mode 100644
index 0000000..32b6680
--- /dev/null
+++ b/crates/asist-core/src/http.rs
@@ -0,0 +1,351 @@
+//! Cliente HTTP/1.1 mínimo para hablar con los servidores locales.
+//!
+//! Los tres motores (llama-server, tts-server) escuchan en localhost sobre HTTP
+//! plano, así que no hace falta TLS ni un runtime asíncrono. A cambio de las
+//! ~300 líneas de aquí se gana lo único que ninguna librería genérica da
+//! cómodo y que este pipeline necesita de verdad: **abortar una respuesta a
+//! media descarga**. Cuando el usuario interrumpe al asistente hay que dejar de
+//! leer audio ya generado y cerrar el socket en ese mismo instante; con un
+//! cliente que sólo expone `read_to_end` eso no se puede hacer.
+
+use std::io::{BufRead, BufReader, Read, Write};
+use std::net::TcpStream;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use crate::error::{Error, Result};
+
+/// Bandera compartida que aborta una lectura en curso.
+///
+/// Se comprueba entre bloques, así que el corte ocurre como muy tarde un
+/// `read` después de activarla —del orden de milisegundos con los tamaños de
+/// bloque que usan los servidores.
+#[derive(Clone, Default)]
+pub struct Cancel(Arc<AtomicBool>);
+
+impl Cancel {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub fn cancel(&self) {
+ self.0.store(true, Ordering::SeqCst);
+ }
+
+ pub fn is_cancelled(&self) -> bool {
+ self.0.load(Ordering::SeqCst)
+ }
+
+ pub fn reset(&self) {
+ self.0.store(false, Ordering::SeqCst);
+ }
+}
+
+#[derive(Clone, Debug)]
+pub struct HttpClient {
+ /// `host:puerto` del servidor local.
+ pub authority: String,
+ pub connect_timeout: Duration,
+ /// Tiempo máximo sin recibir un solo byte. No es el tiempo total: una
+ /// síntesis larga puede tardar minutos siempre que siga fluyendo.
+ pub read_timeout: Duration,
+}
+
+impl HttpClient {
+ pub fn new(authority: impl Into<String>) -> Self {
+ Self {
+ authority: authority.into(),
+ connect_timeout: Duration::from_secs(5),
+ read_timeout: Duration::from_secs(120),
+ }
+ }
+
+ pub fn with_read_timeout(mut self, timeout: Duration) -> Self {
+ self.read_timeout = timeout;
+ self
+ }
+
+ fn connect(&self, path: &str) -> Result<TcpStream> {
+ let addr = resolve(&self.authority, path)?;
+ let stream = TcpStream::connect_timeout(&addr, self.connect_timeout).map_err(|e| {
+ Error::Transport {
+ url: format!("http://{}{}", self.authority, path),
+ source: e,
+ }
+ })?;
+ stream.set_read_timeout(Some(self.read_timeout))?;
+ // Los cuerpos son pequeños y la latencia manda: nada de Nagle.
+ let _ = stream.set_nodelay(true);
+ Ok(stream)
+ }
+
+ fn send(&self, method: &str, path: &str, body: Option<&[u8]>) -> Result<Response> {
+ let mut stream = self.connect(path)?;
+ let mut head = format!(
+ "{method} {path} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\nAccept: */*\r\n",
+ self.authority
+ );
+ if let Some(body) = body {
+ head.push_str("Content-Type: application/json\r\n");
+ head.push_str(&format!("Content-Length: {}\r\n", body.len()));
+ }
+ head.push_str("\r\n");
+
+ let url = format!("http://{}{}", self.authority, path);
+ let io = |e: std::io::Error| Error::Transport {
+ url: url.clone(),
+ source: e,
+ };
+ stream.write_all(head.as_bytes()).map_err(io)?;
+ if let Some(body) = body {
+ stream.write_all(body).map_err(io)?;
+ }
+ stream.flush().map_err(io)?;
+
+ Response::read_head(BufReader::new(stream), url)
+ }
+
+ /// GET que devuelve el cuerpo completo ya decodificado.
+ pub fn get(&self, path: &str) -> Result<Vec<u8>> {
+ self.send("GET", path, None)?.into_body()
+ }
+
+ /// POST de JSON que devuelve el cuerpo completo.
+ pub fn post_json(&self, path: &str, body: &serde_json::Value) -> Result<Vec<u8>> {
+ let payload = serde_json::to_vec(body)?;
+ self.send("POST", path, Some(&payload))?.into_body()
+ }
+
+ /// POST de JSON cuya respuesta se consume a trozos según llega.
+ ///
+ /// `on_chunk` recibe cada bloque en cuanto está disponible y devuelve
+ /// `false` para cortar; junto a `cancel` son las dos vías por las que el
+ /// barge-in detiene una síntesis a medias.
+ pub fn post_json_streaming(
+ &self,
+ path: &str,
+ body: &serde_json::Value,
+ cancel: &Cancel,
+ mut on_chunk: impl FnMut(&[u8]) -> bool,
+ ) -> Result<()> {
+ let payload = serde_json::to_vec(body)?;
+ let mut response = self.send("POST", path, Some(&payload))?;
+ response.error_for_status()?;
+ response.stream(cancel, &mut on_chunk)
+ }
+
+ /// POST de JSON que entrega la respuesta línea a línea (SSE de llama-server).
+ pub fn post_json_lines(
+ &self,
+ path: &str,
+ body: &serde_json::Value,
+ cancel: &Cancel,
+ mut on_line: impl FnMut(&str) -> bool,
+ ) -> Result<()> {
+ let mut pending = Vec::new();
+ self.post_json_streaming(path, body, cancel, |chunk| {
+ pending.extend_from_slice(chunk);
+ while let Some(nl) = pending.iter().position(|b| *b == b'\n') {
+ let line: Vec<u8> = pending.drain(..=nl).collect();
+ let line = String::from_utf8_lossy(&line);
+ if !on_line(line.trim_end_matches(['\r', '\n'])) {
+ return false;
+ }
+ }
+ true
+ })
+ }
+
+ /// Sondea `/health` y devuelve `true` si el servidor está listo.
+ pub fn healthy(&self, path: &str) -> bool {
+ self.get(path).is_ok()
+ }
+}
+
+fn resolve(authority: &str, path: &str) -> Result<std::net::SocketAddr> {
+ use std::net::ToSocketAddrs;
+ authority
+ .to_socket_addrs()
+ .map_err(|e| Error::Transport {
+ url: format!("http://{authority}{path}"),
+ source: e,
+ })?
+ .next()
+ .ok_or_else(|| Error::Config(format!("no se pudo resolver «{authority}»")))
+}
+
+/// Codificación del cuerpo anunciada por el servidor.
+enum Body {
+ Chunked,
+ Length(usize),
+ /// Sin longitud ni chunked: el cuerpo acaba cuando cierra el socket.
+ UntilClose,
+}
+
+pub struct Response {
+ pub status: u16,
+ url: String,
+ reader: BufReader<TcpStream>,
+ body: Body,
+}
+
+impl Response {
+ fn read_head(mut reader: BufReader<TcpStream>, url: String) -> Result<Self> {
+ let io = |e: std::io::Error| Error::Transport {
+ url: url.clone(),
+ source: e,
+ };
+
+ let mut line = String::new();
+ reader.read_line(&mut line).map_err(io)?;
+ let status = line
+ .split_whitespace()
+ .nth(1)
+ .and_then(|s| s.parse::<u16>().ok())
+ .ok_or_else(|| Error::Config(format!("respuesta HTTP ilegible de {url}: {line:?}")))?;
+
+ let mut body = Body::UntilClose;
+ loop {
+ let mut header = String::new();
+ if reader.read_line(&mut header).map_err(io)? == 0 {
+ break;
+ }
+ let header = header.trim_end();
+ if header.is_empty() {
+ break;
+ }
+ let Some((name, value)) = header.split_once(':') else {
+ continue;
+ };
+ let (name, value) = (name.trim().to_ascii_lowercase(), value.trim());
+ match name.as_str() {
+ "transfer-encoding" if value.eq_ignore_ascii_case("chunked") => {
+ body = Body::Chunked;
+ }
+ "content-length" => {
+ if let Ok(n) = value.parse() {
+ body = Body::Length(n);
+ }
+ }
+ _ => {}
+ }
+ }
+
+ Ok(Self {
+ status,
+ url,
+ reader,
+ body,
+ })
+ }
+
+ fn error_for_status(&mut self) -> Result<()> {
+ if (200..300).contains(&self.status) {
+ return Ok(());
+ }
+ let status = self.status;
+ let url = self.url.clone();
+ // Leer el cuerpo del error es lo que convierte un «500» en un mensaje útil.
+ let body = self.drain().unwrap_or_default();
+ Err(Error::Http {
+ status,
+ url,
+ body: String::from_utf8_lossy(&body).chars().take(500).collect(),
+ })
+ }
+
+ fn into_body(mut self) -> Result<Vec<u8>> {
+ self.error_for_status()?;
+ self.drain()
+ }
+
+ fn drain(&mut self) -> Result<Vec<u8>> {
+ let mut out = Vec::new();
+ let cancel = Cancel::new();
+ self.stream(&cancel, &mut |chunk| {
+ out.extend_from_slice(chunk);
+ true
+ })?;
+ Ok(out)
+ }
+
+ fn stream(&mut self, cancel: &Cancel, on_chunk: &mut dyn FnMut(&[u8]) -> bool) -> Result<()> {
+ let url = self.url.clone();
+ let io = |e: std::io::Error| Error::Transport {
+ url: url.clone(),
+ source: e,
+ };
+ let mut buf = vec![0u8; 16 * 1024];
+
+ match self.body {
+ Body::Chunked => loop {
+ if cancel.is_cancelled() {
+ return Err(Error::Cancelled);
+ }
+ let mut size_line = String::new();
+ if self.reader.read_line(&mut size_line).map_err(io)? == 0 {
+ return Ok(());
+ }
+ let size_line = size_line.trim();
+ if size_line.is_empty() {
+ continue;
+ }
+ // Las extensiones de chunk van tras un ';' y aquí no interesan.
+ let size =
+ usize::from_str_radix(size_line.split(';').next().unwrap_or("0").trim(), 16)
+ .map_err(|_| {
+ Error::Config(format!("tamaño de chunk ilegible: {size_line:?}"))
+ })?;
+ if size == 0 {
+ return Ok(());
+ }
+ let mut left = size;
+ while left > 0 {
+ if cancel.is_cancelled() {
+ return Err(Error::Cancelled);
+ }
+ let want = left.min(buf.len());
+ self.reader.read_exact(&mut buf[..want]).map_err(io)?;
+ if !on_chunk(&buf[..want]) {
+ return Err(Error::Cancelled);
+ }
+ left -= want;
+ }
+ // CRLF de cierre del chunk.
+ let mut crlf = [0u8; 2];
+ self.reader.read_exact(&mut crlf).map_err(io)?;
+ },
+ Body::Length(total) => {
+ let mut left = total;
+ while left > 0 {
+ if cancel.is_cancelled() {
+ return Err(Error::Cancelled);
+ }
+ let want = left.min(buf.len());
+ let n = self.reader.read(&mut buf[..want]).map_err(io)?;
+ if n == 0 {
+ return Ok(());
+ }
+ if !on_chunk(&buf[..n]) {
+ return Err(Error::Cancelled);
+ }
+ left -= n;
+ }
+ Ok(())
+ }
+ Body::UntilClose => loop {
+ if cancel.is_cancelled() {
+ return Err(Error::Cancelled);
+ }
+ let n = self.reader.read(&mut buf).map_err(io)?;
+ if n == 0 {
+ return Ok(());
+ }
+ if !on_chunk(&buf[..n]) {
+ return Err(Error::Cancelled);
+ }
+ },
+ }
+ }
+}
diff --git a/crates/asist-core/src/lib.rs b/crates/asist-core/src/lib.rs
new file mode 100644
index 0000000..db3ebfb
--- /dev/null
+++ b/crates/asist-core/src/lib.rs
@@ -0,0 +1,17 @@
+//! Tipos, configuración y utilidades compartidas por todo el asistente.
+//!
+//! Este crate no habla con ningún motor: sólo define el vocabulario común
+//! (eventos, errores, configuración, métricas) y las dos piezas de
+//! infraestructura que los demás crates necesitan: un cliente HTTP mínimo
+//! para hablar con los servidores locales, y el registro de herramientas.
+
+pub mod config;
+pub mod error;
+pub mod event;
+pub mod http;
+pub mod telemetry;
+pub mod text;
+pub mod tools;
+
+pub use error::{Error, Result};
+pub use event::{Event, TurnId};
diff --git a/crates/asist-core/src/telemetry.rs b/crates/asist-core/src/telemetry.rs
new file mode 100644
index 0000000..964aaa6
--- /dev/null
+++ b/crates/asist-core/src/telemetry.rs
@@ -0,0 +1,255 @@
+//! Medición de latencia por turno.
+//!
+//! El objetivo no es un histograma bonito sino contestar a una pregunta
+//! concreta cada vez que el asistente responde: *¿quién se ha comido el
+//! tiempo?* Por eso se marcan los cinco instantes que separan las etapas y se
+//! imprime el desglose, en lugar de un único total que no dice dónde mirar.
+
+use std::collections::BTreeMap;
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use crate::event::TurnId;
+
+/// Etapas del pipeline, en el orden en que ocurren.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Stage {
+ /// Del final del habla a la transcripción definitiva.
+ Asr,
+ /// De la transcripción al primer fragmento de texto del modelo.
+ LlmFirstToken,
+ /// Del primer fragmento a la respuesta completa.
+ LlmRest,
+ /// Ejecución de herramientas.
+ Tools,
+ /// De la primera frase al primer audio recibido.
+ TtsFirstAudio,
+ /// Síntesis del resto del turno.
+ TtsRest,
+ /// Del final del habla al primer audio: lo que de verdad se percibe.
+ PerceivedLatency,
+}
+
+impl Stage {
+ pub fn label(self) -> &'static str {
+ match self {
+ Stage::Asr => "asr.final",
+ Stage::LlmFirstToken => "llm.primer_token",
+ Stage::LlmRest => "llm.resto",
+ Stage::Tools => "herramientas",
+ Stage::TtsFirstAudio => "tts.primer_audio",
+ Stage::TtsRest => "tts.resto",
+ Stage::PerceivedLatency => "LATENCIA PERCIBIDA",
+ }
+ }
+}
+
+/// Cronómetro de un turno. Se rellena a medida que el turno avanza y se
+/// vuelca de una vez al terminar.
+#[derive(Debug)]
+pub struct TurnTimer {
+ pub turn: TurnId,
+ started: Instant,
+ marks: BTreeMap<Stage, Duration>,
+ /// Segundos de audio hablados por el usuario, para calcular el RTF del ASR.
+ pub input_secs: f32,
+ /// Segundos de audio sintetizados, para el RTF del TTS.
+ pub output_secs: f32,
+ pub sentences: usize,
+ pub tool_calls: usize,
+}
+
+impl TurnTimer {
+ pub fn new(turn: TurnId) -> Self {
+ Self {
+ turn,
+ started: Instant::now(),
+ marks: BTreeMap::new(),
+ input_secs: 0.0,
+ output_secs: 0.0,
+ sentences: 0,
+ tool_calls: 0,
+ }
+ }
+
+ /// Instante de referencia del turno: el fin del habla del usuario.
+ pub fn started(&self) -> Instant {
+ self.started
+ }
+
+ pub fn record(&mut self, stage: Stage, took: Duration) {
+ // Etapas que se repiten (una síntesis por frase) se acumulan; las que
+ // marcan un hito (primer audio) se quedan con la primera medida, que
+ // es la que describe la latencia de arranque.
+ match stage {
+ Stage::TtsFirstAudio | Stage::LlmFirstToken | Stage::PerceivedLatency => {
+ self.marks.entry(stage).or_insert(took);
+ }
+ _ => *self.marks.entry(stage).or_default() += took,
+ }
+ }
+
+ /// Marca una etapa con el tiempo transcurrido desde el inicio del turno.
+ pub fn mark_since_start(&mut self, stage: Stage) {
+ let took = self.started.elapsed();
+ self.record(stage, took);
+ }
+
+ pub fn get(&self, stage: Stage) -> Option<Duration> {
+ self.marks.get(&stage).copied()
+ }
+
+ pub fn total(&self) -> Duration {
+ self.started.elapsed()
+ }
+
+ /// Etapa que más ha tardado, excluyendo el total percibido (que las agrega).
+ pub fn bottleneck(&self) -> Option<(Stage, Duration)> {
+ self.marks
+ .iter()
+ .filter(|(stage, _)| **stage != Stage::PerceivedLatency)
+ .max_by_key(|(_, took)| **took)
+ .map(|(stage, took)| (*stage, *took))
+ }
+
+ /// Informe de una línea por etapa, con el cuello de botella señalado.
+ pub fn report(&self) -> String {
+ let mut out = format!("turno {} — desglose de latencia\n", self.turn);
+ let worst = self.bottleneck().map(|(stage, _)| stage);
+ for (stage, took) in &self.marks {
+ let flag = if Some(*stage) == worst {
+ " <== cuello de botella"
+ } else {
+ ""
+ };
+ out.push_str(&format!(
+ " {:<20} {:>8.0} ms{}\n",
+ stage.label(),
+ took.as_secs_f64() * 1000.0,
+ flag
+ ));
+ }
+ if self.input_secs > 0.0 {
+ if let Some(asr) = self.get(Stage::Asr) {
+ out.push_str(&format!(
+ " {:<20} {:>8.2} x tiempo real ({:.1} s de voz)\n",
+ "asr.rtf",
+ asr.as_secs_f32() / self.input_secs,
+ self.input_secs
+ ));
+ }
+ }
+ if self.output_secs > 0.0 {
+ let tts: Duration = self.get(Stage::TtsFirstAudio).unwrap_or_default()
+ + self.get(Stage::TtsRest).unwrap_or_default();
+ out.push_str(&format!(
+ " {:<20} {:>8.2} x tiempo real ({:.1} s de audio, {} frases)\n",
+ "tts.rtf",
+ tts.as_secs_f32() / self.output_secs,
+ self.output_secs,
+ self.sentences
+ ));
+ }
+ out.push_str(&format!(
+ " {:<20} {:>8.0} ms\n",
+ "total del turno",
+ self.total().as_secs_f64() * 1000.0
+ ));
+ out
+ }
+}
+
+/// Agregado de todos los turnos de la sesión, para el resumen del cierre.
+#[derive(Debug, Default)]
+pub struct Metrics {
+ inner: Mutex<MetricsInner>,
+}
+
+#[derive(Debug, Default)]
+struct MetricsInner {
+ turns: usize,
+ totals: BTreeMap<Stage, (Duration, usize)>,
+}
+
+impl Metrics {
+ pub fn record_turn(&self, timer: &TurnTimer) {
+ let mut inner = self.inner.lock().unwrap_or_else(|e| e.into_inner());
+ inner.turns += 1;
+ for (stage, took) in &timer.marks {
+ let entry = inner.totals.entry(*stage).or_default();
+ entry.0 += *took;
+ entry.1 += 1;
+ }
+ }
+
+ pub fn turns(&self) -> usize {
+ self.inner.lock().unwrap_or_else(|e| e.into_inner()).turns
+ }
+
+ /// Media por etapa sobre toda la sesión.
+ pub fn summary(&self) -> String {
+ let inner = self.inner.lock().unwrap_or_else(|e| e.into_inner());
+ if inner.turns == 0 {
+ return "sin turnos completados\n".into();
+ }
+ let mut out = format!("resumen de {} turno(s) — media por etapa\n", inner.turns);
+ for (stage, (total, count)) in &inner.totals {
+ out.push_str(&format!(
+ " {:<20} {:>8.0} ms\n",
+ stage.label(),
+ total.as_secs_f64() * 1000.0 / *count as f64
+ ));
+ }
+ out
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn el_cuello_de_botella_es_la_etapa_mas_lenta() {
+ let mut timer = TurnTimer::new(TurnId(1));
+ timer.record(Stage::Asr, Duration::from_millis(300));
+ timer.record(Stage::LlmFirstToken, Duration::from_millis(500));
+ timer.record(Stage::TtsFirstAudio, Duration::from_millis(900));
+ assert_eq!(timer.bottleneck().unwrap().0, Stage::TtsFirstAudio);
+ }
+
+ #[test]
+ fn la_latencia_percibida_no_compite_como_cuello_de_botella() {
+ let mut timer = TurnTimer::new(TurnId(1));
+ timer.record(Stage::Asr, Duration::from_millis(300));
+ timer.record(Stage::PerceivedLatency, Duration::from_secs(9));
+ assert_eq!(timer.bottleneck().unwrap().0, Stage::Asr);
+ }
+
+ #[test]
+ fn las_etapas_repetidas_se_acumulan_y_los_hitos_no() {
+ let mut timer = TurnTimer::new(TurnId(1));
+ timer.record(Stage::TtsRest, Duration::from_millis(100));
+ timer.record(Stage::TtsRest, Duration::from_millis(150));
+ assert_eq!(timer.get(Stage::TtsRest), Some(Duration::from_millis(250)));
+
+ timer.record(Stage::TtsFirstAudio, Duration::from_millis(600));
+ timer.record(Stage::TtsFirstAudio, Duration::from_millis(50));
+ assert_eq!(
+ timer.get(Stage::TtsFirstAudio),
+ Some(Duration::from_millis(600)),
+ "el primer audio describe el arranque; una frase posterior no debe rebajarlo"
+ );
+ }
+
+ #[test]
+ fn el_resumen_promedia_entre_turnos() {
+ let metrics = Metrics::default();
+ for ms in [100, 300] {
+ let mut timer = TurnTimer::new(TurnId(1));
+ timer.record(Stage::Asr, Duration::from_millis(ms));
+ metrics.record_turn(&timer);
+ }
+ assert_eq!(metrics.turns(), 2);
+ assert!(metrics.summary().contains("200 ms"));
+ }
+}
diff --git a/crates/asist-core/src/text.rs b/crates/asist-core/src/text.rs
new file mode 100644
index 0000000..e799561
--- /dev/null
+++ b/crates/asist-core/src/text.rs
@@ -0,0 +1,330 @@
+//! Preparación del texto que va a leerse en voz alta.
+//!
+//! Dos problemas distintos, ambos en el camino crítico de la latencia:
+//!
+//! 1. **Trocear en frases mientras el modelo escribe.** Esperar a la respuesta
+//! completa antes de sintetizar suma el tiempo del LLM al del TTS. Cortando
+//! por frases, el asistente empieza a hablar mientras sigue pensando.
+//! 2. **Quitar lo que no se pronuncia.** El sintetizador lee los asteriscos y
+//! las almohadillas tal cual, así que el markdown que se le escapa al modelo
+//! hay que limpiarlo antes.
+
+/// Trocea un flujo de texto en frases pronunciables.
+///
+/// La primera frase sale en cuanto es mínimamente decente y las siguientes
+/// esperan a tener más cuerpo: el arranque manda en la latencia percibida,
+/// pero una vez que suena la voz, las frases largas se entonan mejor.
+#[derive(Debug)]
+pub struct SentenceSplitter {
+ buffer: String,
+ emitted: usize,
+ /// Longitud mínima de la primera frase.
+ first_min: usize,
+ /// Longitud mínima de las siguientes.
+ rest_min: usize,
+ /// Longitud a partir de la cual se corta aunque no haya puntuación, para
+ /// que un modelo que no puntúa no deje al asistente mudo.
+ hard_max: usize,
+}
+
+impl Default for SentenceSplitter {
+ fn default() -> Self {
+ Self {
+ buffer: String::new(),
+ emitted: 0,
+ first_min: 12,
+ rest_min: 40,
+ hard_max: 240,
+ }
+ }
+}
+
+impl SentenceSplitter {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub fn with_limits(first_min: usize, rest_min: usize, hard_max: usize) -> Self {
+ Self {
+ first_min,
+ rest_min,
+ hard_max,
+ ..Self::default()
+ }
+ }
+
+ pub fn emitted(&self) -> usize {
+ self.emitted
+ }
+
+ /// Añade texto recién llegado y devuelve las frases que ya están completas.
+ pub fn push(&mut self, delta: &str) -> Vec<String> {
+ self.buffer.push_str(delta);
+ let mut out = Vec::new();
+ while let Some(sentence) = self.take_ready() {
+ out.push(sentence);
+ }
+ out
+ }
+
+ /// Entrega lo que quede al terminar la respuesta.
+ pub fn flush(&mut self) -> Option<String> {
+ let rest = clean_for_speech(&std::mem::take(&mut self.buffer));
+ if !is_speakable(&rest) {
+ return None;
+ }
+ self.emitted += 1;
+ Some(rest)
+ }
+
+ fn min_len(&self) -> usize {
+ if self.emitted == 0 {
+ self.first_min
+ } else {
+ self.rest_min
+ }
+ }
+
+ fn take_ready(&mut self) -> Option<String> {
+ let cut = self.boundary()?;
+ let head: String = self.buffer.drain(..cut).collect();
+ let head = clean_for_speech(&head);
+ if !is_speakable(&head) {
+ // Sólo era puntuación o markdown: se descarta sin gastar un turno
+ // de síntesis, pero el corte ya se ha consumido.
+ return self.take_ready();
+ }
+ self.emitted += 1;
+ Some(head)
+ }
+
+ /// Índice de byte por el que cortar, si hay alguno.
+ fn boundary(&self) -> Option<usize> {
+ let min = self.min_len();
+ let mut last_soft = None;
+
+ for (i, c) in self.buffer.char_indices() {
+ let end = i + c.len_utf8();
+ if end < min {
+ continue;
+ }
+ if is_terminator(c) {
+ // El punto de una abreviatura o de un decimal no cierra frase.
+ if c == '.' && !ends_sentence(&self.buffer, i) {
+ continue;
+ }
+ // Sólo cierra si viene un espacio detrás, o si ya no queda
+ // nada: si no, se estaría cortando a mitad de «3.14».
+ match self.buffer[end..].chars().next() {
+ Some(next) if next.is_whitespace() => return Some(end),
+ None => {}
+ Some(_) => continue,
+ }
+ }
+ // Una coma o un punto y coma valen como corte de emergencia si la
+ // frase ya se ha pasado de largo.
+ if matches!(c, ',' | ';' | ':') {
+ last_soft = Some(end);
+ }
+ if end >= self.hard_max {
+ return Some(last_soft.unwrap_or(end));
+ }
+ }
+ None
+ }
+}
+
+/// ¿Hay algo que pronunciar?
+///
+/// Un fragmento que sólo tiene puntuación —lo que queda al limpiar un «**» o
+/// unos puntos suspensivos sueltos— cuesta una síntesis entera y no suena a
+/// nada, así que no llega a salir del troceador.
+pub fn is_speakable(text: &str) -> bool {
+ text.chars().any(char::is_alphanumeric)
+}
+
+fn is_terminator(c: char) -> bool {
+ matches!(c, '.' | '!' | '?' | '…' | '\n')
+}
+
+/// ¿El punto en `idx` cierra frase de verdad?
+///
+/// Descarta decimales («3.14»), elipsis a medio escribir y las abreviaturas
+/// más comunes en español, que si no parten la frase justo antes del nombre.
+fn ends_sentence(text: &str, idx: usize) -> bool {
+ let before = &text[..idx];
+ let after = &text[idx + 1..];
+
+ if after.starts_with(|c: char| c.is_ascii_digit())
+ && before.ends_with(|c: char| c.is_ascii_digit())
+ {
+ return false;
+ }
+ if after.starts_with('.') || before.ends_with('.') {
+ return false;
+ }
+ let word = before
+ .rsplit(|c: char| c.is_whitespace())
+ .next()
+ .unwrap_or("")
+ .to_lowercase();
+ const ABREVIATURAS: &[&str] = &[
+ "sr", "sra", "srta", "dr", "dra", "ud", "uds", "etc", "ej", "p.ej", "av", "núm", "num",
+ "pág", "pag", "vol", "art", "ap", "aprox", "ee.uu", "d", "dña",
+ ];
+ !ABREVIATURAS.contains(&word.as_str())
+}
+
+/// Deja el texto listo para el sintetizador.
+///
+/// Se limita a quitar lo que no se pronuncia; no reescribe ni resume, porque
+/// lo que suena tiene que ser lo que el modelo dijo.
+pub fn clean_for_speech(text: &str) -> String {
+ let mut out = String::with_capacity(text.len());
+ let mut chars = text.chars().peekable();
+ let mut at_line_start = true;
+
+ while let Some(c) = chars.next() {
+ match c {
+ // Énfasis y código: los delimitadores se leerían en voz alta.
+ '*' | '_' | '`' | '~' => continue,
+ // Encabezados y viñetas, sólo al principio de línea: una
+ // almohadilla o un guion en mitad de una frase sí significan algo.
+ '#' if at_line_start => {
+ while chars.peek() == Some(&'#') {
+ chars.next();
+ }
+ while chars.peek().is_some_and(|c| *c == ' ') {
+ chars.next();
+ }
+ continue;
+ }
+ '-' | '•' | '–' if at_line_start && chars.peek() == Some(&' ') => {
+ chars.next();
+ continue;
+ }
+ '>' if at_line_start => {
+ while chars.peek().is_some_and(|c| *c == ' ') {
+ chars.next();
+ }
+ continue;
+ }
+ // Los saltos de línea se hablan como pausas.
+ '\n' | '\r' | '\t' => {
+ at_line_start = c == '\n';
+ if !out.ends_with(' ') && !out.is_empty() {
+ out.push(' ');
+ }
+ continue;
+ }
+ _ => {}
+ }
+ at_line_start = false;
+ out.push(c);
+ }
+
+ // Colapsa los espacios que deja la limpieza.
+ let mut collapsed = String::with_capacity(out.len());
+ let mut space = false;
+ for c in out.chars() {
+ if c == ' ' {
+ space = true;
+ continue;
+ }
+ if space && !collapsed.is_empty() {
+ collapsed.push(' ');
+ }
+ space = false;
+ collapsed.push(c);
+ }
+ collapsed.trim().to_string()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn split_all(chunks: &[&str]) -> Vec<String> {
+ let mut splitter = SentenceSplitter::new();
+ let mut out: Vec<String> = chunks.iter().flat_map(|c| splitter.push(c)).collect();
+ out.extend(splitter.flush());
+ out
+ }
+
+ #[test]
+ fn la_primera_frase_sale_antes_que_las_siguientes() {
+ // La primera basta con que sea corta; la segunda espera a tener cuerpo.
+ let out = split_all(&["Claro que sí. ", "Vale. ", "Aún no.", ""]);
+ assert_eq!(out[0], "Claro que sí.");
+ assert_eq!(out[1], "Vale. Aún no.");
+ }
+
+ #[test]
+ fn trocea_segun_llegan_los_deltas() {
+ let mut splitter = SentenceSplitter::new();
+ assert!(splitter.push("Hola, ¿qué ").is_empty());
+ assert!(splitter.push("tal est").is_empty());
+ let out = splitter.push("ás hoy? ");
+ assert_eq!(out, vec!["Hola, ¿qué tal estás hoy?"]);
+ }
+
+ #[test]
+ fn el_punto_decimal_no_parte_la_frase() {
+ let out = split_all(&["El resultado es 3.1416 exactamente y nada más."]);
+ assert_eq!(out.len(), 1, "un decimal no cierra frase: {out:?}");
+ }
+
+ #[test]
+ fn las_abreviaturas_no_parten_la_frase() {
+ let out = split_all(&["Avisa al Sr. Pérez cuanto antes por favor."]);
+ assert_eq!(out.len(), 1, "«Sr.» no cierra frase: {out:?}");
+ }
+
+ #[test]
+ fn una_parrafada_sin_puntuacion_se_corta_igualmente() {
+ // Sin este corte de emergencia, un modelo que no puntúa deja al
+ // asistente sin sintetizar nada hasta el final de la respuesta.
+ let largo = "palabra ".repeat(60);
+ let out = split_all(&[&largo]);
+ assert!(out.len() > 1, "esperaba varios cortes, hubo {}", out.len());
+ assert!(out.iter().all(|s| s.len() <= 260));
+ }
+
+ #[test]
+ fn el_corte_de_emergencia_prefiere_una_coma() {
+ let mut splitter = SentenceSplitter::with_limits(4, 4, 40);
+ let out = splitter.push("uno dos tres, cuatro cinco seis siete ocho nueve diez once ");
+ assert_eq!(out[0], "uno dos tres,");
+ }
+
+ #[test]
+ fn se_limpia_el_markdown_que_se_leeria_en_voz_alta() {
+ assert_eq!(clean_for_speech("## Título"), "Título");
+ assert_eq!(
+ clean_for_speech("Esto es **muy** importante"),
+ "Esto es muy importante"
+ );
+ assert_eq!(clean_for_speech("- uno\n- dos"), "uno dos");
+ assert_eq!(clean_for_speech("usa `ls -la` ahora"), "usa ls -la ahora");
+ assert_eq!(clean_for_speech("> citado"), "citado");
+ }
+
+ #[test]
+ fn un_guion_dentro_de_la_frase_sobrevive() {
+ assert_eq!(clean_for_speech("teórico-práctico"), "teórico-práctico");
+ }
+
+ #[test]
+ fn los_fragmentos_solo_de_puntuacion_no_generan_sintesis() {
+ let out = split_all(&["**", "...", " "]);
+ assert!(out.is_empty(), "no había nada que pronunciar: {out:?}");
+ }
+
+ #[test]
+ fn el_flush_entrega_la_cola_sin_puntuacion_final() {
+ let mut splitter = SentenceSplitter::new();
+ splitter.push("Una frase sin punto final");
+ assert_eq!(splitter.flush().unwrap(), "Una frase sin punto final");
+ assert!(splitter.flush().is_none());
+ }
+}
diff --git a/crates/asist-core/src/tools.rs b/crates/asist-core/src/tools.rs
new file mode 100644
index 0000000..0b8a646
--- /dev/null
+++ b/crates/asist-core/src/tools.rs
@@ -0,0 +1,563 @@
+//! Herramientas que el modelo puede invocar.
+//!
+//! El punto de extensión del asistente. Una herramienta es un objeto que se
+//! describe a sí mismo en JSON Schema y sabe ejecutarse; el registro las
+//! traduce al formato `tools` de la API de chat y despacha las llamadas que
+//! vuelven. Añadir una capacidad nueva es implementar el trait y registrarla,
+//! sin tocar el orquestador.
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use serde_json::{json, Value};
+
+use crate::config::ToolsConfig;
+use crate::error::{Error, Result};
+
+/// Lo que el modelo puede pedir que se haga.
+pub trait Tool: Send + Sync {
+ /// Identificador que usa el modelo. En minúsculas y sin espacios.
+ fn name(&self) -> &str;
+
+ /// Para qué sirve. Lo lee el modelo, así que se escribe para él: concreto
+ /// y en la lengua de la conversación.
+ fn description(&self) -> &str;
+
+ /// JSON Schema de los argumentos.
+ fn parameters(&self) -> Value;
+
+ /// Ejecuta y devuelve el texto que se le entrega al modelo como resultado.
+ fn call(&self, args: &Value) -> Result<String>;
+
+ /// `true` si la herramienta cambia algo fuera del proceso. El orquestador
+ /// lo anuncia en voz alta antes de ejecutarla.
+ fn is_side_effecting(&self) -> bool {
+ false
+ }
+}
+
+/// Una llamada tal y como la pide el modelo.
+#[derive(Debug, Clone)]
+pub struct ToolCall {
+ pub id: String,
+ pub name: String,
+ /// Argumentos en JSON, aún sin validar.
+ pub arguments: String,
+}
+
+/// Resultado de ejecutarla.
+#[derive(Debug, Clone)]
+pub struct ToolOutcome {
+ pub id: String,
+ pub name: String,
+ pub ok: bool,
+ pub output: String,
+ pub took: Duration,
+}
+
+#[derive(Default, Clone)]
+pub struct ToolRegistry {
+ tools: BTreeMap<String, Arc<dyn Tool>>,
+}
+
+impl ToolRegistry {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Monta el juego de herramientas que pide la configuración.
+ pub fn from_config(config: &ToolsConfig) -> Self {
+ let mut registry = Self::new();
+ if !config.enabled {
+ return registry;
+ }
+ registry.register(Arc::new(builtin::Clock));
+ if config.shell {
+ registry.register(Arc::new(builtin::Shell::new(config)));
+ }
+ registry
+ }
+
+ pub fn register(&mut self, tool: Arc<dyn Tool>) {
+ self.tools.insert(tool.name().to_string(), tool);
+ }
+
+ pub fn is_empty(&self) -> bool {
+ self.tools.is_empty()
+ }
+
+ pub fn names(&self) -> Vec<&str> {
+ self.tools.keys().map(String::as_str).collect()
+ }
+
+ pub fn get(&self, name: &str) -> Option<&Arc<dyn Tool>> {
+ self.tools.get(name)
+ }
+
+ /// Descripción en el formato `tools` de la API de chat de OpenAI, que es
+ /// el que habla llama-server.
+ pub fn schema(&self) -> Value {
+ Value::Array(
+ self.tools
+ .values()
+ .map(|tool| {
+ json!({
+ "type": "function",
+ "function": {
+ "name": tool.name(),
+ "description": tool.description(),
+ "parameters": tool.parameters(),
+ }
+ })
+ })
+ .collect(),
+ )
+ }
+
+ /// Ejecuta una llamada. Nunca propaga el error hacia arriba: un fallo de
+ /// herramienta se le devuelve al modelo como texto para que lo explique o
+ /// lo reintente, en vez de tumbar el turno.
+ pub fn dispatch(&self, call: &ToolCall) -> ToolOutcome {
+ let started = std::time::Instant::now();
+ let result = match self.tools.get(&call.name) {
+ None => Err(Error::Tool {
+ tool: call.name.clone(),
+ message: format!(
+ "no existe esa herramienta; disponibles: {}",
+ self.names().join(", ")
+ ),
+ }),
+ Some(tool) => serde_json::from_str::<Value>(&call.arguments)
+ .or_else(|_| {
+ // Los modelos pequeños mandan a veces la cadena vacía en
+ // lugar de «{}» cuando la función no lleva argumentos.
+ if call.arguments.trim().is_empty() {
+ Ok(json!({}))
+ } else {
+ Err(Error::Tool {
+ tool: call.name.clone(),
+ message: format!("argumentos JSON inválidos: {}", call.arguments),
+ })
+ }
+ })
+ .and_then(|args| tool.call(&args)),
+ };
+
+ let took = started.elapsed();
+ match result {
+ Ok(output) => ToolOutcome {
+ id: call.id.clone(),
+ name: call.name.clone(),
+ ok: true,
+ output,
+ took,
+ },
+ Err(err) => ToolOutcome {
+ id: call.id.clone(),
+ name: call.name.clone(),
+ ok: false,
+ output: format!("error: {err}"),
+ took,
+ },
+ }
+ }
+}
+
+pub mod builtin {
+ use super::*;
+ use std::process::{Command, Stdio};
+
+ /// Fecha y hora locales. Existe porque el modelo no las sabe y las inventa
+ /// con aplomo, y de paso sirve de ejemplo mínimo de herramienta.
+ pub struct Clock;
+
+ impl Tool for Clock {
+ fn name(&self) -> &str {
+ "hora_actual"
+ }
+
+ fn description(&self) -> &str {
+ "Devuelve la fecha y la hora locales del sistema. Úsala siempre que \
+ te pregunten qué hora o qué día es, en vez de suponerlo."
+ }
+
+ fn parameters(&self) -> Value {
+ json!({ "type": "object", "properties": {}, "required": [] })
+ }
+
+ fn call(&self, _args: &Value) -> Result<String> {
+ // `date` evita arrastrar una dependencia de calendario entera para
+ // una sola llamada, y respeta la zona horaria del sistema. Se le
+ // piden campos numéricos y los nombres se ponen aquí: `%A` y `%B`
+ // salen en el idioma de la locale, que en esta máquina es inglés,
+ // y el asistente acabaría diciendo «Sunday 6 de September».
+ let out = Command::new("date")
+ .arg("+%w %-d %-m %Y %H:%M")
+ .output()
+ .map_err(|e| Error::Tool {
+ tool: "hora_actual".into(),
+ message: e.to_string(),
+ })?;
+ let raw = String::from_utf8_lossy(&out.stdout);
+ format_spanish_date(raw.trim()).ok_or_else(|| Error::Tool {
+ tool: "hora_actual".into(),
+ message: format!("«date» devolvió algo inesperado: {raw:?}"),
+ })
+ }
+ }
+
+ pub(super) const DIAS: [&str; 7] = [
+ "domingo",
+ "lunes",
+ "martes",
+ "miércoles",
+ "jueves",
+ "viernes",
+ "sábado",
+ ];
+ const MESES: [&str; 12] = [
+ "enero",
+ "febrero",
+ "marzo",
+ "abril",
+ "mayo",
+ "junio",
+ "julio",
+ "agosto",
+ "septiembre",
+ "octubre",
+ "noviembre",
+ "diciembre",
+ ];
+
+ /// Compone «domingo 6 de septiembre de 2026, 19:13» a partir de
+ /// «0 6 9 2026 19:13».
+ pub(super) fn format_spanish_date(raw: &str) -> Option<String> {
+ let mut fields = raw.split_whitespace();
+ let weekday: usize = fields.next()?.parse().ok()?;
+ let day: u32 = fields.next()?.parse().ok()?;
+ let month: usize = fields.next()?.parse().ok()?;
+ let year: i32 = fields.next()?.parse().ok()?;
+ let time = fields.next()?;
+ Some(format!(
+ "{} {day} de {} de {year}, {time}",
+ DIAS.get(weekday)?,
+ MESES.get(month.checked_sub(1)?)?
+ ))
+ }
+
+ /// Ejecución de órdenes del sistema, restringida por lista blanca.
+ ///
+ /// Es la puerta por la que el asistente pasa de hablar a actuar, y también
+ /// la más delicada del proyecto: lo que llega aquí viene, en última
+ /// instancia, de lo que se oye por el micrófono. De ahí las cuatro
+ /// barreras: apagada por defecto, lista blanca sobre el ejecutable,
+ /// argumentos sin shell que los interprete, y un plazo máximo.
+ pub struct Shell {
+ allowlist: Vec<String>,
+ timeout: Duration,
+ dry_run: bool,
+ working_dir: String,
+ }
+
+ impl Shell {
+ pub fn new(config: &ToolsConfig) -> Self {
+ Self {
+ allowlist: config.shell_allowlist.clone(),
+ timeout: Duration::from_secs(config.shell_timeout_secs),
+ dry_run: config.shell_dry_run,
+ working_dir: config.shell_working_dir.clone(),
+ }
+ }
+
+ fn permitted(&self, program: &str) -> bool {
+ // Se compara sólo el nombre del ejecutable: dejar pasar rutas
+ // completas invitaría a colar «/tmp/ls».
+ !program.contains('/') && self.allowlist.iter().any(|a| a == program)
+ }
+ }
+
+ impl Tool for Shell {
+ fn name(&self) -> &str {
+ "ejecutar_comando"
+ }
+
+ fn description(&self) -> &str {
+ "Ejecuta una orden del sistema de una lista autorizada y devuelve su \
+ salida. Indica el programa y sus argumentos por separado. Si la \
+ orden no está autorizada, se rechaza."
+ }
+
+ fn parameters(&self) -> Value {
+ json!({
+ "type": "object",
+ "properties": {
+ "programa": {
+ "type": "string",
+ "description": "Nombre del ejecutable, sin ruta. Por ejemplo: date"
+ },
+ "argumentos": {
+ "type": "array",
+ "items": { "type": "string" },
+ "description": "Argumentos, uno por elemento. No uses tuberías ni redirecciones."
+ }
+ },
+ "required": ["programa"]
+ })
+ }
+
+ fn is_side_effecting(&self) -> bool {
+ true
+ }
+
+ fn call(&self, args: &Value) -> Result<String> {
+ let fail = |message: String| Error::Tool {
+ tool: "ejecutar_comando".into(),
+ message,
+ };
+
+ let program = args
+ .get("programa")
+ .and_then(Value::as_str)
+ .ok_or_else(|| fail("falta «programa»".into()))?;
+
+ let arguments: Vec<String> = match args.get("argumentos") {
+ None | Some(Value::Null) => Vec::new(),
+ Some(Value::Array(items)) => items
+ .iter()
+ .map(|v| match v {
+ Value::String(s) => Ok(s.clone()),
+ other => Ok(other.to_string()),
+ })
+ .collect::<Result<_>>()?,
+ // Algunos modelos mandan los argumentos en una sola cadena.
+ Some(Value::String(s)) => s.split_whitespace().map(String::from).collect(),
+ Some(other) => return Err(fail(format!("«argumentos» inválido: {other}"))),
+ };
+
+ if !self.permitted(program) {
+ return Err(fail(format!(
+ "«{program}» no está autorizada. Autorizadas: {}",
+ self.allowlist.join(", ")
+ )));
+ }
+
+ let rendered = format!("{program} {}", arguments.join(" "));
+ if self.dry_run {
+ return Ok(format!("[simulación] no se ejecutó: {}", rendered.trim()));
+ }
+
+ // Sin shell de por medio: los argumentos van al `execve` tal cual,
+ // así que un «; rm -rf /» es un argumento literal, no otra orden.
+ let mut command = Command::new(program);
+ command
+ .args(&arguments)
+ .stdin(Stdio::null())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::piped());
+ if !self.working_dir.is_empty() {
+ command.current_dir(&self.working_dir);
+ }
+
+ let mut child = command.spawn().map_err(|e| fail(e.to_string()))?;
+ let deadline = std::time::Instant::now() + self.timeout;
+ loop {
+ match child.try_wait().map_err(|e| fail(e.to_string()))? {
+ Some(_) => break,
+ None if std::time::Instant::now() >= deadline => {
+ let _ = child.kill();
+ let _ = child.wait();
+ return Err(fail(format!(
+ "«{}» superó el plazo de {} s y se detuvo",
+ rendered.trim(),
+ self.timeout.as_secs()
+ )));
+ }
+ None => std::thread::sleep(Duration::from_millis(20)),
+ }
+ }
+
+ let output = child.wait_with_output().map_err(|e| fail(e.to_string()))?;
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ let mut body = stdout.trim().to_string();
+ if body.is_empty() {
+ body = stderr.trim().to_string();
+ }
+ // La salida se va a leer en voz alta: pasado cierto punto sólo
+ // sirve para aburrir a quien escucha.
+ const MAX: usize = 2000;
+ if body.chars().count() > MAX {
+ body = body.chars().take(MAX).collect::<String>() + "… (salida recortada)";
+ }
+ if !output.status.success() {
+ return Ok(format!(
+ "la orden terminó con código {}: {body}",
+ output.status.code().unwrap_or(-1)
+ ));
+ }
+ Ok(if body.is_empty() {
+ "la orden terminó correctamente y no imprimió nada".into()
+ } else {
+ body
+ })
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::builtin::{format_spanish_date, Shell};
+ use super::*;
+
+ #[test]
+ fn la_fecha_se_compone_en_espanol_sin_depender_de_la_locale() {
+ assert_eq!(
+ format_spanish_date("0 6 9 2026 19:13").unwrap(),
+ "domingo 6 de septiembre de 2026, 19:13"
+ );
+ assert_eq!(
+ format_spanish_date("3 1 1 2027 00:05").unwrap(),
+ "miércoles 1 de enero de 2027, 00:05"
+ );
+ }
+
+ #[test]
+ fn una_salida_de_date_inesperada_no_provoca_un_panico() {
+ assert!(format_spanish_date("").is_none());
+ assert!(
+ format_spanish_date("9 6 9 2026 19:13").is_none(),
+ "día de semana fuera de rango"
+ );
+ assert!(
+ format_spanish_date("0 6 13 2026 19:13").is_none(),
+ "mes fuera de rango"
+ );
+ assert!(
+ format_spanish_date("0 6 0 2026 19:13").is_none(),
+ "mes cero"
+ );
+ }
+
+ #[test]
+ fn la_herramienta_de_hora_devuelve_algo_en_espanol() {
+ let out = builtin::Clock.call(&json!({})).unwrap();
+ assert!(
+ super::builtin::DIAS.iter().any(|d| out.starts_with(d)),
+ "esperaba un día en español, salió «{out}»"
+ );
+ }
+
+ fn shell_config() -> ToolsConfig {
+ ToolsConfig {
+ enabled: true,
+ dedicated_prompt: true,
+ shell: true,
+ shell_allowlist: vec!["echo".into(), "sleep".into()],
+ shell_timeout_secs: 1,
+ shell_dry_run: false,
+ shell_working_dir: String::new(),
+ }
+ }
+
+ #[test]
+ fn la_lista_blanca_deja_pasar_lo_autorizado() {
+ let shell = Shell::new(&shell_config());
+ let out = shell
+ .call(&json!({ "programa": "echo", "argumentos": ["hola"] }))
+ .unwrap();
+ assert_eq!(out, "hola");
+ }
+
+ #[test]
+ fn lo_no_autorizado_se_rechaza() {
+ let shell = Shell::new(&shell_config());
+ let err = shell.call(&json!({ "programa": "rm", "argumentos": ["-rf", "/"] }));
+ assert!(
+ err.is_err(),
+ "«rm» no estaba en la lista y debió rechazarse"
+ );
+ }
+
+ #[test]
+ fn una_ruta_absoluta_no_esquiva_la_lista_blanca() {
+ let shell = Shell::new(&shell_config());
+ assert!(
+ shell.call(&json!({ "programa": "/bin/echo" })).is_err(),
+ "«/bin/echo» debe rechazarse: si no, basta con dar una ruta para colar cualquier binario"
+ );
+ }
+
+ #[test]
+ fn no_hay_shell_que_interprete_los_metacaracteres() {
+ // Si esto llegara a una shell, se ejecutarían dos órdenes.
+ let shell = Shell::new(&shell_config());
+ let out = shell
+ .call(&json!({ "programa": "echo", "argumentos": ["a; echo b"] }))
+ .unwrap();
+ assert_eq!(
+ out, "a; echo b",
+ "el punto y coma debe ser texto, no un separador"
+ );
+ }
+
+ #[test]
+ fn una_orden_colgada_se_mata_al_vencer_el_plazo() {
+ let shell = Shell::new(&shell_config());
+ let err = shell
+ .call(&json!({ "programa": "sleep", "argumentos": ["30"] }))
+ .unwrap_err();
+ assert!(err.to_string().contains("plazo"), "{err}");
+ }
+
+ #[test]
+ fn la_simulacion_no_ejecuta_nada() {
+ let mut config = shell_config();
+ config.shell_dry_run = true;
+ let shell = Shell::new(&config);
+ let out = shell
+ .call(&json!({ "programa": "echo", "argumentos": ["x"] }))
+ .unwrap();
+ assert!(out.starts_with("[simulación]"), "{out}");
+ }
+
+ #[test]
+ fn la_shell_no_se_registra_si_la_configuracion_no_la_pide() {
+ let registry = ToolRegistry::from_config(&ToolsConfig::default());
+ assert!(registry.get("ejecutar_comando").is_none());
+ assert!(registry.get("hora_actual").is_some());
+ }
+
+ #[test]
+ fn una_herramienta_inexistente_devuelve_error_al_modelo_sin_romper_el_turno() {
+ let registry = ToolRegistry::from_config(&ToolsConfig::default());
+ let outcome = registry.dispatch(&ToolCall {
+ id: "1".into(),
+ name: "no_existe".into(),
+ arguments: "{}".into(),
+ });
+ assert!(!outcome.ok);
+ assert!(outcome.output.contains("hora_actual"), "{}", outcome.output);
+ }
+
+ #[test]
+ fn los_argumentos_vacios_valen_como_objeto_vacio() {
+ let registry = ToolRegistry::from_config(&ToolsConfig::default());
+ let outcome = registry.dispatch(&ToolCall {
+ id: "1".into(),
+ name: "hora_actual".into(),
+ arguments: "".into(),
+ });
+ assert!(outcome.ok, "{}", outcome.output);
+ }
+
+ #[test]
+ fn el_esquema_sale_en_el_formato_de_la_api_de_chat() {
+ let registry = ToolRegistry::from_config(&ToolsConfig::default());
+ let schema = registry.schema();
+ let first = &schema.as_array().unwrap()[0];
+ assert_eq!(first["type"], "function");
+ assert_eq!(first["function"]["name"], "hora_actual");
+ }
+}
diff --git a/crates/asist-llm/Cargo.toml b/crates/asist-llm/Cargo.toml
new file mode 100644
index 0000000..6090cf4
--- /dev/null
+++ b/crates/asist-llm/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "asist-llm"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+asist-core.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
diff --git a/crates/asist-llm/src/chat.rs b/crates/asist-llm/src/chat.rs
new file mode 100644
index 0000000..01a9a74
--- /dev/null
+++ b/crates/asist-llm/src/chat.rs
@@ -0,0 +1,275 @@
+//! Historial de conversación en el formato que espera la API de chat.
+
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+use asist_core::tools::{ToolCall, ToolOutcome};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Role {
+ System,
+ User,
+ Assistant,
+ Tool,
+}
+
+impl Role {
+ fn as_str(self) -> &'static str {
+ match self {
+ Role::System => "system",
+ Role::User => "user",
+ Role::Assistant => "assistant",
+ Role::Tool => "tool",
+ }
+ }
+}
+
+#[derive(Debug, Clone)]
+pub struct Message {
+ pub role: Role,
+ pub content: String,
+ /// Herramientas que el asistente pidió en este turno.
+ pub tool_calls: Vec<ToolCall>,
+ /// Para los mensajes de rol `tool`: a qué llamada responden.
+ pub tool_call_id: Option<String>,
+}
+
+impl Message {
+ pub fn system(content: impl Into<String>) -> Self {
+ Self::plain(Role::System, content)
+ }
+
+ pub fn user(content: impl Into<String>) -> Self {
+ Self::plain(Role::User, content)
+ }
+
+ pub fn assistant(content: impl Into<String>) -> Self {
+ Self::plain(Role::Assistant, content)
+ }
+
+ fn plain(role: Role, content: impl Into<String>) -> Self {
+ Self {
+ role,
+ content: content.into(),
+ tool_calls: Vec::new(),
+ tool_call_id: None,
+ }
+ }
+
+ /// Turno del asistente que en vez de hablar pidió herramientas.
+ pub fn tool_request(content: String, tool_calls: Vec<ToolCall>) -> Self {
+ Self {
+ role: Role::Assistant,
+ content,
+ tool_calls,
+ tool_call_id: None,
+ }
+ }
+
+ /// Resultado devuelto al modelo.
+ pub fn tool_result(outcome: &ToolOutcome) -> Self {
+ Self {
+ role: Role::Tool,
+ content: outcome.output.clone(),
+ tool_calls: Vec::new(),
+ tool_call_id: Some(outcome.id.clone()),
+ }
+ }
+
+ pub fn to_json(&self) -> Value {
+ let mut object = json!({ "role": self.role.as_str(), "content": self.content });
+ if !self.tool_calls.is_empty() {
+ object["tool_calls"] = Value::Array(
+ self.tool_calls
+ .iter()
+ .map(|call| {
+ json!({
+ "id": call.id,
+ "type": "function",
+ "function": { "name": call.name, "arguments": call.arguments }
+ })
+ })
+ .collect(),
+ );
+ }
+ if let Some(id) = &self.tool_call_id {
+ object["tool_call_id"] = json!(id);
+ }
+ object
+ }
+}
+
+/// Historial con la instrucción de sistema fija y una ventana deslizante de
+/// turnos, para que la conversación no crezca sin fin.
+#[derive(Debug, Clone)]
+pub struct Conversation {
+ system: Message,
+ turns: Vec<Message>,
+ max_turns: usize,
+}
+
+impl Conversation {
+ pub fn new(system_prompt: impl Into<String>, max_turns: usize) -> Self {
+ Self {
+ system: Message::system(system_prompt),
+ turns: Vec::new(),
+ max_turns,
+ }
+ }
+
+ /// Cambia la instrucción de sistema sin tocar el historial.
+ ///
+ /// El turno alterna entre la guía de herramientas y la de estilo, y el
+ /// historial tiene que sobrevivir al cambio: si se reiniciara, el modelo
+ /// perdería los resultados que acaba de pedir.
+ pub fn set_system(&mut self, prompt: &str) {
+ self.system = Message::system(prompt);
+ }
+
+ pub fn push(&mut self, message: Message) {
+ self.turns.push(message);
+ self.trim();
+ }
+
+ pub fn extend(&mut self, messages: impl IntoIterator<Item = Message>) {
+ self.turns.extend(messages);
+ self.trim();
+ }
+
+ /// Recorta a `max_turns` intervenciones de usuario, sin dejar nunca un
+ /// mensaje de rol `tool` huérfano al principio: la API lo rechaza si no
+ /// va precedido de la llamada que lo originó.
+ fn trim(&mut self) {
+ if self.max_turns == 0 {
+ self.turns.clear();
+ return;
+ }
+ let user_positions: Vec<usize> = self
+ .turns
+ .iter()
+ .enumerate()
+ .filter(|(_, m)| m.role == Role::User)
+ .map(|(i, _)| i)
+ .collect();
+ if user_positions.len() <= self.max_turns {
+ return;
+ }
+ let cut = user_positions[user_positions.len() - self.max_turns];
+ self.turns.drain(..cut);
+ }
+
+ pub fn messages(&self) -> Vec<&Message> {
+ std::iter::once(&self.system)
+ .chain(self.turns.iter())
+ .collect()
+ }
+
+ pub fn to_json(&self) -> Value {
+ Value::Array(self.messages().into_iter().map(Message::to_json).collect())
+ }
+
+ pub fn len(&self) -> usize {
+ self.turns.len()
+ }
+
+ pub fn is_empty(&self) -> bool {
+ self.turns.is_empty()
+ }
+
+ pub fn clear(&mut self) {
+ self.turns.clear();
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn la_instruccion_de_sistema_va_siempre_delante() {
+ let mut chat = Conversation::new("sé breve", 4);
+ chat.push(Message::user("hola"));
+ let json = chat.to_json();
+ assert_eq!(json[0]["role"], "system");
+ assert_eq!(json[0]["content"], "sé breve");
+ assert_eq!(json[1]["role"], "user");
+ }
+
+ #[test]
+ fn cambiar_la_instruccion_de_sistema_conserva_el_historial() {
+ let mut chat = Conversation::new("primera", 4);
+ chat.push(Message::user("hola"));
+ chat.set_system("segunda");
+ let json = chat.to_json();
+ assert_eq!(json[0]["content"], "segunda");
+ assert_eq!(
+ json[1]["content"], "hola",
+ "el historial no puede perderse al cambiar"
+ );
+ }
+
+ #[test]
+ fn el_historial_se_recorta_por_turnos_de_usuario() {
+ let mut chat = Conversation::new("s", 2);
+ for i in 0..5 {
+ chat.push(Message::user(format!("p{i}")));
+ chat.push(Message::assistant(format!("r{i}")));
+ }
+ let messages = chat.messages();
+ let users: Vec<&str> = messages
+ .iter()
+ .filter(|m| m.role == Role::User)
+ .map(|m| m.content.as_str())
+ .collect();
+ assert_eq!(users, vec!["p3", "p4"]);
+ }
+
+ #[test]
+ fn el_recorte_no_deja_un_resultado_de_herramienta_huerfano() {
+ // La API rechaza un mensaje `tool` que no venga detrás de la llamada
+ // que lo pidió, así que el corte tiene que caer en un turno de usuario.
+ let mut chat = Conversation::new("s", 1);
+ chat.push(Message::user("p0"));
+ chat.push(Message::tool_request(
+ String::new(),
+ vec![ToolCall {
+ id: "a".into(),
+ name: "t".into(),
+ arguments: "{}".into(),
+ }],
+ ));
+ chat.push(Message {
+ role: Role::Tool,
+ content: "ok".into(),
+ tool_calls: vec![],
+ tool_call_id: Some("a".into()),
+ });
+ chat.push(Message::user("p1"));
+
+ let roles: Vec<Role> = chat.messages().iter().map(|m| m.role).collect();
+ assert_eq!(roles, vec![Role::System, Role::User]);
+ }
+
+ #[test]
+ fn con_cero_turnos_no_hay_memoria() {
+ let mut chat = Conversation::new("s", 0);
+ chat.push(Message::user("hola"));
+ assert_eq!(chat.messages().len(), 1);
+ }
+
+ #[test]
+ fn una_llamada_a_herramienta_se_serializa_como_espera_la_api() {
+ let message = Message::tool_request(
+ String::new(),
+ vec![ToolCall {
+ id: "call_1".into(),
+ name: "hora_actual".into(),
+ arguments: "{}".into(),
+ }],
+ );
+ let json = message.to_json();
+ assert_eq!(json["tool_calls"][0]["type"], "function");
+ assert_eq!(json["tool_calls"][0]["function"]["name"], "hora_actual");
+ }
+}
diff --git a/crates/asist-llm/src/client.rs b/crates/asist-llm/src/client.rs
new file mode 100644
index 0000000..1dca2af
--- /dev/null
+++ b/crates/asist-llm/src/client.rs
@@ -0,0 +1,342 @@
+//! Transporte hacia llama-server.
+
+use std::time::{Duration, Instant};
+
+use serde_json::{json, Value};
+
+use asist_core::config::LlmConfig;
+use asist_core::error::{Error, Result};
+use asist_core::http::{Cancel, HttpClient};
+use asist_core::tools::{ToolCall, ToolRegistry};
+
+use crate::chat::Conversation;
+
+/// Un trozo de respuesta según sale del modelo.
+#[derive(Debug, Clone)]
+pub enum Delta {
+ /// Texto para el usuario.
+ Text(String),
+ /// El modelo ha decidido llamar a herramientas; no habrá más texto.
+ ToolCalls(Vec<ToolCall>),
+}
+
+/// Cómo terminó una respuesta en streaming.
+#[derive(Debug, Clone, Default)]
+pub struct StreamOutcome {
+ pub text: String,
+ pub tool_calls: Vec<ToolCall>,
+ /// Tiempo hasta el primer fragmento con contenido.
+ pub ttft: Option<Duration>,
+ pub stopped_early: bool,
+}
+
+pub struct LlmClient {
+ http: HttpClient,
+ config: LlmConfig,
+}
+
+impl LlmClient {
+ pub fn new(authority: String, config: &LlmConfig) -> Self {
+ Self {
+ http: HttpClient::new(authority)
+ .with_read_timeout(Duration::from_secs(config.request_timeout_secs)),
+ config: config.clone(),
+ }
+ }
+
+ pub fn healthy(&self) -> bool {
+ self.http.healthy("/health")
+ }
+
+ /// Espera a que el servidor termine de cargar el modelo.
+ pub fn wait_ready(&self, timeout: Duration) -> Result<()> {
+ let deadline = Instant::now() + timeout;
+ while Instant::now() < deadline {
+ if self.healthy() {
+ return Ok(());
+ }
+ std::thread::sleep(Duration::from_millis(500));
+ }
+ Err(Error::Llm(format!(
+ "{} no respondió a /health en {} s",
+ self.http.authority,
+ timeout.as_secs()
+ )))
+ }
+
+ /// Comprueba que la plantilla de chat no arranca un bloque de
+ /// razonamiento sin cerrar.
+ ///
+ /// Merece la pena avisar: con la plantilla original de Qwen3.5 el modelo
+ /// se pasa entre 7 y 9 segundos «pensando» antes de la primera palabra
+ /// audible, y desde fuera parece que el asistente se ha colgado.
+ pub fn warn_if_thinking_template(&self) {
+ let Ok(body) = self.http.get("/props") else {
+ return;
+ };
+ let Ok(props) = serde_json::from_slice::<Value>(&body) else {
+ return;
+ };
+ let Some(template) = props.get("chat_template").and_then(Value::as_str) else {
+ return;
+ };
+
+ let opens = template.matches("<think>").count();
+ let closes = template.matches("</think>").count();
+ if opens > closes {
+ tracing::warn!(
+ target: "llm",
+ "la plantilla de chat abre <think> sin cerrarlo: el modelo razonará \
+ varios segundos antes de contestar. Arranca llama-server con \
+ --chat-template-file config/qwen35-no-think.jinja"
+ );
+ }
+ }
+
+ fn request_body(&self, chat: &Conversation, tools: Option<&ToolRegistry>) -> Value {
+ let mut body = json!({
+ "messages": chat.to_json(),
+ "stream": true,
+ "temperature": self.config.temperature,
+ "top_p": self.config.top_p,
+ "top_k": self.config.top_k,
+ "min_p": self.config.min_p,
+ "repeat_penalty": self.config.repeat_penalty,
+ "max_tokens": self.config.max_tokens,
+ });
+ if !self.config.model.is_empty() {
+ body["model"] = json!(self.config.model);
+ }
+ if let Some(tools) = tools.filter(|t| !t.is_empty()) {
+ body["tools"] = tools.schema();
+ body["tool_choice"] = json!("auto");
+ }
+ body
+ }
+
+ /// Envía la conversación y entrega la respuesta a trozos.
+ ///
+ /// `on_delta` devuelve `false` para cortar —lo que hace el orquestador
+ /// cuando el usuario interrumpe—; `cancel` hace lo mismo desde otro hilo.
+ pub fn stream(
+ &self,
+ chat: &Conversation,
+ tools: Option<&ToolRegistry>,
+ cancel: &Cancel,
+ mut on_delta: impl FnMut(&Delta) -> bool,
+ ) -> Result<StreamOutcome> {
+ let body = self.request_body(chat, tools);
+ let started = Instant::now();
+ let mut outcome = StreamOutcome::default();
+ let mut assembler = ToolCallAssembler::default();
+ let mut finished = false;
+
+ let result = self
+ .http
+ .post_json_lines("/v1/chat/completions", &body, cancel, |line| {
+ let Some(payload) = line.strip_prefix("data: ") else {
+ return true;
+ };
+ if payload.trim() == "[DONE]" {
+ finished = true;
+ return false;
+ }
+ let Ok(event) = serde_json::from_str::<Value>(payload) else {
+ tracing::debug!(target: "llm", %payload, "fragmento SSE ilegible");
+ return true;
+ };
+ let Some(choice) = event.get("choices").and_then(|c| c.get(0)) else {
+ return true;
+ };
+ let delta = choice.get("delta").unwrap_or(&Value::Null);
+
+ if let Some(calls) = delta.get("tool_calls").and_then(Value::as_array) {
+ assembler.absorb(calls);
+ }
+ if let Some(text) = delta.get("content").and_then(Value::as_str) {
+ if !text.is_empty() {
+ if outcome.ttft.is_none() {
+ outcome.ttft = Some(started.elapsed());
+ }
+ outcome.text.push_str(text);
+ if !on_delta(&Delta::Text(text.to_string())) {
+ outcome.stopped_early = true;
+ return false;
+ }
+ }
+ }
+ // Un `finish_reason` cierra la respuesta aunque el servidor no
+ // llegue a mandar el [DONE] (pasa al cortar la conexión).
+ if choice.get("finish_reason").is_some_and(|r| !r.is_null()) {
+ finished = true;
+ return false;
+ }
+ true
+ });
+
+ match result {
+ Ok(()) => {}
+ // Cortar a propósito no es un fallo: `on_delta` devolvió false o
+ // se activó la cancelación.
+ Err(Error::Cancelled) if finished || outcome.stopped_early || cancel.is_cancelled() => {
+ }
+ Err(err) => return Err(err),
+ }
+
+ outcome.tool_calls = assembler.finish();
+ if !outcome.tool_calls.is_empty()
+ && !on_delta(&Delta::ToolCalls(outcome.tool_calls.clone()))
+ {
+ outcome.stopped_early = true;
+ }
+ Ok(outcome)
+ }
+}
+
+/// Reensambla las llamadas a herramientas, que llegan repartidas en fragmentos.
+///
+/// El streaming manda el nombre en un fragmento y los argumentos en varios
+/// más, identificados sólo por su `index`; hasta que no termina el flujo no
+/// hay una llamada completa que ejecutar.
+#[derive(Default)]
+struct ToolCallAssembler {
+ partial: Vec<PartialCall>,
+}
+
+#[derive(Default, Clone)]
+struct PartialCall {
+ id: String,
+ name: String,
+ arguments: String,
+}
+
+impl ToolCallAssembler {
+ fn absorb(&mut self, calls: &[Value]) {
+ for call in calls {
+ let index = call.get("index").and_then(Value::as_u64).unwrap_or(0) as usize;
+ if self.partial.len() <= index {
+ self.partial.resize(index + 1, PartialCall::default());
+ }
+ let slot = &mut self.partial[index];
+ if let Some(id) = call.get("id").and_then(Value::as_str) {
+ if !id.is_empty() {
+ slot.id = id.to_string();
+ }
+ }
+ let Some(function) = call.get("function") else {
+ continue;
+ };
+ if let Some(name) = function.get("name").and_then(Value::as_str) {
+ if !name.is_empty() {
+ slot.name = name.to_string();
+ }
+ }
+ if let Some(args) = function.get("arguments").and_then(Value::as_str) {
+ slot.arguments.push_str(args);
+ }
+ }
+ }
+
+ fn finish(self) -> Vec<ToolCall> {
+ self.partial
+ .into_iter()
+ .enumerate()
+ .filter(|(_, call)| !call.name.is_empty())
+ .map(|(i, call)| ToolCall {
+ id: if call.id.is_empty() {
+ format!("call_{i}")
+ } else {
+ call.id
+ },
+ name: call.name,
+ arguments: if call.arguments.is_empty() {
+ "{}".into()
+ } else {
+ call.arguments
+ },
+ })
+ .collect()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn absorb(assembler: &mut ToolCallAssembler, raw: &str) {
+ let value: Value = serde_json::from_str(raw).unwrap();
+ assembler.absorb(value.as_array().unwrap());
+ }
+
+ #[test]
+ fn los_argumentos_troceados_se_reensamblan() {
+ let mut assembler = ToolCallAssembler::default();
+ absorb(
+ &mut assembler,
+ r#"[{"index":0,"id":"c1","function":{"name":"eco","arguments":"{\"a\":"}}]"#,
+ );
+ absorb(
+ &mut assembler,
+ r#"[{"index":0,"function":{"arguments":"1}"}}]"#,
+ );
+ let calls = assembler.finish();
+ assert_eq!(calls.len(), 1);
+ assert_eq!(calls[0].id, "c1");
+ assert_eq!(calls[0].name, "eco");
+ assert_eq!(calls[0].arguments, r#"{"a":1}"#);
+ }
+
+ #[test]
+ fn se_reensamblan_varias_llamadas_en_paralelo() {
+ let mut assembler = ToolCallAssembler::default();
+ absorb(
+ &mut assembler,
+ r#"[{"index":0,"id":"a","function":{"name":"uno","arguments":"{}"}}]"#,
+ );
+ absorb(
+ &mut assembler,
+ r#"[{"index":1,"id":"b","function":{"name":"dos","arguments":"{}"}}]"#,
+ );
+ let calls = assembler.finish();
+ assert_eq!(calls.len(), 2);
+ assert_eq!(calls[0].name, "uno");
+ assert_eq!(calls[1].name, "dos");
+ }
+
+ #[test]
+ fn sin_argumentos_se_asume_el_objeto_vacio() {
+ let mut assembler = ToolCallAssembler::default();
+ absorb(
+ &mut assembler,
+ r#"[{"index":0,"id":"c","function":{"name":"hora_actual"}}]"#,
+ );
+ assert_eq!(assembler.finish()[0].arguments, "{}");
+ }
+
+ #[test]
+ fn un_hueco_sin_nombre_no_produce_una_llamada() {
+ // El servidor puede numerar el índice 1 sin haber mandado nunca el 0.
+ let mut assembler = ToolCallAssembler::default();
+ absorb(
+ &mut assembler,
+ r#"[{"index":1,"id":"b","function":{"name":"dos","arguments":"{}"}}]"#,
+ );
+ let calls = assembler.finish();
+ assert_eq!(
+ calls.len(),
+ 1,
+ "el hueco no debe convertirse en una llamada vacía"
+ );
+ assert_eq!(calls[0].name, "dos");
+ }
+
+ #[test]
+ fn sin_id_se_genera_uno_estable() {
+ let mut assembler = ToolCallAssembler::default();
+ absorb(
+ &mut assembler,
+ r#"[{"index":0,"function":{"name":"x","arguments":"{}"}}]"#,
+ );
+ assert_eq!(assembler.finish()[0].id, "call_0");
+ }
+}
diff --git a/crates/asist-llm/src/lib.rs b/crates/asist-llm/src/lib.rs
new file mode 100644
index 0000000..4c860df
--- /dev/null
+++ b/crates/asist-llm/src/lib.rs
@@ -0,0 +1,12 @@
+//! Cliente de llama-server.
+//!
+//! Habla la API de chat de OpenAI en modo streaming, porque en un asistente de
+//! voz la respuesta no se espera: se trocea en frases y se va sintetizando
+//! mientras el modelo sigue escribiendo. Esperar a la respuesta entera sumaría
+//! el tiempo del modelo al del sintetizador en lugar de solaparlos.
+
+pub mod chat;
+pub mod client;
+
+pub use chat::{Message, Role};
+pub use client::{Delta, LlmClient, StreamOutcome};
diff --git a/crates/asist-tts/Cargo.toml b/crates/asist-tts/Cargo.toml
new file mode 100644
index 0000000..a0762d8
--- /dev/null
+++ b/crates/asist-tts/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "asist-tts"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+asist-core.workspace = true
+base64.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
diff --git a/crates/asist-tts/src/lib.rs b/crates/asist-tts/src/lib.rs
new file mode 100644
index 0000000..b250116
--- /dev/null
+++ b/crates/asist-tts/src/lib.rs
@@ -0,0 +1,256 @@
+//! Síntesis de voz sobre qwentts.cpp.
+//!
+//! Se habla con `tts-server` por HTTP en lugar de invocar el binario
+//! `qwen-tts` una vez por frase. La diferencia no es de estilo: el proceso
+//! carga 2,1 GB de modelo hablante más 291 MB de codec, y pagar esa carga en
+//! cada frase pondría varios segundos delante de cada respuesta. El servidor
+//! los mantiene residentes en la GPU y responde en formato `pcm`, que llega
+//! troceado según se genera.
+
+use std::time::{Duration, Instant};
+
+use base64::Engine;
+use serde_json::json;
+
+use asist_core::config::{ReferenceVoice, TtsConfig};
+use asist_core::error::{Error, Result};
+use asist_core::http::{Cancel, HttpClient};
+
+/// Frecuencia a la que sintetiza el modelo.
+pub const SAMPLE_RATE: u32 = 24_000;
+
+/// Cómo terminó una síntesis.
+#[derive(Debug, Clone, Default)]
+pub struct SpeechOutcome {
+ /// Tiempo hasta el primer bloque de audio.
+ pub ttfb: Option<Duration>,
+ pub total: Duration,
+ pub samples: usize,
+ pub cancelled: bool,
+}
+
+impl SpeechOutcome {
+ pub fn audio_secs(&self) -> f32 {
+ self.samples as f32 / SAMPLE_RATE as f32
+ }
+
+ /// Múltiplo del tiempo real. Por encima de 1,0 el sintetizador va más
+ /// lento que el habla y la cola de reproducción acabará vaciándose.
+ pub fn rtf(&self) -> f32 {
+ let audio = self.audio_secs();
+ if audio <= 0.0 {
+ return f32::INFINITY;
+ }
+ self.total.as_secs_f32() / audio
+ }
+}
+
+pub struct TtsClient {
+ http: HttpClient,
+ config: TtsConfig,
+}
+
+impl TtsClient {
+ pub fn new(authority: String, config: &TtsConfig) -> Self {
+ Self {
+ http: HttpClient::new(authority)
+ .with_read_timeout(Duration::from_secs(config.request_timeout_secs)),
+ config: config.clone(),
+ }
+ }
+
+ pub fn healthy(&self) -> bool {
+ self.http.healthy("/health")
+ }
+
+ pub fn wait_ready(&self, timeout: Duration) -> Result<()> {
+ let deadline = Instant::now() + timeout;
+ while Instant::now() < deadline {
+ if self.healthy() {
+ return Ok(());
+ }
+ std::thread::sleep(Duration::from_millis(500));
+ }
+ Err(Error::Tts(format!(
+ "{} no respondió a /health en {} s",
+ self.http.authority,
+ timeout.as_secs()
+ )))
+ }
+
+ /// Registra una voz clonada a partir de los latentes de `qwen-codec`.
+ ///
+ /// Se mandan los `.spk` y `.rvq` ya extraídos en lugar del WAV original:
+ /// el servidor los toma tal cual y se ahorra volver a analizar la
+ /// referencia en cada arranque.
+ pub fn register_voice(&self, voice: &ReferenceVoice) -> Result<()> {
+ let read = |path: &std::path::Path, what: &str| -> Result<Vec<u8>> {
+ std::fs::read(path).map_err(|e| {
+ Error::Tts(format!("no se pudo leer {what} ({}): {e}", path.display()))
+ })
+ };
+ let b64 = base64::engine::general_purpose::STANDARD;
+ let speaker = b64.encode(read(&voice.speaker, "el embedding del hablante")?);
+ let codes = b64.encode(read(&voice.codes, "los códigos de referencia")?);
+ let transcript = String::from_utf8_lossy(&read(&voice.transcript, "la transcripción")?)
+ .trim()
+ .to_string();
+
+ if transcript.is_empty() {
+ return Err(Error::Tts(format!(
+ "la transcripción de referencia {} está vacía; sin ella no se activa el clonado",
+ voice.transcript.display()
+ )));
+ }
+
+ let body = json!({
+ "name": voice.name,
+ "ref_text": transcript,
+ "spk_b64": speaker,
+ "rvq_b64": codes,
+ });
+ self.http.post_json("/v1/audio/voices", &body)?;
+ tracing::info!(target: "tts", voz = %voice.name, "voz clonada registrada");
+ Ok(())
+ }
+
+ /// Voces que el servidor conoce ahora mismo.
+ pub fn voices(&self) -> Result<Vec<String>> {
+ let body = self.http.get("/v1/audio/voices")?;
+ let parsed: serde_json::Value = serde_json::from_slice(&body)?;
+ Ok(parsed
+ .get("voices")
+ .and_then(|v| v.as_array())
+ .map(|voices| {
+ voices
+ .iter()
+ .filter_map(|v| {
+ v.get("name")
+ .and_then(|n| n.as_str())
+ .or_else(|| v.as_str())
+ .map(String::from)
+ })
+ .collect()
+ })
+ .unwrap_or_default())
+ }
+
+ /// Sintetiza `text` y entrega el audio a trozos según se genera.
+ ///
+ /// `on_audio` recibe muestras mono f32 a 24 kHz y devuelve `false` para
+ /// cortar; `cancel` hace lo propio desde otro hilo. Ese corte es lo que
+ /// permite callar de golpe cuando el usuario interrumpe, sin esperar a que
+ /// termine de generarse una frase que ya no se va a oír.
+ pub fn speak(
+ &self,
+ text: &str,
+ cancel: &Cancel,
+ mut on_audio: impl FnMut(&[f32]) -> bool,
+ ) -> Result<SpeechOutcome> {
+ let body = json!({
+ "input": text,
+ "voice": self.config.voice,
+ "response_format": "pcm",
+ "temperature": self.config.temperature,
+ "top_k": self.config.top_k,
+ "top_p": self.config.top_p,
+ "repetition_penalty": self.config.repetition_penalty,
+ "max_new_tokens": self.config.max_new_tokens,
+ });
+
+ let started = Instant::now();
+ let mut outcome = SpeechOutcome::default();
+ // El servidor no garantiza que cada bloque traiga un número par de
+ // bytes, así que el byte suelto de un bloque espera al siguiente en
+ // vez de desplazar todas las muestras posteriores.
+ let mut odd: Option<u8> = None;
+ let mut samples = Vec::with_capacity(8192);
+ let mut stopped = false;
+
+ let result = self
+ .http
+ .post_json_streaming("/v1/audio/speech", &body, cancel, |chunk| {
+ if outcome.ttfb.is_none() {
+ outcome.ttfb = Some(started.elapsed());
+ }
+ samples.clear();
+ let mut bytes = chunk;
+ if let Some(pending) = odd.take() {
+ if let Some((first, rest)) = bytes.split_first() {
+ samples.push(i16::from_le_bytes([pending, *first]) as f32 / 32768.0);
+ bytes = rest;
+ } else {
+ odd = Some(pending);
+ }
+ }
+ if bytes.len() % 2 == 1 {
+ odd = Some(bytes[bytes.len() - 1]);
+ bytes = &bytes[..bytes.len() - 1];
+ }
+ for pair in bytes.chunks_exact(2) {
+ samples.push(i16::from_le_bytes([pair[0], pair[1]]) as f32 / 32768.0);
+ }
+ outcome.samples += samples.len();
+ if !on_audio(&samples) {
+ stopped = true;
+ return false;
+ }
+ true
+ });
+
+ outcome.total = started.elapsed();
+ match result {
+ Ok(()) => {}
+ Err(Error::Cancelled) => outcome.cancelled = true,
+ Err(err) => return Err(err),
+ }
+ outcome.cancelled |= stopped;
+
+ tracing::debug!(
+ target: "tts",
+ caracteres = text.chars().count(),
+ ttfb_ms = outcome.ttfb.map(|d| d.as_millis()).unwrap_or(0),
+ audio_s = outcome.audio_secs(),
+ rtf = outcome.rtf(),
+ cancelada = outcome.cancelled,
+ "síntesis"
+ );
+ Ok(outcome)
+ }
+
+ /// Sintetiza una frase corta para pagar por adelantado la construcción de
+ /// los grafos: la primera petición cuesta unos 3,5 s más que las
+ /// siguientes, y no conviene gastarlos en el primer turno de verdad.
+ pub fn warmup(&self) -> Result<()> {
+ if !self.config.warmup {
+ return Ok(());
+ }
+ let started = Instant::now();
+ let cancel = Cancel::new();
+ // El audio se tira: sólo interesa el efecto secundario.
+ self.speak("Listo.", &cancel, |_| true)?;
+ tracing::info!(target: "tts", ms = started.elapsed().as_millis(), "precalentado");
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn el_rtf_relaciona_tiempo_de_calculo_y_audio() {
+ let outcome = SpeechOutcome {
+ total: Duration::from_secs(2),
+ samples: SAMPLE_RATE as usize * 4,
+ ..Default::default()
+ };
+ assert_eq!(outcome.audio_secs(), 4.0);
+ assert_eq!(outcome.rtf(), 0.5);
+ }
+
+ #[test]
+ fn sin_audio_el_rtf_es_infinito_en_vez_de_dividir_por_cero() {
+ assert!(SpeechOutcome::default().rtf().is_infinite());
+ }
+}