path: root/crates/asist-core/src/tools.rs

//! Tools the model can call.
//!
//! The assistant's extension point. A tool is an object that describes itself
//! in JSON Schema and knows how to run; the registry translates them to the
//! chat API `tools` format and dispatches the calls that come back. Adding a
//! new capability means implementing the trait and registering it, without
//! touching the orchestrator.

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};

/// Something the model can ask to be done.
pub trait Tool: Send + Sync {
    /// Identifier the model uses. Lowercase, no spaces.
    fn name(&self) -> &str;

    /// What it is for. The model reads it, so it is written for the model:
    /// concrete and in the conversation language.
    fn description(&self) -> &str;

    /// JSON Schema of the arguments.
    fn parameters(&self) -> Value;

    /// Runs and returns the text handed to the model as the result.
    fn call(&self, args: &Value) -> Result<String>;

    /// `true` if the tool changes something outside the process. The
    /// orchestrator announces it aloud before running it.
    fn is_side_effecting(&self) -> bool {
        false
    }

    /// Sentence spoken right when it starts running.
    ///
    /// It exists for the sake of the conversation, not decoration: a search takes
    /// about 2.5 s, the camera almost 3, and the two model passes come on top.
    /// Six seconds of total silence read as the assistant having hung. A tool
    /// that answers instantly returns `None`, where the acknowledgement would
    /// annoy more than help.
    fn acknowledgement(&self) -> Option<&str> {
        None
    }
}

/// A call as the model requests it.
#[derive(Debug, Clone)]
pub struct ToolCall {
    pub id: String,
    pub name: String,
    /// JSON arguments, not validated yet.
    pub arguments: String,
}

/// Result of running it.
#[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()
    }

    /// Builds the tool set the configuration asks for.
    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)
    }

    /// Description in the OpenAI chat API `tools` format, which is what
    /// llama-server speaks.
    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(),
        )
    }

    /// Runs a call. It never propagates the error upwards: a tool failure is
    /// handed back to the model as text so it can explain it or retry, instead
    /// of bringing the turn down.
    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(|_| {
                    // Small models sometimes send an empty string instead of «{}»
                    // when the function takes no arguments.
                    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::path::Path;
    use std::process::Command;

    /// Local date and time. It exists because the model does not know them and
    /// confidently makes them up, and it doubles as a minimal tool example.
    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` avoids pulling in a whole calendar dependency for a single
            // call, and it honours the system time zone. It is asked for numeric
            // fields and the names are filled in here: `%A` and `%B` come out in
            // the locale language, which on this machine is English, and the
            // assistant would end up saying «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 WEEKDAYS: [&str; 7] = [
        "domingo",
        "lunes",
        "martes",
        "miércoles",
        "jueves",
        "viernes",
        "sábado",
    ];
    const MONTHS: [&str; 12] = [
        "enero",
        "febrero",
        "marzo",
        "abril",
        "mayo",
        "junio",
        "julio",
        "agosto",
        "septiembre",
        "octubre",
        "noviembre",
        "diciembre",
    ];

    /// Builds «domingo 6 de septiembre de 2026, 19:13» from
    /// «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