1use std::collections::BTreeSet;
12
13use rig_core::completion::{
14 CompletionRequest, Document, GenerationOptions, Message, ProviderCapabilities, ProviderOptions,
15 ToolDefinition,
16};
17use rig_core::error::ProviderError;
18use rig_core::message::{ToolChoice, ToolName};
19use rig_core::structured_output::{
20 AUGMENTATION_SEPARATOR, OUTPUT_TOOL_DESCRIPTION, output_tool_augmentation,
21 output_tool_callable, output_tool_name, prompted_augmentation,
22};
23
24use super::output::OutputMode;
25use super::patch::RequestPatch;
26use super::spec::RunSpec;
27
28#[derive(Debug, thiserror::Error)]
32pub enum PrepareError {
33 #[error("{0}")]
36 Request(String),
37 #[error("invalid output schema: {0}")]
39 InvalidOutputSchema(#[source] serde_json::Error),
40}
41
42impl From<PrepareError> for ProviderError {
43 fn from(error: PrepareError) -> Self {
44 ProviderError::request(error.to_string())
45 }
46}
47
48#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
56pub struct PreparedRequest {
57 pub chat_history: Vec<Message>,
61 pub documents: Vec<Document>,
63 pub tools: Vec<ToolDefinition>,
67 pub temperature: Option<f64>,
69 pub max_tokens: Option<u64>,
71 pub additional_params: Option<serde_json::Value>,
74 pub tool_choice: Option<ToolChoice>,
76 #[serde(default, skip_serializing_if = "GenerationOptions::is_default")]
78 pub options: GenerationOptions,
79 #[serde(default, skip_serializing_if = "ProviderOptions::is_empty")]
81 pub provider_options: ProviderOptions,
82 pub output_schema: Option<rig_core::schemars::Schema>,
85 pub output_mode: OutputMode,
87 pub executable_tool_names: BTreeSet<String>,
89 pub allowed_tool_names: BTreeSet<String>,
92 pub output_tool_name: Option<String>,
95 #[serde(default)]
97 pub accept_unknown_finish_reasons: bool,
98}
99
100impl PreparedRequest {
101 pub fn apply(self, mut request: CompletionRequest) -> CompletionRequest {
108 request.accept_unknown_finish_reasons = self.accept_unknown_finish_reasons;
109 let request = request
110 .messages(self.chat_history)
111 .temperature(self.temperature)
112 .max_tokens(self.max_tokens)
113 .additional_params(self.additional_params)
114 .options(self.options)
115 .provider_options(self.provider_options)
116 .documents(self.documents)
117 .tools(self.tools)
118 .output_schema(self.output_schema);
119 match self.tool_choice {
120 Some(tool_choice) => request.tool_choice(tool_choice),
121 None => request,
122 }
123 }
124}
125
126pub fn prepare_request(
132 spec: &RunSpec,
133 capabilities: &ProviderCapabilities,
134 history: &[Message],
135 tools: Vec<ToolDefinition>,
136 committed_output_tool: Option<&str>,
137 patch: Option<&RequestPatch>,
138) -> Result<PreparedRequest, PrepareError> {
139 let request_patch = patch;
140 let chat_history = history;
141 let preamble = spec.preamble.as_deref();
142 let static_context = &spec.static_context;
143 let temperature = spec.temperature;
144 let max_tokens = spec.max_tokens;
145 let additional_params = spec.additional_params.as_ref();
146 let tool_choice = spec.tool_choice.as_ref();
147 let output_schema = spec.output_schema.as_ref();
148 let output_mode = &spec.output_mode;
149 let output_tool_description = spec.output_tool_description.as_deref();
150 let augment_output_preamble = spec.augment_output_preamble;
151 let preamble = request_patch
152 .and_then(|o| o.preamble.as_deref())
153 .or(preamble);
154 let temperature = request_patch.and_then(|o| o.temperature).or(temperature);
155 let max_tokens = request_patch.and_then(|o| o.max_tokens).or(max_tokens);
156 let tool_choice = request_patch
157 .and_then(|o| o.tool_choice.as_ref())
158 .or(tool_choice);
159 let additional_params: Option<serde_json::Value> = match (
162 additional_params,
163 request_patch.and_then(|o| o.additional_params.as_ref()),
164 ) {
165 (Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
166 Some(rig_core::json_utils::merge(base.clone(), patch.clone()))
167 }
168 (base, patch) => patch.or(base).cloned(),
169 };
170 let active_tools = request_patch.and_then(|o| o.active_tools.as_deref());
171
172 let pre_filter_tool_names: Option<BTreeSet<String>> =
175 active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
176
177 let mut tooldefs = tools;
180 if let Some(allow) = active_tools {
181 if let Some(missing) = allow
182 .iter()
183 .find(|name| !tooldefs.iter().any(|tool| tool.name == **name))
184 {
185 return Err(PrepareError::Request(format!(
186 "active_tools requested tool `{missing}`, which is not available this turn"
187 )));
188 }
189 let allowed: BTreeSet<String> = allow.iter().cloned().collect();
190 tooldefs.retain(|tool| allowed.contains(tool.name.as_str()));
191 }
192
193 let executable_tool_names: BTreeSet<String> =
195 tooldefs.iter().map(|tool| tool.name.to_string()).collect();
196
197 let candidate_output_tool = committed_output_tool.map_or_else(
200 || {
201 let taken = pre_filter_tool_names
202 .as_ref()
203 .unwrap_or(&executable_tool_names);
204 output_tool_name(|name| taken.contains(name))
205 },
206 str::to_owned,
207 );
208 let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
209 OutputMode::Tool
210 } else {
211 resolve_output_mode(
212 output_schema.is_some(),
213 !executable_tool_names.is_empty(),
214 output_tool_callable(tool_choice, &candidate_output_tool),
215 capabilities.composes_native_output_with_tools,
216 output_mode,
217 )
218 };
219
220 let output_tool_name =
221 matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
222
223 if let Some(name) = &output_tool_name
226 && executable_tool_names.contains(name)
227 {
228 return Err(PrepareError::Request(format!(
229 "real tool `{name}` conflicts with the structured-output tool reserved for this \
230 run; rename or remove the real tool, exclude it with `active_tools`, or make it \
231 visible before starting a new run so Rig can reserve a different output-tool name"
232 )));
233 }
234
235 if let Some(name) = &output_tool_name
238 && !output_tool_callable(tool_choice, name)
239 {
240 tracing::warn!(
241 "the active tool_choice forbids calling the structured-output tool while the \
242 run is pinned to Tool output mode; this turn cannot emit the structured \
243 result (check for a `RequestPatch` setting `tool_choice` to None or a \
244 Specific set that excludes the output tool)"
245 );
246 }
247
248 let effective_preamble: Option<String> = {
249 let base = preamble.map(str::to_owned);
250 let instruction = match &resolved_mode {
251 OutputMode::Tool if augment_output_preamble => {
252 output_tool_name.as_deref().map(output_tool_augmentation)
253 }
254 OutputMode::Tool => None,
255 OutputMode::Prompted => output_schema.map(|schema| {
256 prompted_augmentation(&rig_core::json_utils::to_canonical_string(schema))
257 }),
258 OutputMode::Native | OutputMode::Auto => None,
259 };
260 match (base, instruction) {
261 (Some(b), Some(i)) => Some(format!("{b}{AUGMENTATION_SEPARATOR}{i}")),
262 (Some(b), None) => Some(b),
263 (None, Some(i)) => Some(i),
264 (None, None) => None,
265 }
266 };
267
268 let messages_history: &[Message] = request_patch
270 .and_then(|o| o.history.as_deref())
271 .unwrap_or(chat_history);
272 let chat_history: Vec<Message> = if let Some(preamble) = &effective_preamble {
273 std::iter::once(Message::system(preamble.clone()))
274 .chain(messages_history.iter().cloned())
275 .collect()
276 } else {
277 messages_history.to_vec()
278 };
279
280 if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
281 tooldefs.push(ToolDefinition {
282 name: ToolName::new(name.clone()).map_err(|_| {
283 PrepareError::Request("the output tool name cannot be empty".to_string())
284 })?,
285 description: output_tool_description
286 .unwrap_or(OUTPUT_TOOL_DESCRIPTION)
287 .to_string(),
288 parameters: schema.clone(),
289 });
290 }
291
292 let native_schema = match (&resolved_mode, output_schema) {
293 (OutputMode::Native, Some(schema)) => Some(
294 rig_core::schemars::Schema::try_from(schema.clone())
295 .map_err(PrepareError::InvalidOutputSchema)?,
296 ),
297 _ => None,
298 };
299
300 let mut documents = static_context.clone();
301 if let Some(patch) = request_patch {
302 documents.extend(patch.extra_context.iter().cloned());
303 }
304
305 let mut allowed_tool_names = allowed_tool_names_for_choice(
307 &executable_tool_names,
308 tool_choice,
309 output_tool_name.as_deref(),
310 pre_filter_tool_names.as_ref(),
311 )?;
312 if let Some(name) = &output_tool_name {
315 allowed_tool_names.insert(name.clone());
316 }
317
318 Ok(PreparedRequest {
319 chat_history,
320 documents,
321 tools: tooldefs,
322 temperature,
323 max_tokens,
324 additional_params,
325 tool_choice: tool_choice.cloned(),
326 options: spec.options.clone(),
327 provider_options: spec.provider_options.clone(),
328 output_schema: native_schema,
329 output_mode: resolved_mode,
330 executable_tool_names,
331 allowed_tool_names,
332 output_tool_name,
333 accept_unknown_finish_reasons: spec.accept_unknown_finish_reasons,
334 })
335}
336
337fn resolve_output_mode(
342 has_schema: bool,
343 has_executable_tools: bool,
344 output_tool_callable: bool,
345 provider_composes_native: bool,
346 requested: &OutputMode,
347) -> OutputMode {
348 if !has_schema {
349 return OutputMode::Native;
350 }
351 match requested {
352 OutputMode::Native => OutputMode::Native,
353 OutputMode::Prompted => OutputMode::Prompted,
354 OutputMode::Tool if output_tool_callable => OutputMode::Tool,
355 OutputMode::Tool => OutputMode::Native,
356 OutputMode::Auto
357 if has_executable_tools && output_tool_callable && !provider_composes_native =>
358 {
359 OutputMode::Tool
360 }
361 OutputMode::Auto => OutputMode::Native,
362 }
363}
364
365pub fn allowed_tool_names_for_choice(
372 executable_tool_names: &BTreeSet<String>,
373 tool_choice: Option<&ToolChoice>,
374 output_tool_name: Option<&str>,
375 pre_filter_tool_names: Option<&BTreeSet<String>>,
376) -> Result<BTreeSet<String>, PrepareError> {
377 let has_advertised_tool = !executable_tool_names.is_empty() || output_tool_name.is_some();
378 let hint = |active_tools_caused: bool| {
379 if active_tools_caused {
380 " A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
381 set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
382 } else {
383 ""
384 }
385 };
386 let advertised = || {
387 executable_tool_names
388 .iter()
389 .map(String::as_str)
390 .chain(output_tool_name)
391 .collect::<Vec<_>>()
392 };
393
394 let allowed = match tool_choice {
395 None | Some(ToolChoice::Auto) => executable_tool_names.clone(),
396 Some(ToolChoice::Required) => {
397 if !has_advertised_tool {
398 let active_tools_caused = pre_filter_tool_names.is_some_and(|pf| !pf.is_empty());
399 return Err(PrepareError::Request(format!(
400 "ToolChoice::Required forces the model to call a tool, but no tools are \
401 advertised this turn.{}",
402 hint(active_tools_caused)
403 )));
404 }
405 executable_tool_names.clone()
406 }
407 Some(ToolChoice::None) => BTreeSet::new(),
408 Some(ToolChoice::Specific { function_names }) => {
409 if function_names.is_empty() {
410 return Err(PrepareError::Request(
411 "ToolChoice::Specific requires at least one function name".to_string(),
412 ));
413 }
414
415 let requested = function_names
416 .iter()
417 .map(ToString::to_string)
418 .collect::<BTreeSet<String>>();
419 let missing = function_names
420 .iter()
421 .map(ToolName::as_str)
422 .filter(|name| {
423 !executable_tool_names.contains(*name) && Some(*name) != output_tool_name
424 })
425 .collect::<Vec<_>>();
426
427 if !missing.is_empty() {
428 let active_tools_caused = pre_filter_tool_names
430 .is_some_and(|pf| missing.iter().any(|name| pf.contains(*name)));
431 return Err(PrepareError::Request(format!(
432 "ToolChoice::Specific requested tool names not advertised this turn: \
433 {missing:?}. Advertised: {:?}.{}",
434 advertised(),
435 hint(active_tools_caused)
436 )));
437 }
438
439 requested
440 }
441 };
442
443 Ok(allowed)
444}
445
446#[cfg(test)]
447mod tests;