dsir 0.1.1

DSPy-shaped library for programming language models in Rust.
Documentation
use std::future::Future;
use std::sync::Arc;

use facet::Facet;
use rig::completion::ToolDefinition;
use rig::message::{ToolCall, ToolFunction};
use rig::tool::{ToolDyn, ToolError};
use rig::wasm_compat::WasmBoxedFuture;

use crate::core::{Module, Signature};
use crate::predictors::{Predict, PredictBuilder};
use crate::{BamlType, PredictError, Predicted};

/// ReAct action-step schema.
#[derive(dsir_macros::Signature, Clone, Debug)]
struct ReActActionStep {
    #[input]
    input: String,

    #[input]
    trajectory: String,

    #[output]
    thought: String,

    #[output]
    action: String,

    #[output]
    action_input: String,
}

/// ReAct extraction-step schema.
#[derive(dsir_macros::Signature, Clone, Debug)]
struct ReActExtractStep<O>
where
    O: BamlType + for<'a> Facet<'a> + Send + Sync + 'static,
{
    #[input]
    input: String,

    #[input]
    trajectory: String,

    #[output]
    output: O,
}

#[derive(facet::Facet)]
#[facet(crate = facet)]
pub struct ReAct<S>
where
    S: Signature,
    S::Input: BamlType + Clone,
    S::Output: BamlType,
{
    action: Predict<ReActActionStep>,
    extract: Predict<ReActExtractStep<S::Output>>,
    #[facet(skip, opaque)]
    tools: Vec<Arc<dyn ToolDyn>>,
    #[facet(skip)]
    max_steps: usize,
}

impl<S> ReAct<S>
where
    S: Signature,
    S::Input: BamlType + Clone,
    S::Output: BamlType,
{
    pub fn new() -> Self {
        Self::builder().build()
    }

    pub fn builder() -> ReActBuilder<S> {
        ReActBuilder::new()
    }

    pub async fn call(&self, input: S::Input) -> Result<Predicted<S::Output>, PredictError> {
        self.forward(input).await
    }

    pub async fn forward(&self, input: S::Input) -> Result<Predicted<S::Output>, PredictError> {
        self.run(input).await
    }

    async fn render_tool_manifest(&self) -> String {
        if self.tools.is_empty() {
            return "Available tools: (none)".to_string();
        }

        let mut lines = vec!["Available tools:".to_string()];
        for tool in &self.tools {
            let definition = tool.definition(String::new()).await;
            lines.push(format!("- {}: {}", definition.name, definition.description));
        }

        lines.join("\n")
    }

    async fn execute_tool(&self, name: &str, args: String) -> String {
        let normalized = name.trim();

        for tool in &self.tools {
            let candidate = tool.name();
            if tool_name_matches(&candidate, normalized) {
                return match tool.call(args).await {
                    Ok(result) => result,
                    Err(err) => format!("tool_error: {err}"),
                };
            }
        }

        // Keep unknown actions explicit in trajectory instead of silently invoking
        // an arbitrary tool, which hides planner/output bugs from callers.
        tracing::debug!(tool = %normalized, "react tool name not found");
        let _ = args;

        format!("tool_not_found: {name}")
    }

    fn is_terminal_action(action: &str) -> bool {
        action.eq_ignore_ascii_case("finish")
            || action.eq_ignore_ascii_case("final")
            || action.eq_ignore_ascii_case("done")
    }

    fn format_trace_entry(
        step: usize,
        thought: &str,
        action: &str,
        action_input: &str,
        observation: Option<&str>,
    ) -> String {
        let observation_text = observation.unwrap_or("<none>");
        format!(
            "Step {step}\nThought: {thought}\nAction: {action}\nAction Input: {action_input}\nObservation: {observation_text}"
        )
    }

    async fn run(&self, input: S::Input) -> Result<Predicted<S::Output>, PredictError> {
        let serialized_input = serde_json::to_string(&input.to_baml_value())
            .unwrap_or_else(|_| "<input serialization failed>".to_string());

        let tool_manifest = self.render_tool_manifest().await;
        let mut trajectory_text = tool_manifest.clone();
        trajectory_text.push_str("\n\n");

        let mut tool_calls = Vec::new();
        let mut tool_executions = Vec::new();
        tool_executions.push(tool_manifest);

        for step in 0..self.max_steps {
            let action_input =
                ReActActionStepInput::new(serialized_input.clone(), trajectory_text.clone());

            let action_predicted = self.action.call(action_input).await?;
            let (action_output, mut action_metadata) = action_predicted.into_parts();
            tool_calls.append(&mut action_metadata.tool_calls);
            tool_executions.append(&mut action_metadata.tool_executions);

            let ReActActionStepOutput {
                thought,
                action,
                action_input,
            } = action_output;

            let action_name = action
                .trim()
                .trim_matches('"')
                .trim_matches('\'')
                .to_string();

            if Self::is_terminal_action(&action_name) {
                let trace =
                    Self::format_trace_entry(step + 1, &thought, &action_name, &action_input, None);
                tool_executions.push(trace.clone());
                trajectory_text.push_str(&format!(
                    "Step {}\nThought: {}\nFinal: {}\n\n",
                    step + 1,
                    thought,
                    action_input
                ));
                break;
            }

            let observation = self.execute_tool(&action_name, action_input.clone()).await;

            tool_calls.push(ToolCall {
                id: format!("react-step-{}", step + 1),
                call_id: None,
                function: ToolFunction {
                    name: action_name.clone(),
                    arguments: serde_json::json!(action_input),
                },
                signature: None,
                additional_params: None,
            });
            tool_executions.push(Self::format_trace_entry(
                step + 1,
                &thought,
                &action_name,
                &action_input,
                Some(&observation),
            ));

            trajectory_text.push_str(&format!(
                "Step {}\nThought: {}\nAction: {}\nAction Input: {}\nObservation: {}\n\n",
                step + 1,
                thought,
                action_name,
                action_input,
                observation
            ));
        }

        let extract_input = ReActExtractStepInput::new(serialized_input, trajectory_text);

        let extract_predicted = self.extract.call(extract_input).await?;
        let (extract_output, mut extract_metadata) = extract_predicted.into_parts();
        extract_metadata.tool_calls.extend(tool_calls);
        extract_metadata.tool_executions.extend(tool_executions);

        let output: ReActExtractStepOutput<S::Output> = extract_output;
        Ok(Predicted::new(output.output, extract_metadata))
    }
}

impl<S> Default for ReAct<S>
where
    S: Signature,
    S::Input: BamlType + Clone,
    S::Output: BamlType,
{
    fn default() -> Self {
        Self::new()
    }
}

impl<S> Module for ReAct<S>
where
    S: Signature,
    S::Input: BamlType + Clone,
    S::Output: BamlType,
{
    type Input = S::Input;
    type Output = S::Output;

    async fn forward(&self, input: S::Input) -> Result<Predicted<S::Output>, PredictError> {
        ReAct::forward(self, input).await
    }
}

pub struct ReActBuilder<S>
where
    S: Signature,
    S::Input: BamlType + Clone,
    S::Output: BamlType,
{
    action: PredictBuilder<ReActActionStep>,
    extract: PredictBuilder<ReActExtractStep<S::Output>>,
    tools: Vec<Arc<dyn ToolDyn>>,
    max_steps: usize,
}

impl<S> ReActBuilder<S>
where
    S: Signature,
    S::Input: BamlType + Clone,
    S::Output: BamlType,
{
    fn new() -> Self {
        Self {
            action: Predict::builder(),
            extract: Predict::builder(),
            tools: Vec::new(),
            max_steps: 4,
        }
    }

    pub fn action_instruction(mut self, instruction: impl Into<String>) -> Self {
        self.action = self.action.instruction(instruction);
        self
    }

    pub fn extract_instruction(mut self, instruction: impl Into<String>) -> Self {
        self.extract = self.extract.instruction(instruction);
        self
    }

    pub fn max_steps(mut self, max_steps: usize) -> Self {
        self.max_steps = max_steps.max(1);
        self
    }

    pub fn add_tool(mut self, tool: impl ToolDyn + 'static) -> Self {
        self.tools.push(Arc::new(tool));
        self
    }

    pub fn with_tools(mut self, tools: impl IntoIterator<Item = Arc<dyn ToolDyn>>) -> Self {
        self.tools.extend(tools);
        self
    }

    pub fn tool<F, Fut>(
        mut self,
        name: impl Into<String>,
        description: impl Into<String>,
        tool_fn: F,
    ) -> Self
    where
        F: Fn(String) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = String> + Send + 'static,
    {
        self.tools.push(Arc::new(PlainAsyncTool {
            name: name.into(),
            description: description.into(),
            handler: tool_fn,
        }));
        self
    }

    /// Sets a per-instance LM on both the action and extract predictors,
    /// bypassing the global. See [`PredictBuilder::lm`].
    pub fn lm(mut self, lm: crate::core::LM) -> Self {
        self.action = self.action.lm(lm.clone());
        self.extract = self.extract.lm(lm);
        self
    }

    pub fn build(self) -> ReAct<S> {
        ReAct {
            action: self.action.build(),
            extract: self.extract.build(),
            tools: self.tools,
            max_steps: self.max_steps,
        }
    }
}

struct PlainAsyncTool<F> {
    name: String,
    description: String,
    handler: F,
}

impl<F, Fut> ToolDyn for PlainAsyncTool<F>
where
    F: Fn(String) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = String> + Send + 'static,
{
    fn name(&self) -> String {
        self.name.clone()
    }

    fn definition<'a>(&'a self, _prompt: String) -> WasmBoxedFuture<'a, ToolDefinition> {
        Box::pin(async move {
            ToolDefinition {
                name: self.name.clone(),
                description: self.description.clone(),
                parameters: serde_json::json!({
                    "type": "object",
                    "additionalProperties": true
                }),
            }
        })
    }

    fn call<'a>(&'a self, args: String) -> WasmBoxedFuture<'a, Result<String, ToolError>> {
        Box::pin(async move { Ok((self.handler)(args).await) })
    }
}

fn tool_name_matches(candidate: &str, action: &str) -> bool {
    candidate.eq_ignore_ascii_case(action)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn tool_name_matches_requires_exact_equality() {
        assert!(tool_name_matches("search", "search"));
        assert!(tool_name_matches("Search", "search"));
        assert!(!tool_name_matches("search", "search_extended"));
        assert!(!tool_name_matches("search_extended", "search"));
        assert!(!tool_name_matches("search", "use search tool"));
    }
}