1use std::collections::BTreeSet;
14use std::sync::Arc;
15
16use rig_core::completion::{CompletionRequest, Message, ProviderCapabilities, ToolDefinition};
17use rig_core::error::ProviderError;
18use rig_core::message::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, overlay_params};
26use super::policy::TurnPolicy;
27use super::spec::RunSpec;
28
29#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
36pub struct PreparedRequest {
37 pub request: CompletionRequest,
48 pub output_mode: OutputMode,
50 pub policy: TurnPolicy,
53}
54
55pub fn prepare_request(
64 spec: &RunSpec,
65 capabilities: &ProviderCapabilities,
66 prompt: impl Into<Message>,
67 history: &[Arc<Message>],
68 tools: Vec<Arc<ToolDefinition>>,
69 committed_output_tool: Option<&str>,
70 patch: Option<&RequestPatch>,
71) -> Result<PreparedRequest, ProviderError> {
72 let output_schema = spec.output_schema.as_ref();
73 let preamble = patch
74 .and_then(|o| o.preamble.as_deref())
75 .or(spec.preamble.as_deref());
76 let temperature = patch.and_then(|o| o.temperature).or(spec.temperature);
77 let max_tokens = patch.and_then(|o| o.max_tokens).or(spec.max_tokens);
78 let tool_choice = patch
79 .and_then(|o| o.tool_choice.as_ref())
80 .or(spec.tool_choice.as_ref());
81 let additional_params = overlay_params(
82 spec.additional_params.clone(),
83 patch.and_then(|o| o.additional_params.clone()),
84 );
85 if !spec.provider_tools.is_empty()
89 && let Some(
90 params @ (serde_json::Value::String(_)
91 | serde_json::Value::Array(_)
92 | serde_json::Value::Number(_)),
93 ) = &additional_params
94 {
95 return Err(ProviderError::request(format!(
96 "additional_params must be a JSON object to carry provider tools, got {params}"
97 )));
98 }
99 let active_tools = patch.and_then(|o| o.active_tools.as_deref());
100 let hosted = !spec.provider_tools.is_empty()
103 || additional_params
104 .as_ref()
105 .and_then(|params| params.get("tools"))
106 .and_then(serde_json::Value::as_array)
107 .is_some_and(|tools| !tools.is_empty());
108
109 let pre_filter_tool_names: Option<BTreeSet<String>> =
112 active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
113
114 let mut tooldefs = tools;
117 if let Some(allow) = active_tools {
118 if let Some(missing) = allow
119 .iter()
120 .find(|name| !tooldefs.iter().any(|tool| tool.name == **name))
121 {
122 return Err(ProviderError::request(format!(
123 "active_tools requested tool `{missing}`, which is not available this turn"
124 )));
125 }
126 let allowed: BTreeSet<String> = allow.iter().cloned().collect();
127 tooldefs.retain(|tool| allowed.contains(tool.name.as_str()));
128 }
129
130 let executable_tool_names: BTreeSet<String> =
132 tooldefs.iter().map(|tool| tool.name.to_string()).collect();
133
134 let candidate_output_tool = committed_output_tool.map_or_else(
137 || {
138 let taken = pre_filter_tool_names
139 .as_ref()
140 .unwrap_or(&executable_tool_names);
141 output_tool_name(|name| taken.contains(name))
142 },
143 str::to_owned,
144 );
145 let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
146 OutputMode::Tool
147 } else {
148 resolve_output_mode(
149 output_schema.is_some(),
150 hosted || !executable_tool_names.is_empty(),
151 output_tool_callable(tool_choice, &candidate_output_tool),
152 capabilities.composes_native_output_with_tools,
153 &spec.output_mode,
154 )
155 };
156
157 let output_tool_name =
158 matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
159
160 if let Some(name) = &output_tool_name
163 && executable_tool_names.contains(name)
164 {
165 return Err(ProviderError::request(format!(
166 "real tool `{name}` conflicts with the structured-output tool reserved for this \
167 run; rename or remove the real tool, exclude it with `active_tools`, or make it \
168 visible before starting a new run so Rig can reserve a different output-tool name"
169 )));
170 }
171
172 if let Some(name) = &output_tool_name
175 && !output_tool_callable(tool_choice, name)
176 {
177 tracing::warn!(
178 "the active tool_choice forbids calling the structured-output tool while the \
179 run is pinned to Tool output mode; this turn cannot emit the structured \
180 result (check for a `RequestPatch` setting `tool_choice` to None or a \
181 Specific set that excludes the output tool)"
182 );
183 }
184
185 let effective_preamble: Option<String> = {
186 let base = preamble.map(str::to_owned);
187 let instruction = match &resolved_mode {
188 OutputMode::Tool if spec.augment_output_preamble => {
189 output_tool_name.as_deref().map(output_tool_augmentation)
190 }
191 OutputMode::Tool => None,
192 OutputMode::Prompted => output_schema.map(|schema| {
193 prompted_augmentation(&rig_core::json_utils::to_canonical_string(
194 schema.as_value(),
195 ))
196 }),
197 OutputMode::Native | OutputMode::Auto => None,
198 };
199 match (base, instruction) {
200 (Some(b), Some(i)) => Some(format!("{b}{AUGMENTATION_SEPARATOR}{i}")),
201 (Some(b), None) => Some(b),
202 (None, Some(i)) => Some(i),
203 (None, None) => None,
204 }
205 };
206
207 let messages_history: &[Arc<Message>] =
209 patch.and_then(|o| o.history.as_deref()).unwrap_or(history);
210 let preamble = effective_preamble.map(|preamble| Arc::new(Message::system(preamble)));
211 let chat_history: Vec<Arc<Message>> = preamble
212 .into_iter()
213 .chain(messages_history.iter().cloned())
214 .collect();
215
216 if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
217 tooldefs.push(Arc::new(ToolDefinition {
218 name: ToolName::new(name.clone()).map_err(|_| {
219 ProviderError::request("the output tool name cannot be empty".to_string())
220 })?,
221 description: spec
222 .output_tool_description
223 .as_deref()
224 .unwrap_or(OUTPUT_TOOL_DESCRIPTION)
225 .to_string(),
226 parameters: schema.as_value().clone(),
227 annotations: Default::default(),
228 }));
229 }
230
231 let native_schema = match (&resolved_mode, output_schema) {
232 (OutputMode::Native, Some(schema)) => Some(schema.clone()),
233 _ => None,
234 };
235
236 let mut documents = spec.static_context.clone();
237 if let Some(patch) = patch {
238 documents.extend(patch.extra_context.iter().cloned());
239 }
240
241 let policy = TurnPolicy::resolve(
243 executable_tool_names,
244 tool_choice.cloned(),
245 output_tool_name,
246 pre_filter_tool_names.as_ref(),
247 hosted,
248 )?;
249
250 let mut request = CompletionRequest::new(prompt);
251 request.accept_unknown_finish_reasons = spec.accept_unknown_finish_reasons;
252 let request = request
253 .messages(chat_history)
254 .temperature(temperature)
255 .max_tokens(max_tokens)
256 .additional_params(additional_params)
257 .options(spec.options.clone())
258 .provider_options(spec.provider_options.clone())
259 .documents(documents)
260 .tools(tooldefs)
261 .provider_tools(spec.provider_tools.clone())
262 .output_schema(native_schema);
263 let request = match policy.tool_choice() {
264 Some(tool_choice) => request.tool_choice(tool_choice.clone()),
265 None => request,
266 };
267
268 Ok(PreparedRequest {
269 request,
270 output_mode: resolved_mode,
271 policy,
272 })
273}
274
275fn resolve_output_mode(
281 has_schema: bool,
282 has_tools: bool,
283 output_tool_callable: bool,
284 provider_composes_native: bool,
285 requested: &OutputMode,
286) -> OutputMode {
287 if !has_schema {
288 return OutputMode::Native;
289 }
290 match requested {
291 OutputMode::Native => OutputMode::Native,
292 OutputMode::Prompted => OutputMode::Prompted,
293 OutputMode::Tool if output_tool_callable => OutputMode::Tool,
294 OutputMode::Tool => OutputMode::Native,
295 OutputMode::Auto if has_tools && output_tool_callable && !provider_composes_native => {
296 OutputMode::Tool
297 }
298 OutputMode::Auto => OutputMode::Native,
299 }
300}
301
302#[cfg(test)]
303mod tests;