1use std::collections::BTreeSet;
12use std::sync::Arc;
13
14use rig_core::completion::{
15 CompletionRequest, Document, GenerationOptions, Message, ProviderCapabilities, ProviderOptions,
16 ProviderToolDefinition, ToolDefinition,
17};
18use rig_core::error::ProviderError;
19use rig_core::message::ToolName;
20use rig_core::structured_output::{
21 AUGMENTATION_SEPARATOR, OUTPUT_TOOL_DESCRIPTION, output_tool_augmentation,
22 output_tool_callable, output_tool_name, prompted_augmentation,
23};
24
25use super::output::OutputMode;
26use super::patch::RequestPatch;
27use super::policy::TurnPolicy;
28use super::spec::RunSpec;
29
30#[derive(Debug, thiserror::Error)]
34pub enum PrepareError {
35 #[error("{0}")]
37 Request(String),
38}
39
40impl From<PrepareError> for ProviderError {
41 fn from(error: PrepareError) -> Self {
42 ProviderError::request(error.to_string())
43 }
44}
45
46#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
53pub struct PreparedRequest {
54 pub chat_history: Vec<Arc<Message>>,
58 pub documents: Vec<Document>,
60 pub tools: Vec<Arc<ToolDefinition>>,
64 pub temperature: Option<f64>,
66 pub max_tokens: Option<u64>,
68 pub additional_params: Option<serde_json::Value>,
71 #[serde(default, skip_serializing_if = "Vec::is_empty")]
74 pub provider_tools: Vec<ProviderToolDefinition>,
75 #[serde(default, skip_serializing_if = "GenerationOptions::is_default")]
77 pub options: GenerationOptions,
78 #[serde(default, skip_serializing_if = "ProviderOptions::is_empty")]
80 pub provider_options: ProviderOptions,
81 pub output_schema: Option<rig_core::schemars::Schema>,
84 pub output_mode: OutputMode,
86 pub policy: TurnPolicy,
89 #[serde(default)]
91 pub accept_unknown_finish_reasons: bool,
92}
93
94impl PreparedRequest {
95 pub fn apply(self, mut request: CompletionRequest) -> CompletionRequest {
102 request.accept_unknown_finish_reasons = self.accept_unknown_finish_reasons;
103 let request = request
104 .messages(self.chat_history)
105 .temperature(self.temperature)
106 .max_tokens(self.max_tokens)
107 .additional_params(self.additional_params)
108 .options(self.options)
109 .provider_options(self.provider_options)
110 .documents(self.documents)
111 .tools(self.tools)
112 .provider_tools(self.provider_tools)
113 .output_schema(self.output_schema);
114 match self.policy.tool_choice() {
115 Some(tool_choice) => request.tool_choice(tool_choice.clone()),
116 None => request,
117 }
118 }
119}
120
121pub fn prepare_request(
127 spec: &RunSpec,
128 capabilities: &ProviderCapabilities,
129 history: &[Arc<Message>],
130 tools: Vec<Arc<ToolDefinition>>,
131 committed_output_tool: Option<&str>,
132 patch: Option<&RequestPatch>,
133) -> Result<PreparedRequest, PrepareError> {
134 let request_patch = patch;
135 let chat_history = history;
136 let preamble = spec.preamble.as_deref();
137 let static_context = &spec.static_context;
138 let temperature = spec.temperature;
139 let max_tokens = spec.max_tokens;
140 let additional_params = spec.additional_params.as_ref();
141 let tool_choice = spec.tool_choice.as_ref();
142 let output_schema = spec.output_schema.as_ref();
143 let output_mode = &spec.output_mode;
144 let output_tool_description = spec.output_tool_description.as_deref();
145 let augment_output_preamble = spec.augment_output_preamble;
146 let preamble = request_patch
147 .and_then(|o| o.preamble.as_deref())
148 .or(preamble);
149 let temperature = request_patch.and_then(|o| o.temperature).or(temperature);
150 let max_tokens = request_patch.and_then(|o| o.max_tokens).or(max_tokens);
151 let tool_choice = request_patch
152 .and_then(|o| o.tool_choice.as_ref())
153 .or(tool_choice);
154 let additional_params: Option<serde_json::Value> = match (
157 additional_params,
158 request_patch.and_then(|o| o.additional_params.as_ref()),
159 ) {
160 (Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
161 Some(rig_core::json_utils::merge(base.clone(), patch.clone()))
162 }
163 (base, patch) => patch.or(base).cloned(),
164 };
165 let active_tools = request_patch.and_then(|o| o.active_tools.as_deref());
166 let hosted = !spec.provider_tools.is_empty()
169 || additional_params
170 .as_ref()
171 .and_then(|params| params.get("tools"))
172 .and_then(serde_json::Value::as_array)
173 .is_some_and(|tools| !tools.is_empty());
174
175 let pre_filter_tool_names: Option<BTreeSet<String>> =
178 active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
179
180 let mut tooldefs = tools;
183 if let Some(allow) = active_tools {
184 if let Some(missing) = allow
185 .iter()
186 .find(|name| !tooldefs.iter().any(|tool| tool.name == **name))
187 {
188 return Err(PrepareError::Request(format!(
189 "active_tools requested tool `{missing}`, which is not available this turn"
190 )));
191 }
192 let allowed: BTreeSet<String> = allow.iter().cloned().collect();
193 tooldefs.retain(|tool| allowed.contains(tool.name.as_str()));
194 }
195
196 let executable_tool_names: BTreeSet<String> =
198 tooldefs.iter().map(|tool| tool.name.to_string()).collect();
199
200 let candidate_output_tool = committed_output_tool.map_or_else(
203 || {
204 let taken = pre_filter_tool_names
205 .as_ref()
206 .unwrap_or(&executable_tool_names);
207 output_tool_name(|name| taken.contains(name))
208 },
209 str::to_owned,
210 );
211 let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
212 OutputMode::Tool
213 } else {
214 resolve_output_mode(
215 output_schema.is_some(),
216 hosted || !executable_tool_names.is_empty(),
217 output_tool_callable(tool_choice, &candidate_output_tool),
218 capabilities.composes_native_output_with_tools,
219 output_mode,
220 )
221 };
222
223 let output_tool_name =
224 matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
225
226 if let Some(name) = &output_tool_name
229 && executable_tool_names.contains(name)
230 {
231 return Err(PrepareError::Request(format!(
232 "real tool `{name}` conflicts with the structured-output tool reserved for this \
233 run; rename or remove the real tool, exclude it with `active_tools`, or make it \
234 visible before starting a new run so Rig can reserve a different output-tool name"
235 )));
236 }
237
238 if let Some(name) = &output_tool_name
241 && !output_tool_callable(tool_choice, name)
242 {
243 tracing::warn!(
244 "the active tool_choice forbids calling the structured-output tool while the \
245 run is pinned to Tool output mode; this turn cannot emit the structured \
246 result (check for a `RequestPatch` setting `tool_choice` to None or a \
247 Specific set that excludes the output tool)"
248 );
249 }
250
251 let effective_preamble: Option<String> = {
252 let base = preamble.map(str::to_owned);
253 let instruction = match &resolved_mode {
254 OutputMode::Tool if augment_output_preamble => {
255 output_tool_name.as_deref().map(output_tool_augmentation)
256 }
257 OutputMode::Tool => None,
258 OutputMode::Prompted => output_schema.map(|schema| {
259 prompted_augmentation(&rig_core::json_utils::to_canonical_string(
260 schema.as_value(),
261 ))
262 }),
263 OutputMode::Native | OutputMode::Auto => None,
264 };
265 match (base, instruction) {
266 (Some(b), Some(i)) => Some(format!("{b}{AUGMENTATION_SEPARATOR}{i}")),
267 (Some(b), None) => Some(b),
268 (None, Some(i)) => Some(i),
269 (None, None) => None,
270 }
271 };
272
273 let messages_history: &[Arc<Message>] = request_patch
275 .and_then(|o| o.history.as_deref())
276 .unwrap_or(chat_history);
277 let preamble = effective_preamble.map(|preamble| Arc::new(Message::system(preamble)));
278 let chat_history: Vec<Arc<Message>> = preamble
279 .into_iter()
280 .chain(messages_history.iter().cloned())
281 .collect();
282
283 if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
284 tooldefs.push(Arc::new(ToolDefinition {
285 name: ToolName::new(name.clone()).map_err(|_| {
286 PrepareError::Request("the output tool name cannot be empty".to_string())
287 })?,
288 description: output_tool_description
289 .unwrap_or(OUTPUT_TOOL_DESCRIPTION)
290 .to_string(),
291 parameters: schema.as_value().clone(),
292 annotations: Default::default(),
293 }));
294 }
295
296 let native_schema = match (&resolved_mode, output_schema) {
297 (OutputMode::Native, Some(schema)) => Some(schema.clone()),
298 _ => None,
299 };
300
301 let mut documents = static_context.clone();
302 if let Some(patch) = request_patch {
303 documents.extend(patch.extra_context.iter().cloned());
304 }
305
306 let policy = TurnPolicy::resolve(
308 executable_tool_names,
309 tool_choice.cloned(),
310 output_tool_name,
311 pre_filter_tool_names.as_ref(),
312 hosted,
313 )?;
314
315 Ok(PreparedRequest {
316 chat_history,
317 documents,
318 tools: tooldefs,
319 temperature,
320 max_tokens,
321 additional_params,
322 provider_tools: spec.provider_tools.clone(),
323 options: spec.options.clone(),
324 provider_options: spec.provider_options.clone(),
325 output_schema: native_schema,
326 output_mode: resolved_mode,
327 policy,
328 accept_unknown_finish_reasons: spec.accept_unknown_finish_reasons,
329 })
330}
331
332fn resolve_output_mode(
338 has_schema: bool,
339 has_tools: bool,
340 output_tool_callable: bool,
341 provider_composes_native: bool,
342 requested: &OutputMode,
343) -> OutputMode {
344 if !has_schema {
345 return OutputMode::Native;
346 }
347 match requested {
348 OutputMode::Native => OutputMode::Native,
349 OutputMode::Prompted => OutputMode::Prompted,
350 OutputMode::Tool if output_tool_callable => OutputMode::Tool,
351 OutputMode::Tool => OutputMode::Native,
352 OutputMode::Auto if has_tools && output_tool_callable && !provider_composes_native => {
353 OutputMode::Tool
354 }
355 OutputMode::Auto => OutputMode::Native,
356 }
357}
358
359#[cfg(test)]
360mod tests;