1use std::collections::BTreeSet;
12
13use rig_core::completion::{
14 CompletionRequest, Document, Message, ProviderCapabilities, ToolDefinition,
15};
16use rig_core::error::ProviderError;
17use rig_core::message::ToolChoice;
18
19use super::output::OutputMode;
20use super::patch::RequestPatch;
21use super::spec::RunSpec;
22
23#[derive(Debug, thiserror::Error)]
27pub enum PrepareError {
28 #[error("{0}")]
31 Request(String),
32 #[error("invalid output schema: {0}")]
34 InvalidOutputSchema(#[source] serde_json::Error),
35}
36
37impl From<PrepareError> for ProviderError {
38 fn from(error: PrepareError) -> Self {
39 ProviderError::request(error.to_string())
40 }
41}
42
43#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
51pub struct PreparedRequest {
52 pub chat_history: Vec<Message>,
56 pub documents: Vec<Document>,
58 pub tools: Vec<ToolDefinition>,
62 pub temperature: Option<f64>,
64 pub max_tokens: Option<u64>,
66 pub additional_params: Option<serde_json::Value>,
69 pub tool_choice: Option<ToolChoice>,
71 pub output_schema: Option<rig_core::schemars::Schema>,
74 pub output_mode: OutputMode,
76 pub executable_tool_names: BTreeSet<String>,
78 pub allowed_tool_names: BTreeSet<String>,
81 pub output_tool_name: Option<String>,
84}
85
86impl PreparedRequest {
87 pub fn apply(self, request: CompletionRequest) -> CompletionRequest {
93 let request = request
94 .messages(self.chat_history)
95 .temperature(self.temperature)
96 .max_tokens(self.max_tokens)
97 .additional_params(self.additional_params)
98 .documents(self.documents)
99 .tools(self.tools)
100 .output_schema(self.output_schema);
101 match self.tool_choice {
102 Some(tool_choice) => request.tool_choice(tool_choice),
103 None => request,
104 }
105 }
106}
107
108pub fn prepare_request(
114 spec: &RunSpec,
115 capabilities: &ProviderCapabilities,
116 history: &[Message],
117 tools: Vec<ToolDefinition>,
118 committed_output_tool: Option<&str>,
119 patch: Option<&RequestPatch>,
120) -> Result<PreparedRequest, PrepareError> {
121 let request_patch = patch;
122 let chat_history = history;
123 let preamble = spec.preamble.as_deref();
124 let static_context = &spec.static_context;
125 let temperature = spec.temperature;
126 let max_tokens = spec.max_tokens;
127 let additional_params = spec.additional_params.as_ref();
128 let tool_choice = spec.tool_choice.as_ref();
129 let output_schema = spec.output_schema.as_ref();
130 let output_mode = &spec.output_mode;
131 let output_tool_description = spec.output_tool_description.as_deref();
132 let augment_output_preamble = spec.augment_output_preamble;
133 let preamble = request_patch
134 .and_then(|o| o.preamble.as_deref())
135 .or(preamble);
136 let temperature = request_patch.and_then(|o| o.temperature).or(temperature);
137 let max_tokens = request_patch.and_then(|o| o.max_tokens).or(max_tokens);
138 let tool_choice = request_patch
139 .and_then(|o| o.tool_choice.as_ref())
140 .or(tool_choice);
141 let additional_params: Option<serde_json::Value> = match (
144 additional_params,
145 request_patch.and_then(|o| o.additional_params.as_ref()),
146 ) {
147 (Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
148 Some(rig_core::json_utils::merge(base.clone(), patch.clone()))
149 }
150 (base, patch) => patch.or(base).cloned(),
151 };
152 let active_tools = request_patch.and_then(|o| o.active_tools.as_deref());
153
154 let pre_filter_tool_names: Option<BTreeSet<String>> =
157 active_tools.map(|_| tools.iter().map(|tool| tool.name.clone()).collect());
158
159 let mut tooldefs = tools;
162 if let Some(allow) = active_tools {
163 if let Some(missing) = allow
164 .iter()
165 .find(|name| !tooldefs.iter().any(|tool| &tool.name == *name))
166 {
167 return Err(PrepareError::Request(format!(
168 "active_tools requested tool `{missing}`, which is not available this turn"
169 )));
170 }
171 let allowed: BTreeSet<String> = allow.iter().cloned().collect();
172 tooldefs.retain(|tool| allowed.contains(&tool.name));
173 }
174
175 let executable_tool_names: BTreeSet<String> =
177 tooldefs.iter().map(|tool| tool.name.clone()).collect();
178
179 let candidate_output_tool = committed_output_tool.map_or_else(
182 || {
183 pick_output_tool_name(
184 pre_filter_tool_names
185 .as_ref()
186 .unwrap_or(&executable_tool_names),
187 )
188 },
189 str::to_owned,
190 );
191 let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
192 OutputMode::Tool
193 } else {
194 resolve_output_mode(
195 output_schema.is_some(),
196 !executable_tool_names.is_empty(),
197 output_tool_callable(tool_choice, &candidate_output_tool),
198 capabilities.composes_native_output_with_tools,
199 output_mode,
200 )
201 };
202
203 let output_tool_name =
204 matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
205
206 if let Some(name) = &output_tool_name
209 && executable_tool_names.contains(name)
210 {
211 return Err(PrepareError::Request(format!(
212 "real tool `{name}` conflicts with the structured-output tool reserved for this \
213 run; rename or remove the real tool, exclude it with `active_tools`, or make it \
214 visible before starting a new run so Rig can reserve a different output-tool name"
215 )));
216 }
217
218 if let Some(name) = &output_tool_name
221 && !output_tool_callable(tool_choice, name)
222 {
223 tracing::warn!(
224 "the active tool_choice forbids calling the structured-output tool while the \
225 run is pinned to Tool output mode; this turn cannot emit the structured \
226 result (check for a `RequestPatch` setting `tool_choice` to None or a \
227 Specific set that excludes the output tool)"
228 );
229 }
230
231 let effective_preamble: Option<String> = {
232 let base = preamble.map(str::to_owned);
233 let instruction = match &resolved_mode {
234 OutputMode::Tool if augment_output_preamble => {
235 output_tool_name.as_deref().map(|name| {
236 format!(
237 "When you have gathered enough information to answer, call the `{name}` \
238 tool exactly once with your final answer. Its arguments are the structured \
239 result and must satisfy the required schema. Do not return the final answer \
240 as plain text."
241 )
242 })
243 }
244 OutputMode::Tool => None,
245 OutputMode::Prompted => output_schema.map(|schema| {
246 let schema_json = rig_core::json_utils::to_canonical_string(schema);
247 format!(
248 "Respond with ONLY a single JSON object that conforms to this JSON Schema. \
249 Do not include any prose, explanation, or markdown code fences.\n{schema_json}"
250 )
251 }),
252 OutputMode::Native | OutputMode::Auto => None,
253 };
254 match (base, instruction) {
255 (Some(b), Some(i)) => Some(format!("{b}\n\n{i}")),
256 (Some(b), None) => Some(b),
257 (None, Some(i)) => Some(i),
258 (None, None) => None,
259 }
260 };
261
262 let messages_history: &[Message] = request_patch
264 .and_then(|o| o.history.as_deref())
265 .unwrap_or(chat_history);
266 let chat_history: Vec<Message> = if let Some(preamble) = &effective_preamble {
267 std::iter::once(Message::system(preamble.clone()))
268 .chain(messages_history.iter().cloned())
269 .collect()
270 } else {
271 messages_history.to_vec()
272 };
273
274 if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
275 tooldefs.push(ToolDefinition {
276 name: name.clone(),
277 description: output_tool_description
278 .unwrap_or(
279 "Call this tool exactly once with your final answer when you are done. \
280 Its arguments are the structured result and must satisfy the output schema.",
281 )
282 .to_string(),
283 parameters: schema.clone(),
284 });
285 }
286
287 let native_schema = match (&resolved_mode, output_schema) {
288 (OutputMode::Native, Some(schema)) => Some(
289 rig_core::schemars::Schema::try_from(schema.clone())
290 .map_err(PrepareError::InvalidOutputSchema)?,
291 ),
292 _ => None,
293 };
294
295 let mut documents = static_context.clone();
296 if let Some(patch) = request_patch {
297 documents.extend(patch.extra_context.iter().cloned());
298 }
299
300 let mut allowed_tool_names = allowed_tool_names_for_choice(
302 &executable_tool_names,
303 tool_choice,
304 output_tool_name.as_deref(),
305 pre_filter_tool_names.as_ref(),
306 )?;
307 if let Some(name) = &output_tool_name {
310 allowed_tool_names.insert(name.clone());
311 }
312
313 Ok(PreparedRequest {
314 chat_history,
315 documents,
316 tools: tooldefs,
317 temperature,
318 max_tokens,
319 additional_params,
320 tool_choice: tool_choice.cloned(),
321 output_schema: native_schema,
322 output_mode: resolved_mode,
323 executable_tool_names,
324 allowed_tool_names,
325 output_tool_name,
326 })
327}
328
329const DEFAULT_OUTPUT_TOOL_NAME: &str = "final_result";
331
332fn output_tool_callable(tool_choice: Option<&ToolChoice>, output_tool_name: &str) -> bool {
335 match tool_choice {
336 None | Some(ToolChoice::Auto | ToolChoice::Required) => true,
337 Some(ToolChoice::None) => false,
338 Some(ToolChoice::Specific { function_names }) => function_names
339 .iter()
340 .any(|name| name.as_str() == output_tool_name),
341 }
342}
343
344fn resolve_output_mode(
349 has_schema: bool,
350 has_executable_tools: bool,
351 output_tool_callable: bool,
352 provider_composes_native: bool,
353 requested: &OutputMode,
354) -> OutputMode {
355 if !has_schema {
356 return OutputMode::Native;
357 }
358 match requested {
359 OutputMode::Native => OutputMode::Native,
360 OutputMode::Prompted => OutputMode::Prompted,
361 OutputMode::Tool if output_tool_callable => OutputMode::Tool,
362 OutputMode::Tool => OutputMode::Native,
363 OutputMode::Auto
364 if has_executable_tools && output_tool_callable && !provider_composes_native =>
365 {
366 OutputMode::Tool
367 }
368 OutputMode::Auto => OutputMode::Native,
369 }
370}
371
372fn pick_output_tool_name(executable_tool_names: &BTreeSet<String>) -> String {
375 let mut name = DEFAULT_OUTPUT_TOOL_NAME.to_string();
376 let mut suffix = 1u32;
377 while executable_tool_names.contains(&name) {
378 name = format!("{DEFAULT_OUTPUT_TOOL_NAME}_{suffix}");
379 suffix += 1;
380 }
381 name
382}
383
384pub fn allowed_tool_names_for_choice(
391 executable_tool_names: &BTreeSet<String>,
392 tool_choice: Option<&ToolChoice>,
393 output_tool_name: Option<&str>,
394 pre_filter_tool_names: Option<&BTreeSet<String>>,
395) -> Result<BTreeSet<String>, PrepareError> {
396 let has_advertised_tool = !executable_tool_names.is_empty() || output_tool_name.is_some();
397 let hint = |active_tools_caused: bool| {
398 if active_tools_caused {
399 " A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
400 set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
401 } else {
402 ""
403 }
404 };
405 let advertised = || {
406 executable_tool_names
407 .iter()
408 .map(String::as_str)
409 .chain(output_tool_name)
410 .collect::<Vec<_>>()
411 };
412
413 let allowed = match tool_choice {
414 None | Some(ToolChoice::Auto) => executable_tool_names.clone(),
415 Some(ToolChoice::Required) => {
416 if !has_advertised_tool {
417 let active_tools_caused = pre_filter_tool_names.is_some_and(|pf| !pf.is_empty());
418 return Err(PrepareError::Request(format!(
419 "ToolChoice::Required forces the model to call a tool, but no tools are \
420 advertised this turn.{}",
421 hint(active_tools_caused)
422 )));
423 }
424 executable_tool_names.clone()
425 }
426 Some(ToolChoice::None) => BTreeSet::new(),
427 Some(ToolChoice::Specific { function_names }) => {
428 if function_names.is_empty() {
429 return Err(PrepareError::Request(
430 "ToolChoice::Specific requires at least one function name".to_string(),
431 ));
432 }
433
434 let requested = function_names.iter().cloned().collect::<BTreeSet<String>>();
435 let missing = function_names
436 .iter()
437 .map(String::as_str)
438 .filter(|name| {
439 !executable_tool_names.contains(*name) && Some(*name) != output_tool_name
440 })
441 .collect::<Vec<_>>();
442
443 if !missing.is_empty() {
444 let active_tools_caused = pre_filter_tool_names
446 .is_some_and(|pf| missing.iter().any(|name| pf.contains(*name)));
447 return Err(PrepareError::Request(format!(
448 "ToolChoice::Specific requested tool names not advertised this turn: \
449 {missing:?}. Advertised: {:?}.{}",
450 advertised(),
451 hint(active_tools_caused)
452 )));
453 }
454
455 requested
456 }
457 };
458
459 Ok(allowed)
460}
461
462#[cfg(test)]
463mod tests;