use std::collections::BTreeSet;
use std::sync::Arc;
use rig_core::completion::{CompletionRequest, Message, ProviderCapabilities, ToolDefinition};
use rig_core::error::ProviderError;
use rig_core::message::ToolName;
use rig_core::structured_output::{
AUGMENTATION_SEPARATOR, OUTPUT_TOOL_DESCRIPTION, output_tool_augmentation,
output_tool_callable, output_tool_name, prompted_augmentation,
};
use super::output::OutputMode;
use super::patch::{RequestPatch, overlay_params};
use super::policy::TurnPolicy;
use super::spec::RunSpec;
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct PreparedRequest {
pub request: CompletionRequest,
pub output_mode: OutputMode,
pub policy: TurnPolicy,
}
pub fn prepare_request(
spec: &RunSpec,
capabilities: &ProviderCapabilities,
prompt: impl Into<Message>,
history: &[Arc<Message>],
tools: Vec<Arc<ToolDefinition>>,
committed_output_tool: Option<&str>,
patch: Option<&RequestPatch>,
) -> Result<PreparedRequest, ProviderError> {
let output_schema = spec.output_schema.as_ref();
let preamble = patch
.and_then(|o| o.preamble.as_deref())
.or(spec.preamble.as_deref());
let temperature = patch.and_then(|o| o.temperature).or(spec.temperature);
let max_tokens = patch.and_then(|o| o.max_tokens).or(spec.max_tokens);
let tool_choice = patch
.and_then(|o| o.tool_choice.as_ref())
.or(spec.tool_choice.as_ref());
let additional_params = overlay_params(
spec.additional_params.clone(),
patch.and_then(|o| o.additional_params.clone()),
);
if !spec.provider_tools.is_empty()
&& let Some(
params @ (serde_json::Value::String(_)
| serde_json::Value::Array(_)
| serde_json::Value::Number(_)),
) = &additional_params
{
return Err(ProviderError::request(format!(
"additional_params must be a JSON object to carry provider tools, got {params}"
)));
}
let active_tools = patch.and_then(|o| o.active_tools.as_deref());
let hosted = !spec.provider_tools.is_empty()
|| additional_params
.as_ref()
.and_then(|params| params.get("tools"))
.and_then(serde_json::Value::as_array)
.is_some_and(|tools| !tools.is_empty());
let pre_filter_tool_names: Option<BTreeSet<String>> =
active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
let mut tooldefs = tools;
if let Some(allow) = active_tools {
if let Some(missing) = allow
.iter()
.find(|name| !tooldefs.iter().any(|tool| tool.name == **name))
{
return Err(ProviderError::request(format!(
"active_tools requested tool `{missing}`, which is not available this turn"
)));
}
let allowed: BTreeSet<String> = allow.iter().cloned().collect();
tooldefs.retain(|tool| allowed.contains(tool.name.as_str()));
}
let executable_tool_names: BTreeSet<String> =
tooldefs.iter().map(|tool| tool.name.to_string()).collect();
let candidate_output_tool = committed_output_tool.map_or_else(
|| {
let taken = pre_filter_tool_names
.as_ref()
.unwrap_or(&executable_tool_names);
output_tool_name(|name| taken.contains(name))
},
str::to_owned,
);
let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
OutputMode::Tool
} else {
resolve_output_mode(
output_schema.is_some(),
hosted || !executable_tool_names.is_empty(),
output_tool_callable(tool_choice, &candidate_output_tool),
capabilities.composes_native_output_with_tools,
&spec.output_mode,
)
};
let output_tool_name =
matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
if let Some(name) = &output_tool_name
&& executable_tool_names.contains(name)
{
return Err(ProviderError::request(format!(
"real tool `{name}` conflicts with the structured-output tool reserved for this \
run; rename or remove the real tool, exclude it with `active_tools`, or make it \
visible before starting a new run so Rig can reserve a different output-tool name"
)));
}
if let Some(name) = &output_tool_name
&& !output_tool_callable(tool_choice, name)
{
tracing::warn!(
"the active tool_choice forbids calling the structured-output tool while the \
run is pinned to Tool output mode; this turn cannot emit the structured \
result (check for a `RequestPatch` setting `tool_choice` to None or a \
Specific set that excludes the output tool)"
);
}
let effective_preamble: Option<String> = {
let base = preamble.map(str::to_owned);
let instruction = match &resolved_mode {
OutputMode::Tool if spec.augment_output_preamble => {
output_tool_name.as_deref().map(output_tool_augmentation)
}
OutputMode::Tool => None,
OutputMode::Prompted => output_schema.map(|schema| {
prompted_augmentation(&rig_core::json_utils::to_canonical_string(
schema.as_value(),
))
}),
OutputMode::Native | OutputMode::Auto => None,
};
match (base, instruction) {
(Some(b), Some(i)) => Some(format!("{b}{AUGMENTATION_SEPARATOR}{i}")),
(Some(b), None) => Some(b),
(None, Some(i)) => Some(i),
(None, None) => None,
}
};
let messages_history: &[Arc<Message>] =
patch.and_then(|o| o.history.as_deref()).unwrap_or(history);
let preamble = effective_preamble.map(|preamble| Arc::new(Message::system(preamble)));
let chat_history: Vec<Arc<Message>> = preamble
.into_iter()
.chain(messages_history.iter().cloned())
.collect();
if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
tooldefs.push(Arc::new(ToolDefinition {
name: ToolName::new(name.clone()).map_err(|_| {
ProviderError::request("the output tool name cannot be empty".to_string())
})?,
description: spec
.output_tool_description
.as_deref()
.unwrap_or(OUTPUT_TOOL_DESCRIPTION)
.to_string(),
parameters: schema.as_value().clone(),
annotations: Default::default(),
}));
}
let native_schema = match (&resolved_mode, output_schema) {
(OutputMode::Native, Some(schema)) => Some(schema.clone()),
_ => None,
};
let mut documents = spec.static_context.clone();
if let Some(patch) = patch {
documents.extend(patch.extra_context.iter().cloned());
}
let policy = TurnPolicy::resolve(
executable_tool_names,
tool_choice.cloned(),
output_tool_name,
pre_filter_tool_names.as_ref(),
hosted,
)?;
let mut request = CompletionRequest::new(prompt);
request.accept_unknown_finish_reasons = spec.accept_unknown_finish_reasons;
let request = request
.messages(chat_history)
.temperature(temperature)
.max_tokens(max_tokens)
.additional_params(additional_params)
.options(spec.options.clone())
.provider_options(spec.provider_options.clone())
.documents(documents)
.tools(tooldefs)
.provider_tools(spec.provider_tools.clone())
.output_schema(native_schema);
let request = match policy.tool_choice() {
Some(tool_choice) => request.tool_choice(tool_choice.clone()),
None => request,
};
Ok(PreparedRequest {
request,
output_mode: resolved_mode,
policy,
})
}
fn resolve_output_mode(
has_schema: bool,
has_tools: bool,
output_tool_callable: bool,
provider_composes_native: bool,
requested: &OutputMode,
) -> OutputMode {
if !has_schema {
return OutputMode::Native;
}
match requested {
OutputMode::Native => OutputMode::Native,
OutputMode::Prompted => OutputMode::Prompted,
OutputMode::Tool if output_tool_callable => OutputMode::Tool,
OutputMode::Tool => OutputMode::Native,
OutputMode::Auto if has_tools && output_tool_callable && !provider_composes_native => {
OutputMode::Tool
}
OutputMode::Auto => OutputMode::Native,
}
}
#[cfg(test)]
mod tests;