1use std::collections::BTreeSet;
10
11use rig_core::message::{Message, ToolCall, ToolChoice, ToolName};
12use serde::{Deserialize, Serialize};
13
14use super::response::PromptError;
15use rig_core::error::ProviderError;
16
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(tag = "reason", rename_all = "snake_case")]
23#[non_exhaustive]
24pub enum InvalidToolCallReason {
25 UnknownTool,
27 DisallowedByToolChoice,
29 MalformedArguments {
32 error: String,
34 },
35}
36
37impl InvalidToolCallReason {
38 pub fn malformed_arguments(raw: &str) -> Self {
41 Self::MalformedArguments {
42 error: arguments_parse_error(raw),
43 }
44 }
45}
46
47pub(crate) fn arguments_parse_error(raw: &str) -> String {
49 match serde_json::from_str::<serde_json::Value>(raw) {
50 Err(error) => error.to_string(),
51 Ok(value) => format!("expected a JSON object, found {}", json_kind(&value)),
52 }
53}
54
55fn json_kind(value: &serde_json::Value) -> &'static str {
56 match value {
57 serde_json::Value::Null => "null",
58 serde_json::Value::Bool(_) => "a boolean",
59 serde_json::Value::Number(_) => "a number",
60 serde_json::Value::String(_) => "a string",
61 serde_json::Value::Array(_) => "an array",
62 serde_json::Value::Object(_) => "an object",
63 }
64}
65
66#[derive(Debug, Clone, Serialize, Deserialize)]
68#[non_exhaustive]
69pub struct InvalidToolCallContext {
70 pub tool_name: String,
72 pub tool_call_id: Option<rig_core::message::CallId>,
75 pub args: Option<String>,
79 pub available_tools: Vec<String>,
81 pub allowed_tools: Vec<String>,
83 pub tool_choice: Option<ToolChoice>,
85 pub chat_history: Vec<Message>,
87 pub is_streaming: bool,
89 pub reason: InvalidToolCallReason,
91}
92
93#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
99#[serde(try_from = "TurnPolicyRepr")]
100pub struct TurnPolicy {
101 executable: BTreeSet<String>,
102 tool_choice: Option<ToolChoice>,
103 output_tool: Option<String>,
104 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
106 hosted: bool,
107 #[serde(skip_serializing)]
108 allowed: BTreeSet<String>,
109}
110
111#[derive(Deserialize)]
112struct TurnPolicyRepr {
113 executable: BTreeSet<String>,
114 tool_choice: Option<ToolChoice>,
115 output_tool: Option<String>,
116 #[serde(default)]
117 hosted: bool,
118}
119
120impl TryFrom<TurnPolicyRepr> for TurnPolicy {
121 type Error = ProviderError;
122
123 fn try_from(repr: TurnPolicyRepr) -> Result<Self, Self::Error> {
124 Self::resolve(
125 repr.executable,
126 repr.tool_choice,
127 repr.output_tool,
128 None,
129 repr.hosted,
130 )
131 }
132}
133
134impl TurnPolicy {
135 pub fn new(
143 executable: BTreeSet<String>,
144 tool_choice: Option<ToolChoice>,
145 output_tool: Option<String>,
146 ) -> Result<Self, ProviderError> {
147 Self::resolve(executable, tool_choice, output_tool, None, false)
148 }
149
150 pub(crate) fn resolve(
155 executable: BTreeSet<String>,
156 tool_choice: Option<ToolChoice>,
157 output_tool: Option<String>,
158 pre_filter: Option<&BTreeSet<String>>,
159 hosted: bool,
160 ) -> Result<Self, ProviderError> {
161 let output = output_tool.as_deref();
162 let hint = |active_tools_caused: bool| {
163 if active_tools_caused {
164 " A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
165 set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
166 } else {
167 ""
168 }
169 };
170
171 let mut allowed = match &tool_choice {
172 Some(ToolChoice::Required) if executable.is_empty() && output.is_none() && !hosted => {
173 return Err(ProviderError::request(format!(
174 "ToolChoice::Required forces the model to call a tool, but no tools are \
175 advertised this turn.{}",
176 hint(pre_filter.is_some_and(|pf| !pf.is_empty()))
177 )));
178 }
179 None | Some(ToolChoice::Auto | ToolChoice::Required) => executable.clone(),
180 Some(ToolChoice::None) => BTreeSet::new(),
181 Some(ToolChoice::Specific { function_names }) => {
182 if function_names.is_empty() {
183 return Err(ProviderError::request(
184 "ToolChoice::Specific requires at least one function name".to_string(),
185 ));
186 }
187 let missing = function_names
188 .iter()
189 .map(ToolName::as_str)
190 .filter(|name| !executable.contains(*name) && Some(*name) != output)
191 .collect::<Vec<_>>();
192 if !missing.is_empty() {
193 let advertised: Vec<_> = executable
194 .iter()
195 .map(String::as_str)
196 .chain(output)
197 .collect();
198 return Err(ProviderError::request(format!(
200 "ToolChoice::Specific requested tool names not advertised this turn: \
201 {missing:?}. Advertised: {advertised:?}.{}",
202 hint(pre_filter.is_some_and(|pf| missing.iter().any(|n| pf.contains(*n))))
203 )));
204 }
205 function_names.iter().map(ToString::to_string).collect()
206 }
207 };
208 if let Some(name) = &output_tool {
211 allowed.insert(name.clone());
212 }
213
214 Ok(Self {
215 executable,
216 tool_choice,
217 output_tool,
218 hosted,
219 allowed,
220 })
221 }
222
223 pub fn executable(&self) -> &BTreeSet<String> {
225 &self.executable
226 }
227
228 pub fn tool_choice(&self) -> Option<&ToolChoice> {
230 self.tool_choice.as_ref()
231 }
232
233 pub fn output_tool(&self) -> Option<&str> {
236 self.output_tool.as_deref()
237 }
238
239 pub fn forbids_calls(&self) -> bool {
242 matches!(self.tool_choice, Some(ToolChoice::None))
243 }
244
245 pub fn allows(&self, name: &str) -> bool {
247 self.allowed.contains(name)
248 }
249
250 pub(crate) fn unknown_call(
252 &self,
253 tool_name: String,
254 chat_history: Vec<Message>,
255 ) -> PromptError {
256 PromptError::UnknownToolCall {
257 tool_name,
258 available_tools: self.executable.iter().cloned().collect(),
259 allowed_tools: self.allowed.iter().cloned().collect(),
260 chat_history,
261 }
262 }
263
264 pub(crate) fn name_reason(&self, call: &ToolCall) -> InvalidToolCallReason {
267 if self.executable.contains(call.function.name.as_str()) {
268 InvalidToolCallReason::DisallowedByToolChoice
269 } else {
270 InvalidToolCallReason::UnknownTool
271 }
272 }
273
274 pub fn invalid_call_context(
277 &self,
278 call: &ToolCall,
279 args: Option<String>,
280 chat_history: Vec<Message>,
281 is_streaming: bool,
282 reason: InvalidToolCallReason,
283 ) -> InvalidToolCallContext {
284 InvalidToolCallContext {
285 tool_name: call.function.name.to_string(),
286 tool_call_id: Some(call.id.clone()),
287 args,
288 available_tools: self.executable.iter().cloned().collect(),
289 allowed_tools: self.allowed.iter().cloned().collect(),
290 tool_choice: self.tool_choice.clone(),
291 chat_history,
292 is_streaming,
293 reason,
294 }
295 }
296}
297
298#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
300pub enum RetryRequest {
301 Repeat,
307 Feedback(String),
309}
310
311#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
313#[non_exhaustive]
314pub enum InvalidToolCallAction {
315 Fail,
317 Retry {
319 feedback: String,
321 },
322 Repair {
324 tool_name: String,
326 },
327 Skip {
329 reason: String,
331 },
332 Stop {
334 reason: String,
336 },
337}
338
339impl InvalidToolCallAction {
340 pub fn fail() -> Self {
342 Self::Fail
343 }
344
345 pub fn retry(feedback: impl Into<String>) -> Self {
347 Self::Retry {
348 feedback: feedback.into(),
349 }
350 }
351
352 pub fn repair(tool_name: impl Into<String>) -> Self {
354 Self::Repair {
355 tool_name: tool_name.into(),
356 }
357 }
358
359 pub fn skip(reason: impl Into<String>) -> Self {
361 Self::Skip {
362 reason: reason.into(),
363 }
364 }
365
366 pub fn stop(reason: impl Into<String>) -> Self {
368 Self::Stop {
369 reason: reason.into(),
370 }
371 }
372}
373
374#[cfg(test)]
375mod tests;