use serde_json::Value;
use thiserror::Error;
const DEFAULT_MAX_INDEX: usize = 1024;
#[derive(Debug, Clone, Default)]
pub struct StreamingToolCallFunction {
pub name: Option<String>,
pub arguments: Option<String>,
}
#[derive(Debug, Clone, Default)]
pub struct StreamingToolCallDelta {
pub index: Option<usize>,
pub id: Option<String>,
pub r#type: Option<String>,
pub function: Option<StreamingToolCallFunction>,
pub extra: Value,
}
impl StreamingToolCallDelta {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn index(mut self, index: usize) -> Self {
self.index = Some(index);
self
}
#[must_use]
pub fn id(mut self, id: impl Into<String>) -> Self {
self.id = Some(id.into());
self
}
#[must_use]
pub fn tool_type(mut self, t: impl Into<String>) -> Self {
self.r#type = Some(t.into());
self
}
#[must_use]
pub fn function_name(mut self, name: impl Into<String>) -> Self {
self.function.get_or_insert_with(Default::default).name = Some(name.into());
self
}
#[must_use]
pub fn arguments(mut self, args: impl Into<String>) -> Self {
self.function.get_or_insert_with(Default::default).arguments = Some(args.into());
self
}
#[must_use]
pub fn extra(mut self, extra: Value) -> Self {
self.extra = extra;
self
}
}
#[derive(Debug, Clone, PartialEq)]
pub enum ToolCallStreamPart<M = ()> {
ToolInputStart { id: String, tool_name: String },
ToolInputDelta { id: String, delta: String },
ToolInputEnd { id: String },
ToolCall {
tool_call_id: String,
tool_name: String,
input: String,
provider_metadata: Option<M>,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TypeValidation {
#[default]
None,
IfPresent,
Required,
}
#[derive(Debug, Error, PartialEq)]
pub enum TrackerError {
#[error("Expected 'id' to be a string.")]
MissingId,
#[error("Expected 'function.name' to be a string.")]
MissingFunctionName,
#[error("Expected 'function' type.")]
InvalidType,
#[error("Tool call index out of range")]
IndexOutOfRange,
}
struct TrackedToolCall<M> {
id: String,
function_name: String,
arguments: String,
has_finished: bool,
metadata: Option<M>,
}
type ExtractMetadataFn<M> = Box<dyn Fn(&StreamingToolCallDelta) -> Option<M>>;
type BuildMetadataFn<M> = Box<dyn Fn(Option<&M>) -> Option<M>>;
pub struct StreamingToolCallTracker<M = ()> {
tool_calls: Vec<Option<TrackedToolCall<M>>>,
parts: Vec<ToolCallStreamPart<M>>,
generate_id: Box<dyn Fn() -> String>,
type_validation: TypeValidation,
max_index: usize,
extract_metadata: Option<ExtractMetadataFn<M>>,
build_provider_metadata: Option<BuildMetadataFn<M>>,
}
impl Default for StreamingToolCallTracker<()> {
fn default() -> Self {
Self::new()
}
}
impl<M> StreamingToolCallTracker<M> {
#[must_use]
pub fn new() -> Self {
Self {
tool_calls: Vec::new(),
parts: Vec::new(),
generate_id: Box::new(|| "generated".to_string()),
type_validation: TypeValidation::None,
max_index: DEFAULT_MAX_INDEX,
extract_metadata: None,
build_provider_metadata: None,
}
}
#[must_use]
pub fn with_generate_id<F: Fn() -> String + 'static>(mut self, f: F) -> Self {
self.generate_id = Box::new(f);
self
}
#[must_use]
pub fn with_type_validation(mut self, v: TypeValidation) -> Self {
self.type_validation = v;
self
}
#[must_use]
pub fn with_max_index(mut self, max_index: usize) -> Self {
self.max_index = max_index;
self
}
#[must_use]
pub fn with_extract_metadata<F: Fn(&StreamingToolCallDelta) -> Option<M> + 'static>(
mut self,
f: F,
) -> Self {
self.extract_metadata = Some(Box::new(f));
self
}
#[must_use]
pub fn with_build_provider_metadata<F: Fn(Option<&M>) -> Option<M> + 'static>(
mut self,
f: F,
) -> Self {
self.build_provider_metadata = Some(Box::new(f));
self
}
pub fn process_delta(&mut self, delta: &StreamingToolCallDelta) -> Result<(), TrackerError> {
let index = delta.index.unwrap_or(self.tool_calls.len());
if index > self.max_index {
return Err(TrackerError::IndexOutOfRange);
}
let is_new = self
.tool_calls
.get(index)
.map(std::option::Option::is_none)
.unwrap_or(true);
if is_new {
self.process_new_tool_call(index, delta)?;
} else {
self.process_existing_tool_call(index, delta);
}
Ok(())
}
pub fn flush(&mut self) {
for i in 0..self.tool_calls.len() {
let needs_finish = self
.tool_calls
.get(i)
.and_then(|o| o.as_ref())
.is_some_and(|tc| !tc.has_finished);
if needs_finish {
self.finish_tool_call_at(i);
}
}
}
#[must_use]
pub fn parts(&self) -> &[ToolCallStreamPart<M>] {
&self.parts
}
pub fn clear_parts(&mut self) {
self.parts.clear();
}
fn process_new_tool_call(
&mut self,
index: usize,
delta: &StreamingToolCallDelta,
) -> Result<(), TrackerError> {
match self.type_validation {
TypeValidation::Required => {
if delta.r#type.as_deref() != Some("function") {
return Err(TrackerError::InvalidType);
}
}
TypeValidation::IfPresent => {
if delta.r#type.as_deref().is_some_and(|t| t != "function") {
return Err(TrackerError::InvalidType);
}
}
TypeValidation::None => {}
}
let id = delta.id.clone().unwrap_or_else(|| (self.generate_id)());
let function_name = delta
.function
.as_ref()
.and_then(|f| f.name.clone())
.ok_or(TrackerError::MissingFunctionName)?;
self.parts.push(ToolCallStreamPart::ToolInputStart {
id: id.clone(),
tool_name: function_name.clone(),
});
let metadata = self
.extract_metadata
.as_ref()
.and_then(|extract| extract(delta));
let arguments = delta
.function
.as_ref()
.and_then(|f| f.arguments.clone())
.unwrap_or_default();
if index >= self.tool_calls.len() {
self.tool_calls.resize_with(index + 1, || None);
}
self.tool_calls[index] = Some(TrackedToolCall {
id: id.clone(),
function_name: function_name.clone(),
arguments: arguments.clone(),
has_finished: false,
metadata,
});
if !arguments.is_empty() {
self.parts.push(ToolCallStreamPart::ToolInputDelta {
id: id.clone(),
delta: arguments,
});
}
Ok(())
}
fn process_existing_tool_call(&mut self, index: usize, delta: &StreamingToolCallDelta) {
let new_args = match delta.function.as_ref().and_then(|f| f.arguments.as_ref()) {
Some(args) => args.clone(),
None => return,
};
let id = {
let Some(Some(tool_call)) = self.tool_calls.get_mut(index) else {
return;
};
if tool_call.has_finished {
return;
}
tool_call.arguments.push_str(&new_args);
tool_call.id.clone()
};
self.parts.push(ToolCallStreamPart::ToolInputDelta {
id,
delta: new_args,
});
}
fn finish_tool_call_at(&mut self, index: usize) {
let (id, function_name, arguments, metadata) = {
let Some(Some(tool_call)) = self.tool_calls.get_mut(index) else {
return;
};
if tool_call.has_finished {
return;
}
(
tool_call.id.clone(),
tool_call.function_name.clone(),
tool_call.arguments.clone(),
tool_call.metadata.take(),
)
};
if let Some(Some(tool_call)) = self.tool_calls.get_mut(index) {
tool_call.has_finished = true;
}
self.parts
.push(ToolCallStreamPart::ToolInputEnd { id: id.clone() });
let provider_metadata = self
.build_provider_metadata
.as_ref()
.and_then(|build| build(metadata.as_ref()));
self.parts.push(ToolCallStreamPart::ToolCall {
tool_call_id: id,
tool_name: function_name,
input: arguments,
provider_metadata,
});
}
}