use std::collections::{btree_map::Entry, BTreeMap};
use std::future::Future;
use openai_client_base::models::{ChatCompletionMessageToolCallsInner, ChatCompletionTool};
use serde::{de::DeserializeOwned, Serialize};
use serde_json::{json, Value};
use crate::{
builders::chat::tool_function, responses::chat::ToolCallExt, responses_api::ResponsesTool,
BoxFuture, Error, MaybeSend, MaybeSync, Result,
};
mod names;
mod output;
pub mod schema;
mod search;
pub use names::{sanitize_tool_name, ToolNamer, CHAT_TOOL_NAME_MAX, RESPONSES_TOOL_NAME_MAX};
pub use output::{
truncate_middle, CallAnswer, ImageDetail, OutputBudget, OutputContent, ToolInvocation,
ToolKind, ToolOutputBody, TruncationConfig, ABORTED_OUTPUT,
};
pub trait FunctionTool: MaybeSend + MaybeSync {
type Input: DeserializeOwned + MaybeSend;
type Output: Serialize + MaybeSend;
fn name(&self) -> &str;
fn description(&self) -> &str;
fn parameters_schema(&self) -> Value;
fn execute(
&self,
input: Self::Input,
) -> impl std::future::Future<Output = Result<Self::Output>> + MaybeSend;
fn supports_parallel(&self) -> bool {
false
}
fn output_budget(&self) -> Option<OutputBudget> {
None
}
fn exposure(&self) -> Exposure {
Exposure::Direct
}
}
pub trait RichTool: MaybeSend + MaybeSync {
type Input: DeserializeOwned + MaybeSend;
fn name(&self) -> &str;
fn description(&self) -> &str;
fn parameters_schema(&self) -> Value;
fn execute(
&self,
input: Self::Input,
) -> impl Future<Output = Result<ToolOutputBody>> + MaybeSend;
fn supports_parallel(&self) -> bool {
false
}
fn output_budget(&self) -> Option<OutputBudget> {
None
}
fn exposure(&self) -> Exposure {
Exposure::Direct
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum GrammarSyntax {
Lark,
Regex,
}
impl GrammarSyntax {
fn as_str(self) -> &'static str {
match self {
Self::Lark => "lark",
Self::Regex => "regex",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum CustomFormat {
Text,
Grammar {
syntax: GrammarSyntax,
definition: String,
},
}
impl CustomFormat {
#[must_use]
pub fn lark(definition: impl Into<String>) -> Self {
Self::Grammar {
syntax: GrammarSyntax::Lark,
definition: definition.into(),
}
}
#[must_use]
pub fn regex(definition: impl Into<String>) -> Self {
Self::Grammar {
syntax: GrammarSyntax::Regex,
definition: definition.into(),
}
}
fn to_json(&self) -> Value {
match self {
Self::Text => json!({"type": "text"}),
Self::Grammar { syntax, definition } => {
json!({"type": "grammar", "syntax": syntax.as_str(), "definition": definition})
}
}
}
}
pub trait CustomTool: MaybeSend + MaybeSync {
fn name(&self) -> &str;
fn description(&self) -> &str;
fn format(&self) -> CustomFormat {
CustomFormat::Text
}
fn execute(&self, input: String) -> impl Future<Output = Result<ToolOutputBody>> + MaybeSend;
fn supports_parallel(&self) -> bool {
false
}
fn output_budget(&self) -> Option<OutputBudget> {
None
}
fn exposure(&self) -> Exposure {
Exposure::Direct
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Exposure {
#[default]
Direct,
Deferred,
Hidden,
}
#[cfg(not(target_family = "wasm"))]
type DynamicHandler =
Box<dyn Fn(Value) -> BoxFuture<'static, Result<ToolOutputBody>> + Send + Sync>;
#[cfg(target_family = "wasm")]
type DynamicHandler = Box<dyn Fn(Value) -> BoxFuture<'static, Result<ToolOutputBody>>>;
pub struct DynamicTool {
raw_name: String,
prefix: Option<String>,
description: String,
schema: Value,
handler: DynamicHandler,
supports_parallel: bool,
output_budget: Option<OutputBudget>,
exposure: Exposure,
}
impl std::fmt::Debug for DynamicTool {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("DynamicTool")
.field("raw_name", &self.raw_name)
.field("prefix", &self.prefix)
.field("description", &self.description)
.finish_non_exhaustive()
}
}
impl DynamicTool {
#[cfg(not(target_family = "wasm"))]
pub fn new<F, Fut>(
name: impl Into<String>,
description: impl Into<String>,
schema: Value,
handler: F,
) -> Self
where
F: Fn(Value) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<ToolOutputBody>> + Send + 'static,
{
Self::from_handler(
name.into(),
description.into(),
schema,
Box::new(move |arguments| Box::pin(handler(arguments))),
)
}
#[cfg(target_family = "wasm")]
pub fn new<F, Fut>(
name: impl Into<String>,
description: impl Into<String>,
schema: Value,
handler: F,
) -> Self
where
F: Fn(Value) -> Fut + 'static,
Fut: Future<Output = Result<ToolOutputBody>> + 'static,
{
Self::from_handler(
name.into(),
description.into(),
schema,
Box::new(move |arguments| Box::pin(handler(arguments))),
)
}
fn from_handler(
raw_name: String,
description: String,
schema: Value,
handler: DynamicHandler,
) -> Self {
Self {
raw_name,
prefix: None,
description,
schema,
handler,
supports_parallel: false,
output_budget: None,
exposure: Exposure::Direct,
}
}
#[must_use]
pub fn prefix(mut self, prefix: impl Into<String>) -> Self {
self.prefix = Some(prefix.into());
self
}
#[must_use]
pub fn supports_parallel(mut self, parallel: bool) -> Self {
self.supports_parallel = parallel;
self
}
#[must_use]
pub fn output_budget(mut self, budget: OutputBudget) -> Self {
self.output_budget = Some(budget);
self
}
#[must_use]
pub fn exposure(mut self, exposure: Exposure) -> Self {
self.exposure = exposure;
self
}
}
pub const DYNAMIC_SCHEMA_COMPACT_BYTES: usize = 5_000;
pub const DYNAMIC_SCHEMA_MAX_BYTES: usize = 8_000;
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ToolError {
#[error("Tool {name:?} is already registered")]
Duplicate {
name: String,
},
#[error("Invalid definition for tool {name:?}: {reason}")]
InvalidDefinition {
name: String,
reason: String,
},
#[error("Unknown tool {name:?}")]
Unknown {
name: String,
},
#[error("Tool {name:?} argument decoding failed: {source}")]
Arguments {
name: String,
#[source]
source: serde_json::Error,
},
#[error("Tool {name:?} output encoding failed: {source}")]
Output {
name: String,
#[source]
source: serde_json::Error,
},
#[error("Tool {name:?} arguments must be a JSON object")]
InvalidArguments {
name: String,
},
#[error("Tool {name:?} execution failed: {source}")]
Execution {
name: String,
#[source]
source: Error,
},
#[error("Invalid tool call: {reason}")]
InvalidCall {
reason: String,
},
#[error("Tool call {call_id:?} failed: {source}")]
Call {
call_id: String,
#[source]
source: Box<Self>,
},
#[error("Unsupported tool output: {reason}")]
UnsupportedOutput {
reason: String,
},
}
#[derive(Debug)]
#[non_exhaustive]
pub enum ToolFailure {
RespondToModel(String),
Fatal(ToolError),
}
impl ToolError {
#[must_use]
pub fn classify(self) -> ToolFailure {
match self {
Self::Arguments { source, .. } => {
ToolFailure::RespondToModel(format!("failed to parse function arguments: {source}"))
}
Self::InvalidArguments { .. } => {
ToolFailure::RespondToModel("function arguments must be a JSON object".into())
}
Self::Unknown { name } => {
ToolFailure::RespondToModel(format!("unsupported call: {name}"))
}
Self::InvalidCall { reason } | Self::UnsupportedOutput { reason } => {
ToolFailure::RespondToModel(reason)
}
Self::Execution { source, .. } if !source.is_fatal() => {
ToolFailure::RespondToModel(model_message(&source))
}
Self::Call { call_id, source } => match source.classify() {
ToolFailure::Fatal(source) => ToolFailure::Fatal(Self::Call {
call_id,
source: Box::new(source),
}),
other => other,
},
other => ToolFailure::Fatal(other),
}
}
}
fn model_message(error: &Error) -> String {
match error {
Error::Application(error) => error.to_string(),
Error::Tool(error) => error.to_string(),
other => other.to_string(),
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ToolOutput {
pub call_id: String,
pub content: String,
}
impl ToolOutput {
#[must_use]
pub fn body(&self) -> ToolOutputBody {
ToolOutputBody::Text(self.content.clone())
}
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub struct ToolKey {
pub namespace: Option<String>,
pub name: String,
}
impl ToolKey {
#[must_use]
pub fn new(name: impl Into<String>) -> Self {
Self {
namespace: None,
name: name.into(),
}
}
#[must_use]
pub fn namespaced(namespace: impl Into<String>, name: impl Into<String>) -> Self {
Self {
namespace: Some(namespace.into()),
name: name.into(),
}
}
fn of(call: &ToolInvocation) -> Self {
Self {
namespace: call.namespace.clone(),
name: call.name.clone(),
}
}
}
enum ErasedOutput {
Json(Value),
Body(ToolOutputBody),
}
impl ErasedOutput {
fn into_body(self) -> ToolOutputBody {
match self {
Self::Json(value) => ToolOutputBody::Text(value.to_string()),
Self::Body(body) => body,
}
}
fn into_value(self) -> Value {
match self {
Self::Json(value) => value,
Self::Body(ToolOutputBody::Text(text)) => Value::String(text),
Self::Body(body) => body.to_json(),
}
}
}
trait ErasedTool: MaybeSend + MaybeSync {
fn call<'a>(
&'a self,
name: &'a str,
input: &'a str,
) -> BoxFuture<'a, std::result::Result<ErasedOutput, ToolError>>;
}
fn decode_arguments<I: DeserializeOwned>(
name: &str,
arguments: &str,
) -> std::result::Result<I, ToolError> {
let argument_error = |source| ToolError::Arguments {
name: name.into(),
source,
};
let value: Value = serde_json::from_str(arguments).map_err(argument_error)?;
if !value.is_object() {
return Err(ToolError::InvalidArguments { name: name.into() });
}
serde_json::from_str(arguments).map_err(argument_error)
}
fn execution_error(name: &str) -> impl FnOnce(Error) -> ToolError + '_ {
move |source| ToolError::Execution {
name: name.into(),
source,
}
}
struct FunctionAdapter<T>(T);
impl<T: FunctionTool> ErasedTool for FunctionAdapter<T> {
fn call<'a>(
&'a self,
name: &'a str,
input: &'a str,
) -> BoxFuture<'a, std::result::Result<ErasedOutput, ToolError>> {
Box::pin(async move {
let input = decode_arguments(name, input)?;
let output = FunctionTool::execute(&self.0, input)
.await
.map_err(execution_error(name))?;
serde_json::to_value(output)
.map(ErasedOutput::Json)
.map_err(|source| ToolError::Output {
name: name.into(),
source,
})
})
}
}
struct RichAdapter<T>(T);
impl<T: RichTool> ErasedTool for RichAdapter<T> {
fn call<'a>(
&'a self,
name: &'a str,
input: &'a str,
) -> BoxFuture<'a, std::result::Result<ErasedOutput, ToolError>> {
Box::pin(async move {
let input = decode_arguments(name, input)?;
RichTool::execute(&self.0, input)
.await
.map(ErasedOutput::Body)
.map_err(execution_error(name))
})
}
}
struct CustomAdapter<T>(T);
impl<T: CustomTool> ErasedTool for CustomAdapter<T> {
fn call<'a>(
&'a self,
name: &'a str,
input: &'a str,
) -> BoxFuture<'a, std::result::Result<ErasedOutput, ToolError>> {
Box::pin(async move {
CustomTool::execute(&self.0, input.to_string())
.await
.map(ErasedOutput::Body)
.map_err(execution_error(name))
})
}
}
struct DynamicAdapter(DynamicHandler);
impl ErasedTool for DynamicAdapter {
fn call<'a>(
&'a self,
name: &'a str,
input: &'a str,
) -> BoxFuture<'a, std::result::Result<ErasedOutput, ToolError>> {
Box::pin(async move {
let arguments: Value = decode_arguments(name, input)?;
(self.0)(arguments)
.await
.map(ErasedOutput::Body)
.map_err(execution_error(name))
})
}
}
struct RegisteredTool {
kind: ToolKind,
description: String,
parameters: Value,
format: CustomFormat,
handler: Box<dyn ErasedTool>,
supports_parallel: bool,
output_budget: Option<OutputBudget>,
exposure: Exposure,
raw_name: Option<String>,
}
impl RegisteredTool {
fn function(
description: &str,
parameters: Value,
handler: Box<dyn ErasedTool>,
supports_parallel: bool,
output_budget: Option<OutputBudget>,
exposure: Exposure,
) -> Self {
Self {
kind: ToolKind::Function,
description: description.to_string(),
parameters,
format: CustomFormat::Text,
handler,
supports_parallel,
output_budget,
exposure,
raw_name: None,
}
}
fn responses_json(&self, name: &str, defer_loading: bool) -> Value {
let mut value = match self.kind {
ToolKind::Custom => json!({
"type": "custom",
"name": name,
"description": self.description,
"format": self.format.to_json(),
}),
_ => json!({
"type": "function",
"name": name,
"description": self.description,
"parameters": self.parameters,
}),
};
if defer_loading {
value["defer_loading"] = Value::Bool(true);
}
value
}
}
fn check_name(name: &str) -> std::result::Result<(), ToolError> {
if name.is_empty()
|| name.len() > CHAT_TOOL_NAME_MAX
|| !name
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
{
return Err(invalid(
name,
"name must contain 1–64 ASCII letters, digits, underscores or hyphens",
));
}
Ok(())
}
fn check_description(name: &str, description: &str) -> std::result::Result<(), ToolError> {
if description.trim().is_empty() {
return Err(invalid(name, "description must not be blank"));
}
Ok(())
}
fn check_schema(name: &str, schema: &Value) -> std::result::Result<(), ToolError> {
if !schema.is_object() || schema.get("type").and_then(Value::as_str) != Some("object") {
return Err(invalid(
name,
"parameters schema must have root type object",
));
}
Ok(())
}
fn invalid(name: &str, reason: &str) -> ToolError {
ToolError::InvalidDefinition {
name: name.into(),
reason: reason.into(),
}
}
#[derive(Default)]
pub struct ToolRegistry {
tools: BTreeMap<ToolKey, RegisteredTool>,
namespaces: BTreeMap<String, String>,
}
impl std::fmt::Debug for ToolRegistry {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ToolRegistry")
.field("tools", &self.tools.keys())
.field("namespaces", &self.namespaces.keys())
.finish_non_exhaustive()
}
}
impl ToolRegistry {
#[must_use]
pub fn new() -> Self {
Self::default()
}
pub fn register<T: FunctionTool + 'static>(
&mut self,
tool: T,
) -> std::result::Result<(), ToolError> {
self.register_function_in(None, tool)
}
pub fn register_rich<T: RichTool + 'static>(
&mut self,
tool: T,
) -> std::result::Result<(), ToolError> {
self.register_rich_in(None, tool)
}
pub fn register_custom<T: CustomTool + 'static>(
&mut self,
tool: T,
) -> std::result::Result<(), ToolError> {
self.register_custom_in(None, tool)
}
pub fn register_dynamic(
&mut self,
tool: DynamicTool,
) -> std::result::Result<String, ToolError> {
let mut schema = tool.schema;
schema::sanitize(&mut schema);
if schema.get("type").and_then(Value::as_str) != Some("object") {
return Err(invalid(
&tool.raw_name,
"parameters schema must have root type object",
));
}
if schema::size(&schema) > DYNAMIC_SCHEMA_COMPACT_BYTES {
schema::compact(&mut schema, DYNAMIC_SCHEMA_COMPACT_BYTES);
}
if schema::size(&schema) > DYNAMIC_SCHEMA_MAX_BYTES {
schema = json!({"type": "object", "properties": {}, "additionalProperties": true});
}
let name = names::unique_name(
tool.prefix.as_deref(),
&tool.raw_name,
CHAT_TOOL_NAME_MAX,
|candidate| {
self.tools.contains_key(&ToolKey::new(candidate))
|| self.namespaces.contains_key(candidate)
},
);
let description = if tool.description.trim().is_empty() {
tool.raw_name.clone()
} else {
tool.description
};
let mut registered = RegisteredTool::function(
&description,
schema,
Box::new(DynamicAdapter(tool.handler)),
tool.supports_parallel,
tool.output_budget,
tool.exposure,
);
registered.raw_name = Some(tool.raw_name);
self.insert(ToolKey::new(name.clone()), registered)?;
Ok(name)
}
pub fn namespace(
&mut self,
name: &str,
description: &str,
) -> std::result::Result<NamespaceRegistrar<'_>, ToolError> {
check_name(name)?;
check_description(name, description)?;
if self.tools.contains_key(&ToolKey::new(name)) {
return Err(ToolError::Duplicate { name: name.into() });
}
match self.namespaces.get(name) {
Some(existing) if existing != description => {
return Err(invalid(
name,
"namespace already registered with another description",
));
}
Some(_) => {}
None => {
self.namespaces.insert(name.into(), description.into());
}
}
Ok(NamespaceRegistrar {
registry: self,
namespace: name.into(),
})
}
fn register_function_in<T: FunctionTool + 'static>(
&mut self,
namespace: Option<&str>,
tool: T,
) -> std::result::Result<(), ToolError> {
let name = tool.name().to_owned();
check_name(&name)?;
check_description(&name, tool.description())?;
let schema = tool.parameters_schema();
check_schema(&name, &schema)?;
let (parallel, budget, exposure) = (
FunctionTool::supports_parallel(&tool),
FunctionTool::output_budget(&tool),
FunctionTool::exposure(&tool),
);
let description = tool.description().to_owned();
let registered = RegisteredTool::function(
&description,
schema,
Box::new(FunctionAdapter(tool)),
parallel,
budget,
exposure,
);
self.insert(key(namespace, name), registered)
}
fn register_rich_in<T: RichTool + 'static>(
&mut self,
namespace: Option<&str>,
tool: T,
) -> std::result::Result<(), ToolError> {
let name = tool.name().to_owned();
check_name(&name)?;
check_description(&name, tool.description())?;
let schema = tool.parameters_schema();
check_schema(&name, &schema)?;
let (parallel, budget, exposure) = (
tool.supports_parallel(),
tool.output_budget(),
tool.exposure(),
);
let description = tool.description().to_owned();
let registered = RegisteredTool::function(
&description,
schema,
Box::new(RichAdapter(tool)),
parallel,
budget,
exposure,
);
self.insert(key(namespace, name), registered)
}
fn register_custom_in<T: CustomTool + 'static>(
&mut self,
namespace: Option<&str>,
tool: T,
) -> std::result::Result<(), ToolError> {
let name = tool.name().to_owned();
check_name(&name)?;
check_description(&name, tool.description())?;
let registered = RegisteredTool {
kind: ToolKind::Custom,
description: tool.description().to_string(),
parameters: Value::Null,
format: tool.format(),
supports_parallel: tool.supports_parallel(),
output_budget: tool.output_budget(),
exposure: tool.exposure(),
raw_name: None,
handler: Box::new(CustomAdapter(tool)),
};
self.insert(key(namespace, name), registered)
}
fn insert(&mut self, key: ToolKey, tool: RegisteredTool) -> std::result::Result<(), ToolError> {
if key.namespace.is_none() && self.namespaces.contains_key(&key.name) {
return Err(ToolError::Duplicate { name: key.name });
}
match self.tools.entry(key) {
Entry::Occupied(entry) => Err(ToolError::Duplicate {
name: entry.key().name.clone(),
}),
Entry::Vacant(entry) => {
entry.insert(tool);
Ok(())
}
}
}
#[must_use]
pub fn tool_definitions(&self) -> Vec<ChatCompletionTool> {
self.chat_tools_where(|_, exposure| exposure == Exposure::Direct)
}
pub(crate) fn chat_tools_where(
&self,
show: impl Fn(&ToolKey, Exposure) -> bool,
) -> Vec<ChatCompletionTool> {
self.tools
.iter()
.filter(|(key, tool)| {
key.namespace.is_none()
&& tool.kind == ToolKind::Function
&& show(key, tool.exposure)
})
.map(|(key, tool)| tool_function(&key.name, &tool.description, tool.parameters.clone()))
.collect()
}
#[must_use]
pub fn responses_tools(&self) -> Vec<ResponsesTool> {
self.responses_tools_where(|_, exposure| {
(exposure == Exposure::Direct).then_some(Advertise::Plain)
})
}
pub(crate) fn responses_tools_where(
&self,
show: impl Fn(&ToolKey, Exposure) -> Option<Advertise>,
) -> Vec<ResponsesTool> {
let mut tools: Vec<ResponsesTool> = self
.tools
.iter()
.filter(|(key, _)| key.namespace.is_none())
.filter_map(|(key, tool)| {
let advertise = show(key, tool.exposure)?;
Some(match (tool.kind.clone(), advertise) {
(ToolKind::Function, Advertise::Plain) => {
crate::responses_api::responses_function_tool(
&key.name,
&tool.description,
tool.parameters.clone(),
)
}
(_, advertise) => {
to_tool(tool.responses_json(&key.name, advertise == Advertise::Deferred))
}
})
})
.collect();
for (namespace, description) in &self.namespaces {
let members: Vec<Value> = self
.tools
.iter()
.filter(|(key, _)| key.namespace.as_deref() == Some(namespace.as_str()))
.filter_map(|(key, tool)| {
let advertise = show(key, tool.exposure)?;
Some(tool.responses_json(&key.name, advertise == Advertise::Deferred))
})
.collect();
if members.is_empty() {
continue;
}
tools.push(to_tool(json!({
"type": "namespace",
"name": namespace,
"description": description,
"tools": members,
})));
}
tools
}
#[must_use]
pub fn exposure(&self, key: &ToolKey) -> Option<Exposure> {
self.tools.get(key).map(|tool| tool.exposure)
}
pub fn set_exposure(&mut self, key: &ToolKey, exposure: Exposure) -> bool {
self.tools.get_mut(key).is_some_and(|tool| {
tool.exposure = exposure;
true
})
}
#[must_use]
pub fn search_deferred(&self, query: &str, limit: usize) -> Vec<ToolKey> {
let query = search::words(query);
let mut scored: Vec<(usize, &ToolKey)> = self
.tools
.iter()
.filter(|(_, tool)| tool.exposure == Exposure::Deferred)
.filter_map(|(key, tool)| {
let mut names = search::words(&key.name);
if let Some(namespace) = &key.namespace {
names.extend(search::words(namespace));
}
let description = search::words(&tool.description);
let score = search::score(&query, &names, &description);
(score > 0).then_some((score, key))
})
.collect();
scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(b.1)));
scored
.into_iter()
.take(limit)
.map(|(_, key)| key.clone())
.collect()
}
#[must_use]
pub fn description(&self, key: &ToolKey) -> Option<&str> {
self.tools.get(key).map(|tool| tool.description.as_str())
}
pub fn keys(&self) -> impl Iterator<Item = &ToolKey> {
self.tools.keys()
}
#[must_use]
pub fn len(&self) -> usize {
self.tools.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.tools.is_empty()
}
#[must_use]
pub fn raw_name(&self, name: &str) -> Option<&str> {
self.tools.get(&ToolKey::new(name))?.raw_name.as_deref()
}
#[must_use]
pub fn supports_parallel(&self, call: &ToolInvocation) -> bool {
self.tools
.get(&ToolKey::of(call))
.is_some_and(|tool| tool.supports_parallel)
}
#[must_use]
pub fn output_budget(&self, call: &ToolInvocation) -> Option<OutputBudget> {
self.tools.get(&ToolKey::of(call))?.output_budget
}
pub async fn execute(
&self,
name: &str,
arguments: &str,
) -> std::result::Result<Value, ToolError> {
let tool = self
.tools
.get(&ToolKey::new(name))
.filter(|tool| tool.kind == ToolKind::Function)
.ok_or_else(|| ToolError::Unknown { name: name.into() })?;
tool.handler
.call(name, arguments)
.await
.map(ErasedOutput::into_value)
}
pub async fn execute_call(
&self,
call: &ChatCompletionMessageToolCallsInner,
) -> std::result::Result<ToolOutput, ToolError> {
let result = async {
if call.id().is_empty() {
return Err(ToolError::InvalidCall {
reason: "call identifier must not be empty".into(),
});
}
let ChatCompletionMessageToolCallsInner::ChatCompletionMessageToolCall(function_call) =
call
else {
return Err(ToolError::InvalidCall {
reason: "only function tool calls are supported".into(),
});
};
let name = &function_call.function.name;
let tool = self
.tools
.get(&ToolKey::new(name.as_str()))
.filter(|tool| tool.kind == ToolKind::Function)
.ok_or_else(|| ToolError::Unknown { name: name.clone() })?;
let output = tool
.handler
.call(name, &function_call.function.arguments)
.await?;
Ok(ToolOutput {
call_id: call.id().into(),
content: output.into_body().to_chat_text()?,
})
}
.await;
result.map_err(|source| ToolError::Call {
call_id: call.id().into(),
source: Box::new(source),
})
}
pub async fn answer_call(
&self,
call: impl Into<ToolInvocation>,
) -> std::result::Result<CallAnswer, ToolError> {
self.answer_call_with(call, ToolError::classify).await
}
pub async fn answer_call_with(
&self,
call: impl Into<ToolInvocation>,
classify: impl FnOnce(ToolError) -> ToolFailure,
) -> std::result::Result<CallAnswer, ToolError> {
let call = call.into();
if call.call_id.is_empty() {
return Err(ToolError::Call {
call_id: String::new(),
source: Box::new(ToolError::InvalidCall {
reason: "call identifier must not be empty".into(),
}),
});
}
match self.run(&call).await {
Ok(output) => Ok(CallAnswer::new(&call, output, true)),
Err(error) => match classify(error) {
ToolFailure::Fatal(error) => Err(ToolError::Call {
call_id: call.call_id.clone(),
source: Box::new(error),
}),
ToolFailure::RespondToModel(message) => Ok(CallAnswer::failure(&call, message)),
},
}
}
async fn run(&self, call: &ToolInvocation) -> std::result::Result<ToolOutputBody, ToolError> {
if let ToolKind::Other(kind) = &call.kind {
return Err(ToolError::InvalidCall {
reason: format!("unsupported call type {kind:?}"),
});
}
let Some(tool) = self.tools.get(&ToolKey::of(call)) else {
let name = call.namespace.as_ref().map_or_else(
|| call.name.clone(),
|namespace| format!("{namespace}.{}", call.name),
);
return Err(ToolError::Unknown { name });
};
if tool.kind != call.kind {
let reason = match tool.kind {
ToolKind::Custom => format!("{} is a custom tool: send text input", call.name),
_ => format!("{} is a function tool: send JSON arguments", call.name),
};
return Err(ToolError::InvalidCall { reason });
}
tool.handler
.call(&call.name, &call.input)
.await
.map(ErasedOutput::into_body)
}
}
impl From<&ToolInvocation> for ToolInvocation {
fn from(call: &ToolInvocation) -> Self {
call.clone()
}
}
#[derive(Debug)]
pub struct NamespaceRegistrar<'a> {
registry: &'a mut ToolRegistry,
namespace: String,
}
impl NamespaceRegistrar<'_> {
pub fn register<T: FunctionTool + 'static>(
&mut self,
tool: T,
) -> std::result::Result<&mut Self, ToolError> {
self.registry
.register_function_in(Some(&self.namespace), tool)?;
Ok(self)
}
pub fn register_rich<T: RichTool + 'static>(
&mut self,
tool: T,
) -> std::result::Result<&mut Self, ToolError> {
self.registry
.register_rich_in(Some(&self.namespace), tool)?;
Ok(self)
}
pub fn register_custom<T: CustomTool + 'static>(
&mut self,
tool: T,
) -> std::result::Result<&mut Self, ToolError> {
self.registry
.register_custom_in(Some(&self.namespace), tool)?;
Ok(self)
}
}
fn key(namespace: Option<&str>, name: String) -> ToolKey {
ToolKey {
namespace: namespace.map(str::to_string),
name,
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Advertise {
Plain,
Deferred,
}
fn to_tool(value: Value) -> ResponsesTool {
serde_json::from_value(value.clone()).unwrap_or(ResponsesTool::Unknown(value))
}