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;
12use std::sync::Arc;
13
14use rig_core::completion::{
15    CompletionRequest, Document, GenerationOptions, Message, ProviderCapabilities, ProviderOptions,
16    ProviderToolDefinition, ToolDefinition,
17};
18use rig_core::error::ProviderError;
19use rig_core::message::ToolName;
20use rig_core::structured_output::{
21    AUGMENTATION_SEPARATOR, OUTPUT_TOOL_DESCRIPTION, output_tool_augmentation,
22    output_tool_callable, output_tool_name, prompted_augmentation,
23};
24
25use super::output::OutputMode;
26use super::patch::RequestPatch;
27use super::policy::TurnPolicy;
28use super::spec::RunSpec;
29
30/// Why a request could not be prepared: a local, pre-IO error. The effective
31/// request is invalid (an impossible tool choice, an `active_tools` name that
32/// is not available, an output-tool collision).
33#[derive(Debug, thiserror::Error)]
34pub enum PrepareError {
35    /// The request the spec, patch and tool set describe.
36    #[error("{0}")]
37    Request(String),
38}
39
40impl From<PrepareError> for ProviderError {
41    fn from(error: PrepareError) -> Self {
42        ProviderError::request(error.to_string())
43    }
44}
45
46/// Everything a model call carries that the protocol decides, as owned data.
47///
48/// Apply it to a provider's request builder with [`apply`](Self::apply); the
49/// driver adds only what is its own (telemetry flags), then sends. The
50/// turn's [`policy`](Self::policy) is what the driver feeds back into the run
51/// when the response arrives.
52#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
53pub struct PreparedRequest {
54    /// Prior messages to send: the effective (possibly augmented) preamble as a
55    /// leading system message, then the history (the patch's `history` when
56    /// set, else the caller's).
57    pub chat_history: Vec<Arc<Message>>,
58    /// Static context documents followed by the patch's `extra_context`.
59    pub documents: Vec<Document>,
60    /// The tools advertised to the model this turn, in order: the executable
61    /// tools (after any `active_tools` allow-list) plus, in Tool output mode,
62    /// the synthetic output tool last.
63    pub tools: Vec<Arc<ToolDefinition>>,
64    /// Effective sampling temperature (patch over spec).
65    pub temperature: Option<f64>,
66    /// Effective output-token cap, with patch values overriding the spec.
67    pub max_tokens: Option<u64>,
68    /// Effective provider passthrough parameters (patch shallow-merged over
69    /// spec when both are objects).
70    pub additional_params: Option<serde_json::Value>,
71    /// The spec's provider-hosted tools, appended to
72    /// `additional_params.tools` by [`apply`](Self::apply).
73    #[serde(default, skip_serializing_if = "Vec::is_empty")]
74    pub provider_tools: Vec<ProviderToolDefinition>,
75    /// The spec's portable generation options.
76    #[serde(default, skip_serializing_if = "GenerationOptions::is_default")]
77    pub options: GenerationOptions,
78    /// The spec's typed per-provider options.
79    #[serde(default, skip_serializing_if = "ProviderOptions::is_empty")]
80    pub provider_options: ProviderOptions,
81    /// The provider-native structured-output constraint, set only when the
82    /// resolved mode is [`OutputMode::Native`].
83    pub output_schema: Option<rig_core::schemars::Schema>,
84    /// The mode this turn actually runs in (never [`OutputMode::Auto`]).
85    pub output_mode: OutputMode,
86    /// The turn's tool policy: executable tools, effective tool choice
87    /// (patch over spec), output tool and the names the choice allows.
88    pub policy: TurnPolicy,
89    /// The spec's [`RunSpec::accept_unknown_finish_reasons`].
90    #[serde(default)]
91    pub accept_unknown_finish_reasons: bool,
92}
93
94impl PreparedRequest {
95    /// Apply every prepared field to `request`, in the protocol's canonical
96    /// order. The request keeps its prompt last; the prepared sampling fields
97    /// (`temperature`, `max_tokens`, `output_schema`) and
98    /// `accept_unknown_finish_reasons` overwrite whatever the driver set on
99    /// it, while messages, documents, tools and additional parameters
100    /// accumulate.
101    pub fn apply(self, mut request: CompletionRequest) -> CompletionRequest {
102        request.accept_unknown_finish_reasons = self.accept_unknown_finish_reasons;
103        let request = request
104            .messages(self.chat_history)
105            .temperature(self.temperature)
106            .max_tokens(self.max_tokens)
107            .additional_params(self.additional_params)
108            .options(self.options)
109            .provider_options(self.provider_options)
110            .documents(self.documents)
111            .tools(self.tools)
112            .provider_tools(self.provider_tools)
113            .output_schema(self.output_schema);
114        match self.policy.tool_choice() {
115            Some(tool_choice) => request.tool_choice(tool_choice.clone()),
116            None => request,
117        }
118    }
119}
120
121/// Prepare one model call from settings, capability snapshot, ordered history,
122/// retrieved tools in advertisement order, and an optional merged patch.
123/// A committed output-tool name pins tool mode while a schema is present.
124/// Returns errors for incompatible tool choices, unavailable allow-list names,
125/// output-tool collisions, or invalid native schemas. Performs no I/O.
126pub fn prepare_request(
127    spec: &RunSpec,
128    capabilities: &ProviderCapabilities,
129    history: &[Arc<Message>],
130    tools: Vec<Arc<ToolDefinition>>,
131    committed_output_tool: Option<&str>,
132    patch: Option<&RequestPatch>,
133) -> Result<PreparedRequest, PrepareError> {
134    let request_patch = patch;
135    let chat_history = history;
136    let preamble = spec.preamble.as_deref();
137    let static_context = &spec.static_context;
138    let temperature = spec.temperature;
139    let max_tokens = spec.max_tokens;
140    let additional_params = spec.additional_params.as_ref();
141    let tool_choice = spec.tool_choice.as_ref();
142    let output_schema = spec.output_schema.as_ref();
143    let output_mode = &spec.output_mode;
144    let output_tool_description = spec.output_tool_description.as_deref();
145    let augment_output_preamble = spec.augment_output_preamble;
146    let preamble = request_patch
147        .and_then(|o| o.preamble.as_deref())
148        .or(preamble);
149    let temperature = request_patch.and_then(|o| o.temperature).or(temperature);
150    let max_tokens = request_patch.and_then(|o| o.max_tokens).or(max_tokens);
151    let tool_choice = request_patch
152        .and_then(|o| o.tool_choice.as_ref())
153        .or(tool_choice);
154    // Non-object patches must replace the baseline; the object merge helper
155    // otherwise retains its first argument for these inputs.
156    let additional_params: Option<serde_json::Value> = match (
157        additional_params,
158        request_patch.and_then(|o| o.additional_params.as_ref()),
159    ) {
160        (Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
161            Some(rig_core::json_utils::merge(base.clone(), patch.clone()))
162        }
163        (base, patch) => patch.or(base).cloned(),
164    };
165    let active_tools = request_patch.and_then(|o| o.active_tools.as_deref());
166    // Hosted tools also arrive as raw `additional_params.tools`; providers
167    // advertise both after the function tools.
168    let hosted = !spec.provider_tools.is_empty()
169        || additional_params
170            .as_ref()
171            .and_then(|params| params.get("tools"))
172            .and_then(serde_json::Value::as_array)
173            .is_some_and(|tools| !tools.is_empty());
174
175    // Reserve output names against the full tool set because filtered tools may
176    // return on later turns while the output name remains pinned.
177    let pre_filter_tool_names: Option<BTreeSet<String>> =
178        active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
179
180    // Filter before computing executable names so request advertisements and
181    // runtime validation agree. Synthetic output remains independent of this filter.
182    let mut tooldefs = tools;
183    if let Some(allow) = active_tools {
184        if let Some(missing) = allow
185            .iter()
186            .find(|name| !tooldefs.iter().any(|tool| tool.name == **name))
187        {
188            return Err(PrepareError::Request(format!(
189                "active_tools requested tool `{missing}`, which is not available this turn"
190            )));
191        }
192        let allowed: BTreeSet<String> = allow.iter().cloned().collect();
193        tooldefs.retain(|tool| allowed.contains(tool.name.as_str()));
194    }
195
196    // The synthetic output tool must never enter the executable set.
197    let executable_tool_names: BTreeSet<String> =
198        tooldefs.iter().map(|tool| tool.name.to_string()).collect();
199
200    // Resolve against the actual candidate name so Specific choices can permit
201    // the output tool. A committed name prevents changing output mode mid-run.
202    let candidate_output_tool = committed_output_tool.map_or_else(
203        || {
204            let taken = pre_filter_tool_names
205                .as_ref()
206                .unwrap_or(&executable_tool_names);
207            output_tool_name(|name| taken.contains(name))
208        },
209        str::to_owned,
210    );
211    let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
212        OutputMode::Tool
213    } else {
214        resolve_output_mode(
215            output_schema.is_some(),
216            hosted || !executable_tool_names.is_empty(),
217            output_tool_callable(tool_choice, &candidate_output_tool),
218            capabilities.composes_native_output_with_tools,
219            output_mode,
220        )
221    };
222
223    let output_tool_name =
224        matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
225
226    // A later real tool may collide with a pinned output name; reject it before
227    // a real tool call can be mistaken for run finalization.
228    if let Some(name) = &output_tool_name
229        && executable_tool_names.contains(name)
230    {
231        return Err(PrepareError::Request(format!(
232            "real tool `{name}` conflicts with the structured-output tool reserved for this \
233             run; rename or remove the real tool, exclude it with `active_tools`, or make it \
234             visible before starting a new run so Rig can reserve a different output-tool name"
235        )));
236    }
237
238    // Pinned tool mode cannot fall back to native output when a later choice
239    // forbids its output call, so report the incompatible policy.
240    if let Some(name) = &output_tool_name
241        && !output_tool_callable(tool_choice, name)
242    {
243        tracing::warn!(
244            "the active tool_choice forbids calling the structured-output tool while the \
245             run is pinned to Tool output mode; this turn cannot emit the structured \
246             result (check for a `RequestPatch` setting `tool_choice` to None or a \
247             Specific set that excludes the output tool)"
248        );
249    }
250
251    let effective_preamble: Option<String> = {
252        let base = preamble.map(str::to_owned);
253        let instruction = match &resolved_mode {
254            OutputMode::Tool if augment_output_preamble => {
255                output_tool_name.as_deref().map(output_tool_augmentation)
256            }
257            OutputMode::Tool => None,
258            OutputMode::Prompted => output_schema.map(|schema| {
259                prompted_augmentation(&rig_core::json_utils::to_canonical_string(
260                    schema.as_value(),
261                ))
262            }),
263            OutputMode::Native | OutputMode::Auto => None,
264        };
265        match (base, instruction) {
266            (Some(b), Some(i)) => Some(format!("{b}{AUGMENTATION_SEPARATOR}{i}")),
267            (Some(b), None) => Some(b),
268            (None, Some(i)) => Some(i),
269            (None, None) => None,
270        }
271    };
272
273    // Request history replacement must not mutate persisted conversation history.
274    let messages_history: &[Arc<Message>] = request_patch
275        .and_then(|o| o.history.as_deref())
276        .unwrap_or(chat_history);
277    let preamble = effective_preamble.map(|preamble| Arc::new(Message::system(preamble)));
278    let chat_history: Vec<Arc<Message>> = preamble
279        .into_iter()
280        .chain(messages_history.iter().cloned())
281        .collect();
282
283    if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
284        tooldefs.push(Arc::new(ToolDefinition {
285            name: ToolName::new(name.clone()).map_err(|_| {
286                PrepareError::Request("the output tool name cannot be empty".to_string())
287            })?,
288            description: output_tool_description
289                .unwrap_or(OUTPUT_TOOL_DESCRIPTION)
290                .to_string(),
291            parameters: schema.as_value().clone(),
292            annotations: Default::default(),
293        }));
294    }
295
296    let native_schema = match (&resolved_mode, output_schema) {
297        (OutputMode::Native, Some(schema)) => Some(schema.clone()),
298        _ => None,
299    };
300
301    let mut documents = static_context.clone();
302    if let Some(patch) = request_patch {
303        documents.extend(patch.extra_context.iter().cloned());
304    }
305
306    // Reject impossible choices before spending a provider request.
307    let policy = TurnPolicy::resolve(
308        executable_tool_names,
309        tool_choice.cloned(),
310        output_tool_name,
311        pre_filter_tool_names.as_ref(),
312        hosted,
313    )?;
314
315    Ok(PreparedRequest {
316        chat_history,
317        documents,
318        tools: tooldefs,
319        temperature,
320        max_tokens,
321        additional_params,
322        provider_tools: spec.provider_tools.clone(),
323        options: spec.options.clone(),
324        provider_options: spec.provider_options.clone(),
325        output_schema: native_schema,
326        output_mode: resolved_mode,
327        policy,
328        accept_unknown_finish_reasons: spec.accept_unknown_finish_reasons,
329    })
330}
331
332/// Resolve to a non-auto mode. Without a schema, use native output. Auto selects
333/// tool output only with advertised tools (executable or hosted), a callable
334/// output tool, and no native composition support. Explicit tool mode falls
335/// back to native if uncallable; native and prompted modes remain unchanged
336/// when a schema is present.
337fn resolve_output_mode(
338    has_schema: bool,
339    has_tools: bool,
340    output_tool_callable: bool,
341    provider_composes_native: bool,
342    requested: &OutputMode,
343) -> OutputMode {
344    if !has_schema {
345        return OutputMode::Native;
346    }
347    match requested {
348        OutputMode::Native => OutputMode::Native,
349        OutputMode::Prompted => OutputMode::Prompted,
350        OutputMode::Tool if output_tool_callable => OutputMode::Tool,
351        OutputMode::Tool => OutputMode::Native,
352        OutputMode::Auto if has_tools && output_tool_callable && !provider_composes_native => {
353            OutputMode::Tool
354        }
355        OutputMode::Auto => OutputMode::Native,
356    }
357}
358
359#[cfg(test)]
360mod tests;