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, Message, ProviderCapabilities, ToolDefinition,
15};
16use rig_core::error::ProviderError;
17use rig_core::message::ToolChoice;
18
19use super::output::OutputMode;
20use super::patch::RequestPatch;
21use super::spec::RunSpec;
22
23/// Why a request could not be prepared. Every variant is a local, pre-IO
24/// error: the spec, patch and tool set cannot produce a request the model
25/// could honor.
26#[derive(Debug, thiserror::Error)]
27pub enum PrepareError {
28    /// The effective request is invalid (an impossible tool choice, an
29    /// `active_tools` name that is not available, an output-tool collision).
30    #[error("{0}")]
31    Request(String),
32    /// `output_schema` is not a valid JSON schema.
33    #[error("invalid output schema: {0}")]
34    InvalidOutputSchema(#[source] serde_json::Error),
35}
36
37impl From<PrepareError> for ProviderError {
38    fn from(error: PrepareError) -> Self {
39        ProviderError::request(error.to_string())
40    }
41}
42
43/// Everything a model call carries that the protocol decides, as owned data.
44///
45/// Apply it to a provider's request builder with [`apply`](Self::apply); the
46/// driver adds only what is its own (telemetry flags), then sends. The
47/// bookkeeping fields (`executable_tool_names`, `allowed_tool_names`,
48/// `output_tool_name`, `output_mode`) are what the driver feeds back into the
49/// run when the response arrives.
50#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
51pub struct PreparedRequest {
52    /// Prior messages to send: the effective (possibly augmented) preamble as a
53    /// leading system message, then the history (the patch's `history` when
54    /// set, else the caller's).
55    pub chat_history: Vec<Message>,
56    /// Static context documents followed by the patch's `extra_context`.
57    pub documents: Vec<Document>,
58    /// The tools advertised to the model this turn, in order: the executable
59    /// tools (after any `active_tools` allow-list) plus, in Tool output mode,
60    /// the synthetic output tool last.
61    pub tools: Vec<ToolDefinition>,
62    /// Effective sampling temperature (patch over spec).
63    pub temperature: Option<f64>,
64    /// Effective output-token cap, with patch values overriding the spec.
65    pub max_tokens: Option<u64>,
66    /// Effective provider passthrough parameters (patch shallow-merged over
67    /// spec when both are objects).
68    pub additional_params: Option<serde_json::Value>,
69    /// Effective tool choice (patch over spec).
70    pub tool_choice: Option<ToolChoice>,
71    /// The provider-native structured-output constraint, set only when the
72    /// resolved mode is [`OutputMode::Native`].
73    pub output_schema: Option<rig_core::schemars::Schema>,
74    /// The mode this turn actually runs in (never [`OutputMode::Auto`]).
75    pub output_mode: OutputMode,
76    /// Names of the real, dispatchable tools advertised this turn.
77    pub executable_tool_names: BTreeSet<String>,
78    /// Names the model may call without it being an invalid tool call: the
79    /// executable tools narrowed by the tool choice, plus the output tool.
80    pub allowed_tool_names: BTreeSet<String>,
81    /// In Tool output mode, the synthetic output tool's name (allowed but never
82    /// executable); reuse it as `committed_output_tool` on later turns.
83    pub output_tool_name: Option<String>,
84}
85
86impl PreparedRequest {
87    /// Apply every prepared field to `request`, in the protocol's canonical
88    /// order. The request keeps its prompt last; the prepared sampling fields
89    /// (`temperature`, `max_tokens`, `output_schema`) overwrite whatever the
90    /// driver set on it, while messages, documents, tools and additional
91    /// parameters accumulate.
92    pub fn apply(self, request: CompletionRequest) -> CompletionRequest {
93        let request = request
94            .messages(self.chat_history)
95            .temperature(self.temperature)
96            .max_tokens(self.max_tokens)
97            .additional_params(self.additional_params)
98            .documents(self.documents)
99            .tools(self.tools)
100            .output_schema(self.output_schema);
101        match self.tool_choice {
102            Some(tool_choice) => request.tool_choice(tool_choice),
103            None => request,
104        }
105    }
106}
107
108/// Prepare one model call from settings, capability snapshot, ordered history,
109/// retrieved tools in advertisement order, and an optional merged patch.
110/// A committed output-tool name pins tool mode while a schema is present.
111/// Returns errors for incompatible tool choices, unavailable allow-list names,
112/// output-tool collisions, or invalid native schemas. Performs no I/O.
113pub fn prepare_request(
114    spec: &RunSpec,
115    capabilities: &ProviderCapabilities,
116    history: &[Message],
117    tools: Vec<ToolDefinition>,
118    committed_output_tool: Option<&str>,
119    patch: Option<&RequestPatch>,
120) -> Result<PreparedRequest, PrepareError> {
121    let request_patch = patch;
122    let chat_history = history;
123    let preamble = spec.preamble.as_deref();
124    let static_context = &spec.static_context;
125    let temperature = spec.temperature;
126    let max_tokens = spec.max_tokens;
127    let additional_params = spec.additional_params.as_ref();
128    let tool_choice = spec.tool_choice.as_ref();
129    let output_schema = spec.output_schema.as_ref();
130    let output_mode = &spec.output_mode;
131    let output_tool_description = spec.output_tool_description.as_deref();
132    let augment_output_preamble = spec.augment_output_preamble;
133    let preamble = request_patch
134        .and_then(|o| o.preamble.as_deref())
135        .or(preamble);
136    let temperature = request_patch.and_then(|o| o.temperature).or(temperature);
137    let max_tokens = request_patch.and_then(|o| o.max_tokens).or(max_tokens);
138    let tool_choice = request_patch
139        .and_then(|o| o.tool_choice.as_ref())
140        .or(tool_choice);
141    // Non-object patches must replace the baseline; the object merge helper
142    // otherwise retains its first argument for these inputs.
143    let additional_params: Option<serde_json::Value> = match (
144        additional_params,
145        request_patch.and_then(|o| o.additional_params.as_ref()),
146    ) {
147        (Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
148            Some(rig_core::json_utils::merge(base.clone(), patch.clone()))
149        }
150        (base, patch) => patch.or(base).cloned(),
151    };
152    let active_tools = request_patch.and_then(|o| o.active_tools.as_deref());
153
154    // Reserve output names against the full tool set because filtered tools may
155    // return on later turns while the output name remains pinned.
156    let pre_filter_tool_names: Option<BTreeSet<String>> =
157        active_tools.map(|_| tools.iter().map(|tool| tool.name.clone()).collect());
158
159    // Filter before computing executable names so request advertisements and
160    // runtime validation agree. Synthetic output remains independent of this filter.
161    let mut tooldefs = tools;
162    if let Some(allow) = active_tools {
163        if let Some(missing) = allow
164            .iter()
165            .find(|name| !tooldefs.iter().any(|tool| &tool.name == *name))
166        {
167            return Err(PrepareError::Request(format!(
168                "active_tools requested tool `{missing}`, which is not available this turn"
169            )));
170        }
171        let allowed: BTreeSet<String> = allow.iter().cloned().collect();
172        tooldefs.retain(|tool| allowed.contains(&tool.name));
173    }
174
175    // The synthetic output tool must never enter the executable set.
176    let executable_tool_names: BTreeSet<String> =
177        tooldefs.iter().map(|tool| tool.name.clone()).collect();
178
179    // Resolve against the actual candidate name so Specific choices can permit
180    // the output tool. A committed name prevents changing output mode mid-run.
181    let candidate_output_tool = committed_output_tool.map_or_else(
182        || {
183            pick_output_tool_name(
184                pre_filter_tool_names
185                    .as_ref()
186                    .unwrap_or(&executable_tool_names),
187            )
188        },
189        str::to_owned,
190    );
191    let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
192        OutputMode::Tool
193    } else {
194        resolve_output_mode(
195            output_schema.is_some(),
196            !executable_tool_names.is_empty(),
197            output_tool_callable(tool_choice, &candidate_output_tool),
198            capabilities.composes_native_output_with_tools,
199            output_mode,
200        )
201    };
202
203    let output_tool_name =
204        matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
205
206    // A later real tool may collide with a pinned output name; reject it before
207    // a real tool call can be mistaken for run finalization.
208    if let Some(name) = &output_tool_name
209        && executable_tool_names.contains(name)
210    {
211        return Err(PrepareError::Request(format!(
212            "real tool `{name}` conflicts with the structured-output tool reserved for this \
213             run; rename or remove the real tool, exclude it with `active_tools`, or make it \
214             visible before starting a new run so Rig can reserve a different output-tool name"
215        )));
216    }
217
218    // Pinned tool mode cannot fall back to native output when a later choice
219    // forbids its output call, so report the incompatible policy.
220    if let Some(name) = &output_tool_name
221        && !output_tool_callable(tool_choice, name)
222    {
223        tracing::warn!(
224            "the active tool_choice forbids calling the structured-output tool while the \
225             run is pinned to Tool output mode; this turn cannot emit the structured \
226             result (check for a `RequestPatch` setting `tool_choice` to None or a \
227             Specific set that excludes the output tool)"
228        );
229    }
230
231    let effective_preamble: Option<String> = {
232        let base = preamble.map(str::to_owned);
233        let instruction = match &resolved_mode {
234            OutputMode::Tool if augment_output_preamble => {
235                output_tool_name.as_deref().map(|name| {
236                    format!(
237                        "When you have gathered enough information to answer, call the `{name}` \
238                     tool exactly once with your final answer. Its arguments are the structured \
239                     result and must satisfy the required schema. Do not return the final answer \
240                     as plain text."
241                    )
242                })
243            }
244            OutputMode::Tool => None,
245            OutputMode::Prompted => output_schema.map(|schema| {
246                let schema_json = rig_core::json_utils::to_canonical_string(schema);
247                format!(
248                    "Respond with ONLY a single JSON object that conforms to this JSON Schema. \
249                     Do not include any prose, explanation, or markdown code fences.\n{schema_json}"
250                )
251            }),
252            OutputMode::Native | OutputMode::Auto => None,
253        };
254        match (base, instruction) {
255            (Some(b), Some(i)) => Some(format!("{b}\n\n{i}")),
256            (Some(b), None) => Some(b),
257            (None, Some(i)) => Some(i),
258            (None, None) => None,
259        }
260    };
261
262    // Request history replacement must not mutate persisted conversation history.
263    let messages_history: &[Message] = request_patch
264        .and_then(|o| o.history.as_deref())
265        .unwrap_or(chat_history);
266    let chat_history: Vec<Message> = if let Some(preamble) = &effective_preamble {
267        std::iter::once(Message::system(preamble.clone()))
268            .chain(messages_history.iter().cloned())
269            .collect()
270    } else {
271        messages_history.to_vec()
272    };
273
274    if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
275        tooldefs.push(ToolDefinition {
276            name: name.clone(),
277            description: output_tool_description
278                .unwrap_or(
279                    "Call this tool exactly once with your final answer when you are done. \
280                     Its arguments are the structured result and must satisfy the output schema.",
281                )
282                .to_string(),
283            parameters: schema.clone(),
284        });
285    }
286
287    let native_schema = match (&resolved_mode, output_schema) {
288        (OutputMode::Native, Some(schema)) => Some(
289            rig_core::schemars::Schema::try_from(schema.clone())
290                .map_err(PrepareError::InvalidOutputSchema)?,
291        ),
292        _ => None,
293    };
294
295    let mut documents = static_context.clone();
296    if let Some(patch) = request_patch {
297        documents.extend(patch.extra_context.iter().cloned());
298    }
299
300    // Reject impossible choices before spending a provider request.
301    let mut allowed_tool_names = allowed_tool_names_for_choice(
302        &executable_tool_names,
303        tool_choice,
304        output_tool_name.as_deref(),
305        pre_filter_tool_names.as_ref(),
306    )?;
307    // The output tool must be allowed (so it isn't flagged as an invalid tool
308    // call) even though it is not executable.
309    if let Some(name) = &output_tool_name {
310        allowed_tool_names.insert(name.clone());
311    }
312
313    Ok(PreparedRequest {
314        chat_history,
315        documents,
316        tools: tooldefs,
317        temperature,
318        max_tokens,
319        additional_params,
320        tool_choice: tool_choice.cloned(),
321        output_schema: native_schema,
322        output_mode: resolved_mode,
323        executable_tool_names,
324        allowed_tool_names,
325        output_tool_name,
326    })
327}
328
329/// Base name of the synthetic output tool used by [`OutputMode::Tool`].
330const DEFAULT_OUTPUT_TOOL_NAME: &str = "final_result";
331
332/// Return whether tool choice permits the named output tool. Unspecified, auto,
333/// required, and specific choices naming it permit the call.
334fn output_tool_callable(tool_choice: Option<&ToolChoice>, output_tool_name: &str) -> bool {
335    match tool_choice {
336        None | Some(ToolChoice::Auto | ToolChoice::Required) => true,
337        Some(ToolChoice::None) => false,
338        Some(ToolChoice::Specific { function_names }) => function_names
339            .iter()
340            .any(|name| name.as_str() == output_tool_name),
341    }
342}
343
344/// Resolve to a non-auto mode. Without a schema, use native output. Auto selects
345/// tool output only with executable tools, a callable output tool, and no native
346/// composition support. Explicit tool mode falls back to native if uncallable;
347/// native and prompted modes remain unchanged when a schema is present.
348fn resolve_output_mode(
349    has_schema: bool,
350    has_executable_tools: bool,
351    output_tool_callable: bool,
352    provider_composes_native: bool,
353    requested: &OutputMode,
354) -> OutputMode {
355    if !has_schema {
356        return OutputMode::Native;
357    }
358    match requested {
359        OutputMode::Native => OutputMode::Native,
360        OutputMode::Prompted => OutputMode::Prompted,
361        OutputMode::Tool if output_tool_callable => OutputMode::Tool,
362        OutputMode::Tool => OutputMode::Native,
363        OutputMode::Auto
364            if has_executable_tools && output_tool_callable && !provider_composes_native =>
365        {
366            OutputMode::Tool
367        }
368        OutputMode::Auto => OutputMode::Native,
369    }
370}
371
372/// Pick a collision-safe name for the synthetic output tool, never shadowing a
373/// real executable tool (which would make the model's output call dispatchable).
374fn pick_output_tool_name(executable_tool_names: &BTreeSet<String>) -> String {
375    let mut name = DEFAULT_OUTPUT_TOOL_NAME.to_string();
376    let mut suffix = 1u32;
377    while executable_tool_names.contains(&name) {
378        name = format!("{DEFAULT_OUTPUT_TOOL_NAME}_{suffix}");
379        suffix += 1;
380    }
381    name
382}
383
384/// Validate tool choice and return permitted names. Auto and required choices
385/// return executable names; specific choices return their requested names,
386/// including the output tool if named. None returns an empty set.
387/// Errors on required choice without any advertised tool, empty specific choices,
388/// or names absent from executable tools and the output tool. Supply pre-filter
389/// names only when an allow-list was applied, for filter-specific diagnostics.
390pub fn allowed_tool_names_for_choice(
391    executable_tool_names: &BTreeSet<String>,
392    tool_choice: Option<&ToolChoice>,
393    output_tool_name: Option<&str>,
394    pre_filter_tool_names: Option<&BTreeSet<String>>,
395) -> Result<BTreeSet<String>, PrepareError> {
396    let has_advertised_tool = !executable_tool_names.is_empty() || output_tool_name.is_some();
397    let hint = |active_tools_caused: bool| {
398        if active_tools_caused {
399            " A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
400             set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
401        } else {
402            ""
403        }
404    };
405    let advertised = || {
406        executable_tool_names
407            .iter()
408            .map(String::as_str)
409            .chain(output_tool_name)
410            .collect::<Vec<_>>()
411    };
412
413    let allowed = match tool_choice {
414        None | Some(ToolChoice::Auto) => executable_tool_names.clone(),
415        Some(ToolChoice::Required) => {
416            if !has_advertised_tool {
417                let active_tools_caused = pre_filter_tool_names.is_some_and(|pf| !pf.is_empty());
418                return Err(PrepareError::Request(format!(
419                    "ToolChoice::Required forces the model to call a tool, but no tools are \
420                     advertised this turn.{}",
421                    hint(active_tools_caused)
422                )));
423            }
424            executable_tool_names.clone()
425        }
426        Some(ToolChoice::None) => BTreeSet::new(),
427        Some(ToolChoice::Specific { function_names }) => {
428            if function_names.is_empty() {
429                return Err(PrepareError::Request(
430                    "ToolChoice::Specific requires at least one function name".to_string(),
431                ));
432            }
433
434            let requested = function_names.iter().cloned().collect::<BTreeSet<String>>();
435            let missing = function_names
436                .iter()
437                .map(String::as_str)
438                .filter(|name| {
439                    !executable_tool_names.contains(*name) && Some(*name) != output_tool_name
440                })
441                .collect::<Vec<_>>();
442
443            if !missing.is_empty() {
444                // Attribute missing names to filtering only if they existed before it.
445                let active_tools_caused = pre_filter_tool_names
446                    .is_some_and(|pf| missing.iter().any(|name| pf.contains(*name)));
447                return Err(PrepareError::Request(format!(
448                    "ToolChoice::Specific requested tool names not advertised this turn: \
449                     {missing:?}. Advertised: {:?}.{}",
450                    advertised(),
451                    hint(active_tools_caused)
452                )));
453            }
454
455            requested
456        }
457    };
458
459    Ok(allowed)
460}
461
462#[cfg(test)]
463mod tests;