use std::collections::BTreeSet;
use rig_core::completion::{
CompletionRequest, Document, Message, ProviderCapabilities, ToolDefinition,
};
use rig_core::error::ProviderError;
use rig_core::message::ToolChoice;
use super::output::OutputMode;
use super::patch::RequestPatch;
use super::spec::RunSpec;
#[derive(Debug, thiserror::Error)]
pub enum PrepareError {
#[error("{0}")]
Request(String),
#[error("invalid output schema: {0}")]
InvalidOutputSchema(#[source] serde_json::Error),
}
impl From<PrepareError> for ProviderError {
fn from(error: PrepareError) -> Self {
ProviderError::request(error.to_string())
}
}
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct PreparedRequest {
pub chat_history: Vec<Message>,
pub documents: Vec<Document>,
pub tools: Vec<ToolDefinition>,
pub temperature: Option<f64>,
pub max_tokens: Option<u64>,
pub additional_params: Option<serde_json::Value>,
pub tool_choice: Option<ToolChoice>,
pub output_schema: Option<rig_core::schemars::Schema>,
pub output_mode: OutputMode,
pub executable_tool_names: BTreeSet<String>,
pub allowed_tool_names: BTreeSet<String>,
pub output_tool_name: Option<String>,
}
impl PreparedRequest {
pub fn apply(self, request: CompletionRequest) -> CompletionRequest {
let request = request
.messages(self.chat_history)
.temperature(self.temperature)
.max_tokens(self.max_tokens)
.additional_params(self.additional_params)
.documents(self.documents)
.tools(self.tools)
.output_schema(self.output_schema);
match self.tool_choice {
Some(tool_choice) => request.tool_choice(tool_choice),
None => request,
}
}
}
pub fn prepare_request(
spec: &RunSpec,
capabilities: &ProviderCapabilities,
history: &[Message],
tools: Vec<ToolDefinition>,
committed_output_tool: Option<&str>,
patch: Option<&RequestPatch>,
) -> Result<PreparedRequest, PrepareError> {
let request_patch = patch;
let chat_history = history;
let preamble = spec.preamble.as_deref();
let static_context = &spec.static_context;
let temperature = spec.temperature;
let max_tokens = spec.max_tokens;
let additional_params = spec.additional_params.as_ref();
let tool_choice = spec.tool_choice.as_ref();
let output_schema = spec.output_schema.as_ref();
let output_mode = &spec.output_mode;
let output_tool_description = spec.output_tool_description.as_deref();
let augment_output_preamble = spec.augment_output_preamble;
let preamble = request_patch
.and_then(|o| o.preamble.as_deref())
.or(preamble);
let temperature = request_patch.and_then(|o| o.temperature).or(temperature);
let max_tokens = request_patch.and_then(|o| o.max_tokens).or(max_tokens);
let tool_choice = request_patch
.and_then(|o| o.tool_choice.as_ref())
.or(tool_choice);
let additional_params: Option<serde_json::Value> = match (
additional_params,
request_patch.and_then(|o| o.additional_params.as_ref()),
) {
(Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
Some(rig_core::json_utils::merge(base.clone(), patch.clone()))
}
(base, patch) => patch.or(base).cloned(),
};
let active_tools = request_patch.and_then(|o| o.active_tools.as_deref());
let pre_filter_tool_names: Option<BTreeSet<String>> =
active_tools.map(|_| tools.iter().map(|tool| tool.name.clone()).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(PrepareError::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));
}
let executable_tool_names: BTreeSet<String> =
tooldefs.iter().map(|tool| tool.name.clone()).collect();
let candidate_output_tool = committed_output_tool.map_or_else(
|| {
pick_output_tool_name(
pre_filter_tool_names
.as_ref()
.unwrap_or(&executable_tool_names),
)
},
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(),
!executable_tool_names.is_empty(),
output_tool_callable(tool_choice, &candidate_output_tool),
capabilities.composes_native_output_with_tools,
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(PrepareError::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 augment_output_preamble => {
output_tool_name.as_deref().map(|name| {
format!(
"When you have gathered enough information to answer, call the `{name}` \
tool exactly once with your final answer. Its arguments are the structured \
result and must satisfy the required schema. Do not return the final answer \
as plain text."
)
})
}
OutputMode::Tool => None,
OutputMode::Prompted => output_schema.map(|schema| {
let schema_json = rig_core::json_utils::to_canonical_string(schema);
format!(
"Respond with ONLY a single JSON object that conforms to this JSON Schema. \
Do not include any prose, explanation, or markdown code fences.\n{schema_json}"
)
}),
OutputMode::Native | OutputMode::Auto => None,
};
match (base, instruction) {
(Some(b), Some(i)) => Some(format!("{b}\n\n{i}")),
(Some(b), None) => Some(b),
(None, Some(i)) => Some(i),
(None, None) => None,
}
};
let messages_history: &[Message] = request_patch
.and_then(|o| o.history.as_deref())
.unwrap_or(chat_history);
let chat_history: Vec<Message> = if let Some(preamble) = &effective_preamble {
std::iter::once(Message::system(preamble.clone()))
.chain(messages_history.iter().cloned())
.collect()
} else {
messages_history.to_vec()
};
if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
tooldefs.push(ToolDefinition {
name: name.clone(),
description: output_tool_description
.unwrap_or(
"Call this tool exactly once with your final answer when you are done. \
Its arguments are the structured result and must satisfy the output schema.",
)
.to_string(),
parameters: schema.clone(),
});
}
let native_schema = match (&resolved_mode, output_schema) {
(OutputMode::Native, Some(schema)) => Some(
rig_core::schemars::Schema::try_from(schema.clone())
.map_err(PrepareError::InvalidOutputSchema)?,
),
_ => None,
};
let mut documents = static_context.clone();
if let Some(patch) = request_patch {
documents.extend(patch.extra_context.iter().cloned());
}
let mut allowed_tool_names = allowed_tool_names_for_choice(
&executable_tool_names,
tool_choice,
output_tool_name.as_deref(),
pre_filter_tool_names.as_ref(),
)?;
if let Some(name) = &output_tool_name {
allowed_tool_names.insert(name.clone());
}
Ok(PreparedRequest {
chat_history,
documents,
tools: tooldefs,
temperature,
max_tokens,
additional_params,
tool_choice: tool_choice.cloned(),
output_schema: native_schema,
output_mode: resolved_mode,
executable_tool_names,
allowed_tool_names,
output_tool_name,
})
}
const DEFAULT_OUTPUT_TOOL_NAME: &str = "final_result";
fn output_tool_callable(tool_choice: Option<&ToolChoice>, output_tool_name: &str) -> bool {
match tool_choice {
None | Some(ToolChoice::Auto | ToolChoice::Required) => true,
Some(ToolChoice::None) => false,
Some(ToolChoice::Specific { function_names }) => function_names
.iter()
.any(|name| name.as_str() == output_tool_name),
}
}
fn resolve_output_mode(
has_schema: bool,
has_executable_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_executable_tools && output_tool_callable && !provider_composes_native =>
{
OutputMode::Tool
}
OutputMode::Auto => OutputMode::Native,
}
}
fn pick_output_tool_name(executable_tool_names: &BTreeSet<String>) -> String {
let mut name = DEFAULT_OUTPUT_TOOL_NAME.to_string();
let mut suffix = 1u32;
while executable_tool_names.contains(&name) {
name = format!("{DEFAULT_OUTPUT_TOOL_NAME}_{suffix}");
suffix += 1;
}
name
}
pub fn allowed_tool_names_for_choice(
executable_tool_names: &BTreeSet<String>,
tool_choice: Option<&ToolChoice>,
output_tool_name: Option<&str>,
pre_filter_tool_names: Option<&BTreeSet<String>>,
) -> Result<BTreeSet<String>, PrepareError> {
let has_advertised_tool = !executable_tool_names.is_empty() || output_tool_name.is_some();
let hint = |active_tools_caused: bool| {
if active_tools_caused {
" A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
} else {
""
}
};
let advertised = || {
executable_tool_names
.iter()
.map(String::as_str)
.chain(output_tool_name)
.collect::<Vec<_>>()
};
let allowed = match tool_choice {
None | Some(ToolChoice::Auto) => executable_tool_names.clone(),
Some(ToolChoice::Required) => {
if !has_advertised_tool {
let active_tools_caused = pre_filter_tool_names.is_some_and(|pf| !pf.is_empty());
return Err(PrepareError::Request(format!(
"ToolChoice::Required forces the model to call a tool, but no tools are \
advertised this turn.{}",
hint(active_tools_caused)
)));
}
executable_tool_names.clone()
}
Some(ToolChoice::None) => BTreeSet::new(),
Some(ToolChoice::Specific { function_names }) => {
if function_names.is_empty() {
return Err(PrepareError::Request(
"ToolChoice::Specific requires at least one function name".to_string(),
));
}
let requested = function_names.iter().cloned().collect::<BTreeSet<String>>();
let missing = function_names
.iter()
.map(String::as_str)
.filter(|name| {
!executable_tool_names.contains(*name) && Some(*name) != output_tool_name
})
.collect::<Vec<_>>();
if !missing.is_empty() {
let active_tools_caused = pre_filter_tool_names
.is_some_and(|pf| missing.iter().any(|name| pf.contains(*name)));
return Err(PrepareError::Request(format!(
"ToolChoice::Specific requested tool names not advertised this turn: \
{missing:?}. Advertised: {:?}.{}",
advertised(),
hint(active_tools_caused)
)));
}
requested
}
};
Ok(allowed)
}
#[cfg(test)]
mod tests;