rune-chain-core 0.1.1

/// An LLM-callable tool that an agent can invoke during its reasoning loop.
///
/// Implement this trait to expose any capability — a calculator, web search,
/// file reader, or database query — to a [`crate::Chain`]-based agent. The
/// agent selects a tool by matching its [`Tool::name`] and calls [`Tool::run`]
/// with a plain-text input string.
///
/// # Example
///
/// ```rust
/// use rune_chain_core::Tool;
///
/// struct Echo;
///
/// impl Tool for Echo {
///     fn name(&self) -> &str { "echo" }
///     fn description(&self) -> &str { "Returns the input unchanged." }
///     fn run(&self, input: &str) -> String { input.to_string() }
/// }
///
/// let tool = Echo;
/// assert_eq!(tool.run("hello"), "hello");
/// ```
pub trait Tool: Send + Sync {
    /// Short identifier used in prompts: `"calculator"`, `"web_search"`, etc.
    ///
    /// Must be unique within an agent's tool list and contain no spaces.
    fn name(&self) -> &str;

    /// One-sentence description the LLM uses to decide when to call this tool.
    ///
    /// Keep it concise and action-oriented, e.g. `"Evaluates a math expression and returns the numeric result."`.
    fn description(&self) -> &str;

    /// Execute the tool with the given `input` string and return the result.
    ///
    /// The input is whatever the LLM placed after `Action Input:` in the ReAct
    /// scratchpad. The return value is fed back to the LLM as an `Observation`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use rune_chain_core::Tool;
    ///
    /// struct Upper;
    /// impl Tool for Upper {
    ///     fn name(&self) -> &str { "upper" }
    ///     fn description(&self) -> &str { "Converts input to upper case." }
    ///     fn run(&self, input: &str) -> String { input.to_uppercase() }
    /// }
    ///
    /// assert_eq!(Upper.run("hello"), "HELLO");
    /// ```
    fn run(&self, input: &str) -> String;
}