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
//! Translating one [`Request`] into the three wire formats.
//!
//! The interesting part is tool round trips. Each API expresses "the model
//! asked for this, here is what it got" differently, and all three reject a
//! conversation where the two halves do not line up — Anthropic and Chat
//! Completions by id, Responses by `call_id`. Everything here exists to keep
//! those halves matched.

use serde_json::{json, Value};

use crate::catalog::ApiStyle;
use crate::message::{Message, Role};
use crate::request::{Request, ToolSchema};

/// What varies per client rather than per request.
pub(crate) struct Wire<'a> {
    pub api: ApiStyle,
    pub model: &'a str,
    pub reasoning_effort: Option<&'a str>,
    /// Anthropic's `max_tokens` is required, so a client-level floor is needed
    /// when the request does not name one.
    pub default_max_tokens: u32,
    /// False for a route that rejects an output limit outright, in which case
    /// the field is left out rather than sent and refused. Anthropic ignores
    /// this: `max_tokens` is required there, so there is nothing to leave out.
    pub accepts_output_limit: bool,
}

pub(crate) fn body(wire: &Wire<'_>, request: &Request) -> Value {
    match wire.api {
        ApiStyle::Responses => responses(wire, request),
        ApiStyle::Anthropic => anthropic(wire, request),
        ApiStyle::ChatCompletions => chat(wire, request),
    }
}

fn arguments(value: &Value) -> String {
    // Every API carries function arguments as a JSON *string*, not an object.
    serde_json::to_string(value).unwrap_or_else(|_| "{}".into())
}

// ---------------------------------------------------------------------------
// OpenAI Responses
// ---------------------------------------------------------------------------

fn responses(wire: &Wire<'_>, request: &Request) -> Value {
    let mut input = Vec::new();
    for message in &request.messages {
        if !message.text.is_empty() || (message.calls.is_empty() && message.results.is_empty()) {
            let part = if message.role == Role::User {
                "input_text"
            } else {
                "output_text"
            };
            input.push(json!({
                "type": "message",
                "role": message.role.wire_name(),
                "content": [{ "type": part, "text": message.text }],
            }));
        }
        for (index, call) in message.calls.iter().enumerate() {
            input.push(json!({
                "type": "function_call",
                "call_id": call.call_id(index),
                "name": call.name,
                "arguments": arguments(&call.args),
            }));
        }
        for result in &message.results {
            input.push(json!({
                "type": "function_call_output",
                "call_id": result.id,
                "output": result.output,
            }));
        }
    }

    let mut body = json!({
        "model": wire.model,
        "instructions": request.instructions,
        "input": input,
        "stream": true,
        "store": false,
    });
    if !request.tools.is_empty() {
        body["tools"] = Value::Array(
            request
                .tools
                .iter()
                .map(|tool: &ToolSchema| {
                    json!({
                        "type": "function",
                        "name": tool.name,
                        "description": tool.description,
                        "parameters": tool.parameters,
                    })
                })
                .collect(),
        );
        body["tool_choice"] = json!("auto");
        body["parallel_tool_calls"] = json!(true);
    }
    if let Some(max) = request.max_output_tokens.filter(|_| wire.accepts_output_limit) {
        body["max_output_tokens"] = json!(max);
    }
    if let Some(temperature) = request.temperature {
        body["temperature"] = json!(temperature);
    }
    if let Some(effort) = wire.reasoning_effort {
        body["reasoning"] = json!({ "effort": effort });
    }
    body
}

// ---------------------------------------------------------------------------
// Anthropic Messages
// ---------------------------------------------------------------------------

fn anthropic(wire: &Wire<'_>, request: &Request) -> Value {
    let messages: Vec<Value> = request
        .messages
        .iter()
        .filter(|message| !message.is_empty())
        .map(anthropic_message)
        .collect();

    let mut body = json!({
        "model": wire.model,
        "max_tokens": request.max_output_tokens.unwrap_or(wire.default_max_tokens),
        "system": request.instructions,
        "messages": messages,
        "stream": true,
    });
    if !request.tools.is_empty() {
        body["tools"] = Value::Array(
            request
                .tools
                .iter()
                .map(|tool| {
                    json!({
                        "name": tool.name,
                        "description": tool.description,
                        "input_schema": tool.parameters,
                    })
                })
                .collect(),
        );
    }
    if let Some(temperature) = request.temperature {
        body["temperature"] = json!(temperature);
    }
    if let Some(effort) = wire.reasoning_effort {
        body["output_config"] = json!({ "effort": effort });
    }
    body
}

fn anthropic_message(message: &Message) -> Value {
    if message.calls.is_empty() && message.results.is_empty() {
        return json!({ "role": message.role.wire_name(), "content": message.text });
    }
    let mut content = Vec::new();
    if !message.text.trim().is_empty() {
        content.push(json!({ "type": "text", "text": message.text }));
    }
    for (index, call) in message.calls.iter().enumerate() {
        content.push(json!({
            "type": "tool_use",
            "id": call.call_id(index),
            "name": call.name,
            "input": call.args,
        }));
    }
    for result in &message.results {
        content.push(json!({
            "type": "tool_result",
            "tool_use_id": result.id,
            "content": result.output,
            "is_error": result.failed,
        }));
    }
    json!({ "role": message.role.wire_name(), "content": content })
}

// ---------------------------------------------------------------------------
// OpenAI-shaped Chat Completions
// ---------------------------------------------------------------------------

fn chat(wire: &Wire<'_>, request: &Request) -> Value {
    let mut messages = vec![json!({ "role": "system", "content": request.instructions })];
    for message in &request.messages {
        // Tool output is its own role here, and must come before anything else
        // the same turn carries.
        for result in &message.results {
            messages.push(json!({
                "role": "tool",
                "tool_call_id": result.id,
                "content": result.output,
            }));
        }
        if message.calls.is_empty() {
            if !message.text.is_empty() || message.results.is_empty() {
                messages.push(json!({ "role": message.role.wire_name(), "content": message.text }));
            }
            continue;
        }
        let calls: Vec<Value> = message
            .calls
            .iter()
            .enumerate()
            .map(|(index, call)| {
                json!({
                    "id": call.call_id(index),
                    "type": "function",
                    "function": { "name": call.name, "arguments": arguments(&call.args) },
                })
            })
            .collect();
        messages.push(json!({
            "role": "assistant",
            "content": message.text,
            "tool_calls": calls,
        }));
    }

    let mut body = json!({
        "model": wire.model,
        "messages": messages,
        "stream": true,
        "stream_options": { "include_usage": true },
    });
    if let Some(max) = request.max_output_tokens.filter(|_| wire.accepts_output_limit) {
        body["max_tokens"] = json!(max);
    }
    if let Some(temperature) = request.temperature {
        body["temperature"] = json!(temperature);
    }
    if !request.tools.is_empty() {
        body["tools"] = Value::Array(
            request
                .tools
                .iter()
                .map(|tool| {
                    json!({
                        "type": "function",
                        "function": {
                            "name": tool.name,
                            "description": tool.description,
                            "parameters": tool.parameters,
                        },
                    })
                })
                .collect(),
        );
        body["tool_choice"] = json!("auto");
    }
    body
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::message::{ToolCall, ToolResult};

    fn wire(api: ApiStyle) -> Wire<'static> {
        Wire {
            api,
            model: "test-model",
            reasoning_effort: None,
            default_max_tokens: 1024,
            accepts_output_limit: true,
        }
    }

    #[test]
    fn a_route_that_refuses_an_output_limit_is_sent_none() {
        let request = round_trip().max_output_tokens(420);

        for api in [ApiStyle::Responses, ApiStyle::ChatCompletions] {
            assert!(!body(&wire(api), &request)["max_output_tokens"].is_null()
                || !body(&wire(api), &request)["max_tokens"].is_null());
            let refused = Wire {
                accepts_output_limit: false,
                ..wire(api)
            };
            let body = body(&refused, &request);
            assert!(
                body["max_output_tokens"].is_null() && body["max_tokens"].is_null(),
                "{api:?} still carried a limit: {body}"
            );
        }

        // Anthropic requires the field, so there is nothing to leave out and
        // the flag must not be able to produce a body the API will reject.
        let refused = Wire {
            accepts_output_limit: false,
            ..wire(ApiStyle::Anthropic)
        };
        assert_eq!(body(&refused, &request)["max_tokens"], 420);
    }

    /// The same tool round trip, ready to be encoded three ways.
    fn round_trip() -> Request {
        let call = ToolCall::new("weather", json!({"city": "Lisbon"})).with_id("call_1");
        let result = ToolResult::new(&call, 0, "18C and clear");
        Request::new("Be brief")
            .user("What is the weather?")
            .message(Message::tool_calls("Checking.", vec![call]))
            .message(Message::tool_results(vec![result]))
    }

    #[test]
    fn responses_pairs_each_call_with_its_output() {
        let body = body(&wire(ApiStyle::Responses), &round_trip());
        let input = body["input"].as_array().unwrap();
        let call = input
            .iter()
            .find(|item| item["type"] == "function_call")
            .unwrap();
        let output = input
            .iter()
            .find(|item| item["type"] == "function_call_output")
            .unwrap();

        assert_eq!(call["call_id"], output["call_id"]);
        assert_eq!(call["name"], "weather");
        // Arguments travel as a JSON string, never as an object.
        assert_eq!(call["arguments"], r#"{"city":"Lisbon"}"#);
        assert_eq!(output["output"], "18C and clear");
    }

    #[test]
    fn anthropic_pairs_tool_use_with_tool_result() {
        let body = body(&wire(ApiStyle::Anthropic), &round_trip());
        let messages = body["messages"].as_array().unwrap();
        let use_block = &messages[1]["content"][1];
        let result_block = &messages[2]["content"][0];

        assert_eq!(messages[1]["role"], "assistant");
        assert_eq!(messages[1]["content"][0]["type"], "text");
        assert_eq!(use_block["type"], "tool_use");
        assert_eq!(use_block["input"]["city"], "Lisbon");
        assert_eq!(result_block["type"], "tool_result");
        assert_eq!(result_block["tool_use_id"], use_block["id"]);
        assert_eq!(result_block["is_error"], false);
        assert_eq!(body["max_tokens"], 1024);
    }

    #[test]
    fn chat_completions_answers_a_call_with_the_tool_role() {
        let body = body(&wire(ApiStyle::ChatCompletions), &round_trip());
        let messages = body["messages"].as_array().unwrap();

        assert_eq!(messages[0]["role"], "system");
        let assistant = messages
            .iter()
            .find(|message| message["role"] == "assistant")
            .unwrap();
        let tool = messages
            .iter()
            .find(|message| message["role"] == "tool")
            .unwrap();
        assert_eq!(
            assistant["tool_calls"][0]["function"]["arguments"],
            r#"{"city":"Lisbon"}"#
        );
        assert_eq!(tool["tool_call_id"], assistant["tool_calls"][0]["id"]);
        assert_eq!(tool["content"], "18C and clear");
    }

    #[test]
    fn a_failed_tool_is_reported_as_a_failure_to_anthropic() {
        let call = ToolCall::new("open_page", json!({})).with_id("c1");
        let request = Request::new("x")
            .message(Message::tool_calls("", vec![call.clone()]))
            .message(Message::tool_results(vec![ToolResult::failure(
                &call, 0, "404",
            )]));
        let body = body(&wire(ApiStyle::Anthropic), &request);
        assert_eq!(body["messages"][1]["content"][0]["is_error"], true);
    }

    #[test]
    fn plain_conversations_keep_the_simple_shape() {
        let request = Request::new("Be concise").user("Hello");
        assert_eq!(
            body(&wire(ApiStyle::Responses), &request)["input"][0]["content"][0]["type"],
            "input_text"
        );
        assert_eq!(
            body(&wire(ApiStyle::Anthropic), &request)["messages"][0]["content"],
            "Hello"
        );
        assert_eq!(
            body(&wire(ApiStyle::ChatCompletions), &request)["messages"][1]["content"],
            "Hello"
        );
    }
}