use std::sync::Arc;
use indexmap::IndexMap;
use rig_core::serve::adapters::ToolAdapter;
use rig_core::serve::{ErasedHandler, Serve};
use rig_core::{
completion::ToolDefinition,
effect::{
Answered, EffectKind, FamilyDescriptor, Key, ToolEmbeddingDescriptor, family, tool_key,
},
embeddings::{embed::EmbedError, tool::ToolSchema},
error::{ErrorKind, ErrorReport},
message::ToolName,
tool::{
DynamicTool, LivenessFn, Tool, ToolContext, ToolEmbedding, ToolExecutionError, ToolResult,
tool_definition,
},
};
use super::catalog::ToolCatalog;
#[derive(Clone)]
pub struct RegisteredTool {
definition: Arc<ToolDefinition>,
embedding: Option<ToolEmbeddingDescriptor>,
key: Key<family::Tool>,
handler: ErasedHandler,
liveness: Option<LivenessFn>,
}
impl std::fmt::Debug for RegisteredTool {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RegisteredTool")
.field("name", &self.definition.name)
.field("key", &self.key)
.field("retrievable", &self.embedding.is_some())
.finish_non_exhaustive()
}
}
impl RegisteredTool {
pub fn from_tool<T>(tool: T) -> Self
where
T: Tool + 'static,
{
let definition = tool_definition(&tool);
Self::from_parts(
definition,
None,
ErasedHandler::new(ToolAdapter::new(tool)),
None,
)
}
pub fn from_retrievable<T>(tool: T) -> Result<Self, serde_json::Error>
where
T: ToolEmbedding + 'static,
{
let adapter = ToolAdapter::retrievable(tool)?;
let definition = tool_definition(adapter.tool());
let embedding = adapter.embedding().cloned();
Ok(Self::from_parts(
definition,
embedding,
ErasedHandler::new(adapter),
None,
))
}
pub fn from_dynamic(tool: DynamicTool) -> Self {
let (definition, handler, liveness) = tool.into_parts();
Self::from_parts(definition, None, handler, liveness)
}
pub fn from_handler(handler: impl Serve + 'static) -> Result<Self, ErrorReport> {
let descriptor = handler.descriptor();
let FamilyDescriptor::Tool {
name,
description,
parameters,
embedding,
} = descriptor.family
else {
return Err(ErrorReport::new(
ErrorKind::HandlerUnavailable,
format!(
"handler `{}` serves the {} family, not tool_call",
descriptor.key,
descriptor.family.family()
),
));
};
let name = ToolName::new(name).map_err(|_| {
ErrorReport::new(
ErrorKind::HandlerUnavailable,
format!(
"handler `{}` serves a tool with an empty name",
descriptor.key
),
)
})?;
Ok(Self {
definition: Arc::new(ToolDefinition {
name,
description,
parameters,
annotations: Default::default(),
}),
embedding,
key: Key::new_unchecked(descriptor.key),
handler: ErasedHandler::new(handler),
liveness: None,
})
}
pub(crate) fn has_default_key(&self) -> bool {
*self.key.raw() == tool_key(&self.definition.name)
}
fn from_parts(
definition: ToolDefinition,
embedding: Option<ToolEmbeddingDescriptor>,
handler: ErasedHandler,
liveness: Option<LivenessFn>,
) -> Self {
let key = Key::new_unchecked(tool_key(&definition.name));
Self {
definition: Arc::new(definition),
embedding,
key,
handler,
liveness,
}
}
pub fn with_key(mut self, key: Key<family::Tool>) -> Self {
self.key = key;
self
}
pub fn name(&self) -> String {
self.definition.name.to_string()
}
pub fn key(&self) -> &Key<family::Tool> {
&self.key
}
pub fn handler(&self) -> &ErasedHandler {
&self.handler
}
pub(crate) fn definition(&self) -> Arc<ToolDefinition> {
Arc::clone(&self.definition)
}
pub fn embedding(&self) -> Option<&ToolEmbeddingDescriptor> {
self.embedding.as_ref()
}
pub fn is_live(&self) -> bool {
self.liveness.as_ref().is_none_or(|probe| probe())
}
pub async fn execute(&self, args: String, context: &mut ToolContext) -> ToolResult {
let name = self.definition.name.to_string();
let published = rig_core::tool::PublishedContext::new();
let outcome = rig_core::serve::serve_inline_with(
&self.handler,
EffectKind::ToolCall { name, args },
vec![
std::sync::Arc::new(context.for_dispatch()),
published.clone() as std::sync::Arc<dyn std::any::Any + Send + Sync>,
],
)
.await;
context.accept_dispatch_result(published.take().unwrap_or_default());
match outcome {
Ok(Answered::ToolResult { result }) => result,
Ok(other) => ToolResult::failed(ToolExecutionError::other(format!(
"tool handler answered with a {} outcome",
other.family()
))),
Err(report) => ToolResult::failed(report.into()),
}
}
}
#[derive(Clone)]
pub(crate) struct ToolRegistration {
tool: RegisteredTool,
always_exposed: bool,
}
impl ToolRegistration {
fn new(tool: RegisteredTool, always_exposed: bool) -> Self {
Self {
tool,
always_exposed,
}
}
}
#[derive(Clone, Default)]
pub struct ToolSet {
pub(crate) tools: IndexMap<String, ToolRegistration>,
}
impl ToolSet {
pub fn from_tools<T>(tools: Vec<T>) -> Self
where
T: Tool + 'static,
{
let mut set = Self::default();
for tool in tools {
set.add_tool(tool);
}
set
}
pub fn contains(&self, name: &str) -> bool {
self.tools.contains_key(name)
}
pub fn add_tool<T>(&mut self, tool: T) -> String
where
T: Tool + 'static,
{
self.insert(RegisteredTool::from_tool(tool))
}
pub fn add_dynamic_tool(&mut self, tool: DynamicTool) -> String {
self.insert(RegisteredTool::from_dynamic(tool))
}
pub fn add_retrieved_tool<T>(&mut self, tool: T) -> Result<String, serde_json::Error>
where
T: ToolEmbedding + 'static,
{
RegisteredTool::from_retrievable(tool).map(|registered| self.insert(registered))
}
pub fn add_registered_tool(&mut self, tool: RegisteredTool) -> String {
self.insert(tool)
}
pub(crate) fn insert(&mut self, tool: RegisteredTool) -> String {
let name = tool.name();
self.insert_registration(name.clone(), ToolRegistration::new(tool, true));
name
}
fn insert_registration(&mut self, name: String, mut registration: ToolRegistration) {
if let Some(current) = self.tools.get_mut(&name) {
registration.always_exposed |= current.always_exposed;
*current = registration;
tracing::warn!(tool_name = %name, "replacing an existing tool registration");
} else {
self.tools.insert(name, registration);
}
}
pub fn remove_tool(&mut self, name: &str) {
self.tools.shift_remove(name);
}
pub fn add_tools(&mut self, set: ToolSet) {
for (name, registration) in set.tools {
self.insert_registration(name, registration);
}
}
pub fn add_retrievable_tools(&mut self, set: ToolSet) {
for (name, mut registration) in set.tools {
registration.always_exposed = false;
self.insert_registration(name, registration);
}
}
pub fn get(&self, name: &str) -> Option<&RegisteredTool> {
self.tools.get(name).map(|registration| ®istration.tool)
}
pub fn iter(&self) -> impl Iterator<Item = (&str, &RegisteredTool)> {
self.tools
.iter()
.map(|(name, registration)| (name.as_str(), ®istration.tool))
}
pub fn names(&self) -> impl Iterator<Item = &str> {
self.tools.keys().map(String::as_str)
}
pub fn len(&self) -> usize {
self.tools.len()
}
pub fn is_empty(&self) -> bool {
self.tools.is_empty()
}
pub fn always_exposed_names(&self) -> impl Iterator<Item = &str> {
self.tools
.iter()
.filter_map(|(name, registration)| registration.always_exposed.then_some(name.as_str()))
}
pub(crate) fn move_to_end(&mut self, name: &str) -> bool {
self.tools
.shift_remove_entry(name)
.is_some_and(|(name, registration)| {
self.tools.insert(name, registration);
true
})
}
pub fn catalog(&self) -> ToolCatalog {
ToolCatalog::from_registered(
self.tools
.iter()
.filter(|(_, registration)| registration.always_exposed)
.map(|(name, registration)| (name.clone(), registration.tool.clone()))
.collect(),
)
}
pub fn tool_definitions(&self) -> Vec<Arc<ToolDefinition>> {
self.tools
.values()
.map(|registration| registration.tool.definition())
.collect()
}
pub async fn execute(
&self,
name: &str,
args: impl Into<String>,
context: &mut ToolContext,
) -> ToolResult {
let Some(tool) = self.get(name) else {
context.clear_dispatch_result();
return ToolResult::failed(
ToolExecutionError::not_found(format!("no tool named `{name}` is registered"))
.with_model_feedback(format!("tool `{name}` not found")),
);
};
tracing::debug!(target: "rig", tool_name = name, "calling tool");
tool.execute(args.into(), context).await
}
pub fn schemas(&self) -> Result<Vec<ToolSchema>, EmbedError> {
Ok(self
.tools
.iter()
.filter_map(|(name, registration)| {
registration.tool.embedding().map(|embedding| ToolSchema {
name: name.clone(),
context: embedding.context.clone(),
embedding_docs: embedding.embedding_docs.clone(),
})
})
.collect())
}
}
#[cfg(test)]
mod tests;