modelbridge 0.5.2

One provider-neutral Rust client for OpenAI, Anthropic, Gemini, Groq, Ollama and friends: streaming, tool calling, an agent loop, usage accounting, and subscription sign-in
Documentation
//! Conversation turns, including the tool calls a model makes and the results
//! handed back to it.
//!
//! Every provider expresses a tool round trip differently — OpenAI Responses
//! items, Anthropic content blocks, Chat Completions `tool` messages — but they
//! all need the same three things: a call id, what was called, and what came
//! back. That is what [`Message`] carries, and [`crate::encode`] translates.

use serde::{Deserialize, Serialize};
use serde_json::Value;

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum Role {
    #[default]
    User,
    Assistant,
}

impl Role {
    /// What this role is called on the wire. All three APIs agree on these
    /// two names, which is most of why the enum has only two variants.
    pub fn wire_name(self) -> &'static str {
        match self {
            Role::User => "user",
            Role::Assistant => "assistant",
        }
    }
}

/// A tool invocation the model asked for.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct ToolCall {
    /// The provider's id for this call. Results must quote it back; Anthropic
    /// and Chat Completions both reject a mismatch. Empty when a provider did
    /// not supply one, in which case [`Message::tool_calls`] synthesises it.
    #[serde(default)]
    pub id: String,
    pub name: String,
    pub args: Value,
}

impl ToolCall {
    pub fn new(name: impl Into<String>, args: Value) -> Self {
        Self {
            id: String::new(),
            name: name.into(),
            args,
        }
    }

    pub fn with_id(mut self, id: impl Into<String>) -> Self {
        self.id = id.into();
        self
    }

    /// A stable id, inventing one when the provider stayed silent. Providers
    /// only need the two sides of a round trip to agree, not to match a format.
    pub fn call_id(&self, index: usize) -> String {
        if self.id.is_empty() {
            format!("call_{index}_{}", self.name)
        } else {
            self.id.clone()
        }
    }

    /// A named argument as text, which is what most tools actually want.
    pub fn arg(&self, name: &str) -> Option<&str> {
        self.args.get(name).and_then(Value::as_str)
    }
}

/// What a tool produced, on its way back to the model.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct ToolResult {
    pub id: String,
    pub name: String,
    pub output: String,
    /// Reported to the model as a failed call rather than a successful one, so
    /// it can try something else instead of trusting an error message as data.
    #[serde(default)]
    pub failed: bool,
}

impl ToolResult {
    pub fn new(call: &ToolCall, index: usize, output: impl Into<String>) -> Self {
        Self {
            id: call.call_id(index),
            name: call.name.clone(),
            output: output.into(),
            failed: false,
        }
    }

    pub fn failure(call: &ToolCall, index: usize, message: impl Into<String>) -> Self {
        Self {
            failed: true,
            ..Self::new(call, index, message)
        }
    }
}

/// One turn of the conversation.
///
/// A plain turn is a role and some text. A tool round trip adds `calls` to the
/// assistant turn that requested them and `results` to the user turn that
/// answers, and the two are matched by id.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Message {
    pub role: Role,
    #[serde(default)]
    pub text: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub calls: Vec<ToolCall>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub results: Vec<ToolResult>,
}

impl Message {
    pub fn user(text: impl Into<String>) -> Self {
        Self {
            role: Role::User,
            text: text.into(),
            ..Self::default()
        }
    }

    pub fn assistant(text: impl Into<String>) -> Self {
        Self {
            role: Role::Assistant,
            text: text.into(),
            ..Self::default()
        }
    }

    /// The assistant turn that asked for tools, with whatever it said first.
    pub fn tool_calls(text: impl Into<String>, calls: Vec<ToolCall>) -> Self {
        let calls = calls
            .into_iter()
            .enumerate()
            .map(|(index, call)| {
                let id = call.call_id(index);
                ToolCall { id, ..call }
            })
            .collect();
        Self {
            role: Role::Assistant,
            text: text.into(),
            calls,
            results: Vec::new(),
        }
    }

    /// The turn that hands tool output back to the model.
    pub fn tool_results(results: Vec<ToolResult>) -> Self {
        Self {
            role: Role::User,
            text: String::new(),
            calls: Vec::new(),
            results,
        }
    }

    pub fn is_empty(&self) -> bool {
        self.text.trim().is_empty() && self.calls.is_empty() && self.results.is_empty()
    }
}

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

    #[test]
    fn calls_without_provider_ids_get_stable_synthetic_ones() {
        let message = Message::tool_calls(
            "looking it up",
            vec![
                ToolCall::new("search", json!({"q": "rust"})),
                ToolCall::new("search", json!({"q": "gats"})),
            ],
        );
        assert_ne!(message.calls[0].id, message.calls[1].id);
        assert!(message.calls[0].id.contains("search"));

        // A result built from the same call and index quotes the same id back.
        let result = ToolResult::new(&message.calls[0], 0, "hits");
        assert_eq!(result.id, message.calls[0].id);
    }

    #[test]
    fn provider_supplied_ids_are_left_alone() {
        let message = Message::tool_calls(
            "",
            vec![ToolCall::new("search", json!({})).with_id("toolu_01ABC")],
        );
        assert_eq!(message.calls[0].id, "toolu_01ABC");
    }

    #[test]
    fn a_failed_tool_is_marked_as_such() {
        let call = ToolCall::new("open_page", json!({"url": "x"}));
        assert!(ToolResult::failure(&call, 0, "404").failed);
        assert!(!ToolResult::new(&call, 0, "body").failed);
    }

    #[test]
    fn plain_turns_carry_no_tool_baggage() {
        let message = Message::user("hello");
        assert!(message.calls.is_empty() && message.results.is_empty());
        assert!(Message::assistant("").is_empty());
    }
}