Skip to main content

rig_agent/run/
prepare.rs

1//! Pure request preparation from run settings, model capabilities, history, tools,
2//! and per-turn overrides. Retrieval and model execution remain driver responsibilities.
3//!
4//! ```
5//! use rig_agent::run::{prepare::prepare_request, spec::RunSpec};
6//! let request = prepare_request(&RunSpec::new(), &Default::default(), &[], vec![], None, None)?;
7//! assert!(request.tools.is_empty());
8//! # Ok::<(), rig_agent::run::prepare::PrepareError>(())
9//! ```
10
11use 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/// Why a request could not be prepared. Every variant is a local, pre-IO
29/// error: the spec, patch and tool set cannot produce a request the model
30/// could honor.
31#[derive(Debug, thiserror::Error)]
32pub enum PrepareError {
33    /// The effective request is invalid (an impossible tool choice, an
34    /// `active_tools` name that is not available, an output-tool collision).
35    #[error("{0}")]
36    Request(String),
37    /// `output_schema` is not a valid JSON schema.
38    #[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/// Everything a model call carries that the protocol decides, as owned data.
49///
50/// Apply it to a provider's request builder with [`apply`](Self::apply); the
51/// driver adds only what is its own (telemetry flags), then sends. The
52/// bookkeeping fields (`executable_tool_names`, `allowed_tool_names`,
53/// `output_tool_name`, `output_mode`) are what the driver feeds back into the
54/// run when the response arrives.
55#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
56pub struct PreparedRequest {
57    /// Prior messages to send: the effective (possibly augmented) preamble as a
58    /// leading system message, then the history (the patch's `history` when
59    /// set, else the caller's).
60    pub chat_history: Vec<Message>,
61    /// Static context documents followed by the patch's `extra_context`.
62    pub documents: Vec<Document>,
63    /// The tools advertised to the model this turn, in order: the executable
64    /// tools (after any `active_tools` allow-list) plus, in Tool output mode,
65    /// the synthetic output tool last.
66    pub tools: Vec<ToolDefinition>,
67    /// Effective sampling temperature (patch over spec).
68    pub temperature: Option<f64>,
69    /// Effective output-token cap, with patch values overriding the spec.
70    pub max_tokens: Option<u64>,
71    /// Effective provider passthrough parameters (patch shallow-merged over
72    /// spec when both are objects).
73    pub additional_params: Option<serde_json::Value>,
74    /// Effective tool choice (patch over spec).
75    pub tool_choice: Option<ToolChoice>,
76    /// The spec's portable generation options.
77    #[serde(default, skip_serializing_if = "GenerationOptions::is_default")]
78    pub options: GenerationOptions,
79    /// The spec's typed per-provider options.
80    #[serde(default, skip_serializing_if = "ProviderOptions::is_empty")]
81    pub provider_options: ProviderOptions,
82    /// The provider-native structured-output constraint, set only when the
83    /// resolved mode is [`OutputMode::Native`].
84    pub output_schema: Option<rig_core::schemars::Schema>,
85    /// The mode this turn actually runs in (never [`OutputMode::Auto`]).
86    pub output_mode: OutputMode,
87    /// Names of the real, dispatchable tools advertised this turn.
88    pub executable_tool_names: BTreeSet<String>,
89    /// Names the model may call without it being an invalid tool call: the
90    /// executable tools narrowed by the tool choice, plus the output tool.
91    pub allowed_tool_names: BTreeSet<String>,
92    /// In Tool output mode, the synthetic output tool's name (allowed but never
93    /// executable); reuse it as `committed_output_tool` on later turns.
94    pub output_tool_name: Option<String>,
95    /// The spec's [`RunSpec::accept_unknown_finish_reasons`].
96    #[serde(default)]
97    pub accept_unknown_finish_reasons: bool,
98}
99
100impl PreparedRequest {
101    /// Apply every prepared field to `request`, in the protocol's canonical
102    /// order. The request keeps its prompt last; the prepared sampling fields
103    /// (`temperature`, `max_tokens`, `output_schema`) and
104    /// `accept_unknown_finish_reasons` overwrite whatever the driver set on
105    /// it, while messages, documents, tools and additional parameters
106    /// accumulate.
107    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
126/// Prepare one model call from settings, capability snapshot, ordered history,
127/// retrieved tools in advertisement order, and an optional merged patch.
128/// A committed output-tool name pins tool mode while a schema is present.
129/// Returns errors for incompatible tool choices, unavailable allow-list names,
130/// output-tool collisions, or invalid native schemas. Performs no I/O.
131pub 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    // Non-object patches must replace the baseline; the object merge helper
160    // otherwise retains its first argument for these inputs.
161    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    // Reserve output names against the full tool set because filtered tools may
173    // return on later turns while the output name remains pinned.
174    let pre_filter_tool_names: Option<BTreeSet<String>> =
175        active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
176
177    // Filter before computing executable names so request advertisements and
178    // runtime validation agree. Synthetic output remains independent of this filter.
179    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    // The synthetic output tool must never enter the executable set.
194    let executable_tool_names: BTreeSet<String> =
195        tooldefs.iter().map(|tool| tool.name.to_string()).collect();
196
197    // Resolve against the actual candidate name so Specific choices can permit
198    // the output tool. A committed name prevents changing output mode mid-run.
199    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    // A later real tool may collide with a pinned output name; reject it before
224    // a real tool call can be mistaken for run finalization.
225    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    // Pinned tool mode cannot fall back to native output when a later choice
236    // forbids its output call, so report the incompatible policy.
237    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    // Request history replacement must not mutate persisted conversation history.
269    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    // Reject impossible choices before spending a provider request.
306    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    // The output tool must be allowed (so it isn't flagged as an invalid tool
313    // call) even though it is not executable.
314    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
337/// Resolve to a non-auto mode. Without a schema, use native output. Auto selects
338/// tool output only with executable tools, a callable output tool, and no native
339/// composition support. Explicit tool mode falls back to native if uncallable;
340/// native and prompted modes remain unchanged when a schema is present.
341fn 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
365/// Validate tool choice and return permitted names. Auto and required choices
366/// return executable names; specific choices return their requested names,
367/// including the output tool if named. None returns an empty set.
368/// Errors on required choice without any advertised tool, empty specific choices,
369/// or names absent from executable tools and the output tool. Supply pre-filter
370/// names only when an allow-list was applied, for filter-specific diagnostics.
371pub 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                // Attribute missing names to filtering only if they existed before it.
429                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;