diff options
Diffstat (limited to 'crates')
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()); + } +} |