use std::collections::BTreeSet;
use rig_core::message::{Message, ToolCall, ToolChoice, ToolName};
use serde::{Deserialize, Serialize};
use super::prepare::PrepareError;
use super::response::PromptError;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "reason", rename_all = "snake_case")]
#[non_exhaustive]
pub enum InvalidToolCallReason {
UnknownTool,
DisallowedByToolChoice,
MalformedArguments {
error: String,
},
}
impl InvalidToolCallReason {
pub fn malformed_arguments(raw: &str) -> Self {
Self::MalformedArguments {
error: arguments_parse_error(raw),
}
}
}
pub(crate) fn arguments_parse_error(raw: &str) -> String {
match serde_json::from_str::<serde_json::Value>(raw) {
Err(error) => error.to_string(),
Ok(value) => format!("expected a JSON object, found {}", json_kind(&value)),
}
}
fn json_kind(value: &serde_json::Value) -> &'static str {
match value {
serde_json::Value::Null => "null",
serde_json::Value::Bool(_) => "a boolean",
serde_json::Value::Number(_) => "a number",
serde_json::Value::String(_) => "a string",
serde_json::Value::Array(_) => "an array",
serde_json::Value::Object(_) => "an object",
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct InvalidToolCallContext {
pub tool_name: String,
pub tool_call_id: Option<rig_core::message::CallId>,
pub args: Option<String>,
pub available_tools: Vec<String>,
pub allowed_tools: Vec<String>,
pub tool_choice: Option<ToolChoice>,
pub chat_history: Vec<Message>,
pub is_streaming: bool,
pub reason: InvalidToolCallReason,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "TurnPolicyRepr")]
pub struct TurnPolicy {
executable: BTreeSet<String>,
tool_choice: Option<ToolChoice>,
output_tool: Option<String>,
#[serde(skip_serializing)]
allowed: BTreeSet<String>,
}
#[derive(Deserialize)]
struct TurnPolicyRepr {
executable: BTreeSet<String>,
tool_choice: Option<ToolChoice>,
output_tool: Option<String>,
}
impl TryFrom<TurnPolicyRepr> for TurnPolicy {
type Error = PrepareError;
fn try_from(repr: TurnPolicyRepr) -> Result<Self, Self::Error> {
Self::new(repr.executable, repr.tool_choice, repr.output_tool)
}
}
impl TurnPolicy {
pub fn new(
executable: BTreeSet<String>,
tool_choice: Option<ToolChoice>,
output_tool: Option<String>,
) -> Result<Self, PrepareError> {
Self::resolve(executable, tool_choice, output_tool, None)
}
pub(crate) fn resolve(
executable: BTreeSet<String>,
tool_choice: Option<ToolChoice>,
output_tool: Option<String>,
pre_filter: Option<&BTreeSet<String>>,
) -> Result<Self, PrepareError> {
let output = output_tool.as_deref();
let hint = |active_tools_caused: bool| {
if active_tools_caused {
" A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
} else {
""
}
};
let mut allowed = match &tool_choice {
Some(ToolChoice::Required) if executable.is_empty() && output.is_none() => {
return Err(PrepareError::Request(format!(
"ToolChoice::Required forces the model to call a tool, but no tools are \
advertised this turn.{}",
hint(pre_filter.is_some_and(|pf| !pf.is_empty()))
)));
}
None | Some(ToolChoice::Auto | ToolChoice::Required) => executable.clone(),
Some(ToolChoice::None) => BTreeSet::new(),
Some(ToolChoice::Specific { function_names }) => {
if function_names.is_empty() {
return Err(PrepareError::Request(
"ToolChoice::Specific requires at least one function name".to_string(),
));
}
let missing = function_names
.iter()
.map(ToolName::as_str)
.filter(|name| !executable.contains(*name) && Some(*name) != output)
.collect::<Vec<_>>();
if !missing.is_empty() {
let advertised: Vec<_> = executable
.iter()
.map(String::as_str)
.chain(output)
.collect();
return Err(PrepareError::Request(format!(
"ToolChoice::Specific requested tool names not advertised this turn: \
{missing:?}. Advertised: {advertised:?}.{}",
hint(pre_filter.is_some_and(|pf| missing.iter().any(|n| pf.contains(*n))))
)));
}
function_names.iter().map(ToString::to_string).collect()
}
};
if let Some(name) = &output_tool {
allowed.insert(name.clone());
}
Ok(Self {
executable,
tool_choice,
output_tool,
allowed,
})
}
pub fn executable(&self) -> &BTreeSet<String> {
&self.executable
}
pub fn allowed(&self) -> &BTreeSet<String> {
&self.allowed
}
pub fn tool_choice(&self) -> Option<&ToolChoice> {
self.tool_choice.as_ref()
}
pub fn output_tool(&self) -> Option<&str> {
self.output_tool.as_deref()
}
pub fn forbids_calls(&self) -> bool {
matches!(self.tool_choice, Some(ToolChoice::None))
}
pub fn allows(&self, name: &str) -> bool {
self.allowed.contains(name)
}
pub(crate) fn unknown_call(
&self,
tool_name: String,
chat_history: Vec<Message>,
) -> PromptError {
PromptError::UnknownToolCall {
tool_name,
available_tools: self.executable.iter().cloned().collect(),
allowed_tools: self.allowed.iter().cloned().collect(),
chat_history,
}
}
pub(crate) fn name_reason(&self, call: &ToolCall) -> InvalidToolCallReason {
if self.executable.contains(call.function.name.as_str()) {
InvalidToolCallReason::DisallowedByToolChoice
} else {
InvalidToolCallReason::UnknownTool
}
}
pub fn invalid_call_context(
&self,
call: &ToolCall,
args: Option<String>,
chat_history: Vec<Message>,
is_streaming: bool,
reason: InvalidToolCallReason,
) -> InvalidToolCallContext {
InvalidToolCallContext {
tool_name: call.function.name.to_string(),
tool_call_id: Some(call.id.clone()),
args,
available_tools: self.executable.iter().cloned().collect(),
allowed_tools: self.allowed.iter().cloned().collect(),
tool_choice: self.tool_choice.clone(),
chat_history,
is_streaming,
reason,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum RetryRequest {
Repeat,
Feedback(String),
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum InvalidToolCallAction {
Fail,
Retry {
feedback: String,
},
Repair {
tool_name: String,
},
Skip {
reason: String,
},
Stop {
reason: String,
},
}
impl InvalidToolCallAction {
pub fn fail() -> Self {
Self::Fail
}
pub fn retry(feedback: impl Into<String>) -> Self {
Self::Retry {
feedback: feedback.into(),
}
}
pub fn repair(tool_name: impl Into<String>) -> Self {
Self::Repair {
tool_name: tool_name.into(),
}
}
pub fn skip(reason: impl Into<String>) -> Self {
Self::Skip {
reason: reason.into(),
}
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Stop {
reason: reason.into(),
}
}
}
#[cfg(test)]
mod tests;