Skip to main content

rig_agent/run/
prepare.rs

1//! Pure request preparation from run settings, model capabilities, the prompt,
2//! history, tools, and per-turn overrides. Retrieval and model execution remain
3//! driver responsibilities.
4//!
5//! ```
6//! use rig_agent::run::{prepare::prepare_request, spec::RunSpec};
7//! let prepared =
8//!     prepare_request(&RunSpec::new(), &Default::default(), "hi", &[], vec![], None, None)?;
9//! assert!(prepared.request.tools.is_empty());
10//! # Ok::<(), rig_core::error::ProviderError>(())
11//! ```
12
13use std::collections::BTreeSet;
14use std::sync::Arc;
15
16use rig_core::completion::{CompletionRequest, Message, ProviderCapabilities, ToolDefinition};
17use rig_core::error::ProviderError;
18use rig_core::message::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, overlay_params};
26use super::policy::TurnPolicy;
27use super::spec::RunSpec;
28
29/// Everything a model call carries that the protocol decides, as owned data.
30///
31/// The driver adds only what is its own (telemetry flags) to
32/// [`request`](Self::request), then sends it. The turn's
33/// [`policy`](Self::policy) is what the driver feeds back into the run when
34/// the response arrives.
35#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
36pub struct PreparedRequest {
37    /// The request to send. Its history is the effective (possibly augmented)
38    /// preamble as a leading system message, then the patch's `history` when
39    /// set (else the caller's), then the prompt. Its documents are the static
40    /// context followed by the patch's `extra_context`. Its tools are the
41    /// executable tools (after any `active_tools` allow-list) plus, in Tool
42    /// output mode, the synthetic output tool last. Temperature, output-token
43    /// cap and tool choice take the patch over the spec; `additional_params`
44    /// shallow-merge the patch over the spec when both are objects and carry
45    /// the spec's provider-hosted tools in `tools`. The output schema is set
46    /// only when the resolved mode is [`OutputMode::Native`].
47    pub request: CompletionRequest,
48    /// The mode this turn actually runs in (never [`OutputMode::Auto`]).
49    pub output_mode: OutputMode,
50    /// The turn's tool policy: executable tools, effective tool choice
51    /// (patch over spec), output tool and the names the choice allows.
52    pub policy: TurnPolicy,
53}
54
55/// Prepare one model call from settings, capability snapshot, the prompt,
56/// ordered history, retrieved tools in advertisement order, and an optional
57/// merged patch.
58/// A committed output-tool name pins tool mode while a schema is present.
59/// Returns errors for incompatible tool choices, unavailable allow-list names,
60/// output-tool collisions, invalid native schemas, or provider tools beside
61/// `additional_params` that is a string, array or number, as
62/// [`ProviderError::Request`]: a local error, raised before any I/O.
63pub fn prepare_request(
64    spec: &RunSpec,
65    capabilities: &ProviderCapabilities,
66    prompt: impl Into<Message>,
67    history: &[Arc<Message>],
68    tools: Vec<Arc<ToolDefinition>>,
69    committed_output_tool: Option<&str>,
70    patch: Option<&RequestPatch>,
71) -> Result<PreparedRequest, ProviderError> {
72    let output_schema = spec.output_schema.as_ref();
73    let preamble = patch
74        .and_then(|o| o.preamble.as_deref())
75        .or(spec.preamble.as_deref());
76    let temperature = patch.and_then(|o| o.temperature).or(spec.temperature);
77    let max_tokens = patch.and_then(|o| o.max_tokens).or(spec.max_tokens);
78    let tool_choice = patch
79        .and_then(|o| o.tool_choice.as_ref())
80        .or(spec.tool_choice.as_ref());
81    let additional_params = overlay_params(
82        spec.additional_params.clone(),
83        patch.and_then(|o| o.additional_params.clone()),
84    );
85    // Provider tools are sent in `additional_params.tools`, which a string,
86    // array or number cannot carry; rig-core's merge reads a bool as `stream`
87    // and null as no params.
88    if !spec.provider_tools.is_empty()
89        && let Some(
90            params @ (serde_json::Value::String(_)
91            | serde_json::Value::Array(_)
92            | serde_json::Value::Number(_)),
93        ) = &additional_params
94    {
95        return Err(ProviderError::request(format!(
96            "additional_params must be a JSON object to carry provider tools, got {params}"
97        )));
98    }
99    let active_tools = patch.and_then(|o| o.active_tools.as_deref());
100    // Hosted tools also arrive as raw `additional_params.tools`; providers
101    // advertise both after the function tools.
102    let hosted = !spec.provider_tools.is_empty()
103        || additional_params
104            .as_ref()
105            .and_then(|params| params.get("tools"))
106            .and_then(serde_json::Value::as_array)
107            .is_some_and(|tools| !tools.is_empty());
108
109    // Reserve output names against the full tool set because filtered tools may
110    // return on later turns while the output name remains pinned.
111    let pre_filter_tool_names: Option<BTreeSet<String>> =
112        active_tools.map(|_| tools.iter().map(|tool| tool.name.to_string()).collect());
113
114    // Filter before computing executable names so request advertisements and
115    // runtime validation agree. Synthetic output remains independent of this filter.
116    let mut tooldefs = tools;
117    if let Some(allow) = active_tools {
118        if let Some(missing) = allow
119            .iter()
120            .find(|name| !tooldefs.iter().any(|tool| tool.name == **name))
121        {
122            return Err(ProviderError::request(format!(
123                "active_tools requested tool `{missing}`, which is not available this turn"
124            )));
125        }
126        let allowed: BTreeSet<String> = allow.iter().cloned().collect();
127        tooldefs.retain(|tool| allowed.contains(tool.name.as_str()));
128    }
129
130    // The synthetic output tool must never enter the executable set.
131    let executable_tool_names: BTreeSet<String> =
132        tooldefs.iter().map(|tool| tool.name.to_string()).collect();
133
134    // Resolve against the actual candidate name so Specific choices can permit
135    // the output tool. A committed name prevents changing output mode mid-run.
136    let candidate_output_tool = committed_output_tool.map_or_else(
137        || {
138            let taken = pre_filter_tool_names
139                .as_ref()
140                .unwrap_or(&executable_tool_names);
141            output_tool_name(|name| taken.contains(name))
142        },
143        str::to_owned,
144    );
145    let resolved_mode = if committed_output_tool.is_some() && output_schema.is_some() {
146        OutputMode::Tool
147    } else {
148        resolve_output_mode(
149            output_schema.is_some(),
150            hosted || !executable_tool_names.is_empty(),
151            output_tool_callable(tool_choice, &candidate_output_tool),
152            capabilities.composes_native_output_with_tools,
153            &spec.output_mode,
154        )
155    };
156
157    let output_tool_name =
158        matches!(resolved_mode, OutputMode::Tool).then_some(candidate_output_tool);
159
160    // A later real tool may collide with a pinned output name; reject it before
161    // a real tool call can be mistaken for run finalization.
162    if let Some(name) = &output_tool_name
163        && executable_tool_names.contains(name)
164    {
165        return Err(ProviderError::request(format!(
166            "real tool `{name}` conflicts with the structured-output tool reserved for this \
167             run; rename or remove the real tool, exclude it with `active_tools`, or make it \
168             visible before starting a new run so Rig can reserve a different output-tool name"
169        )));
170    }
171
172    // Pinned tool mode cannot fall back to native output when a later choice
173    // forbids its output call, so report the incompatible policy.
174    if let Some(name) = &output_tool_name
175        && !output_tool_callable(tool_choice, name)
176    {
177        tracing::warn!(
178            "the active tool_choice forbids calling the structured-output tool while the \
179             run is pinned to Tool output mode; this turn cannot emit the structured \
180             result (check for a `RequestPatch` setting `tool_choice` to None or a \
181             Specific set that excludes the output tool)"
182        );
183    }
184
185    let effective_preamble: Option<String> = {
186        let base = preamble.map(str::to_owned);
187        let instruction = match &resolved_mode {
188            OutputMode::Tool if spec.augment_output_preamble => {
189                output_tool_name.as_deref().map(output_tool_augmentation)
190            }
191            OutputMode::Tool => None,
192            OutputMode::Prompted => output_schema.map(|schema| {
193                prompted_augmentation(&rig_core::json_utils::to_canonical_string(
194                    schema.as_value(),
195                ))
196            }),
197            OutputMode::Native | OutputMode::Auto => None,
198        };
199        match (base, instruction) {
200            (Some(b), Some(i)) => Some(format!("{b}{AUGMENTATION_SEPARATOR}{i}")),
201            (Some(b), None) => Some(b),
202            (None, Some(i)) => Some(i),
203            (None, None) => None,
204        }
205    };
206
207    // Request history replacement must not mutate persisted conversation history.
208    let messages_history: &[Arc<Message>] =
209        patch.and_then(|o| o.history.as_deref()).unwrap_or(history);
210    let preamble = effective_preamble.map(|preamble| Arc::new(Message::system(preamble)));
211    let chat_history: Vec<Arc<Message>> = preamble
212        .into_iter()
213        .chain(messages_history.iter().cloned())
214        .collect();
215
216    if let (Some(name), Some(schema)) = (&output_tool_name, output_schema) {
217        tooldefs.push(Arc::new(ToolDefinition {
218            name: ToolName::new(name.clone()).map_err(|_| {
219                ProviderError::request("the output tool name cannot be empty".to_string())
220            })?,
221            description: spec
222                .output_tool_description
223                .as_deref()
224                .unwrap_or(OUTPUT_TOOL_DESCRIPTION)
225                .to_string(),
226            parameters: schema.as_value().clone(),
227            annotations: Default::default(),
228        }));
229    }
230
231    let native_schema = match (&resolved_mode, output_schema) {
232        (OutputMode::Native, Some(schema)) => Some(schema.clone()),
233        _ => None,
234    };
235
236    let mut documents = spec.static_context.clone();
237    if let Some(patch) = patch {
238        documents.extend(patch.extra_context.iter().cloned());
239    }
240
241    // Reject impossible choices before spending a provider request.
242    let policy = TurnPolicy::resolve(
243        executable_tool_names,
244        tool_choice.cloned(),
245        output_tool_name,
246        pre_filter_tool_names.as_ref(),
247        hosted,
248    )?;
249
250    let mut request = CompletionRequest::new(prompt);
251    request.accept_unknown_finish_reasons = spec.accept_unknown_finish_reasons;
252    let request = request
253        .messages(chat_history)
254        .temperature(temperature)
255        .max_tokens(max_tokens)
256        .additional_params(additional_params)
257        .options(spec.options.clone())
258        .provider_options(spec.provider_options.clone())
259        .documents(documents)
260        .tools(tooldefs)
261        .provider_tools(spec.provider_tools.clone())
262        .output_schema(native_schema);
263    let request = match policy.tool_choice() {
264        Some(tool_choice) => request.tool_choice(tool_choice.clone()),
265        None => request,
266    };
267
268    Ok(PreparedRequest {
269        request,
270        output_mode: resolved_mode,
271        policy,
272    })
273}
274
275/// Resolve to a non-auto mode. Without a schema, use native output. Auto selects
276/// tool output only with advertised tools (executable or hosted), a callable
277/// output tool, and no native composition support. Explicit tool mode falls
278/// back to native if uncallable; native and prompted modes remain unchanged
279/// when a schema is present.
280fn resolve_output_mode(
281    has_schema: bool,
282    has_tools: bool,
283    output_tool_callable: bool,
284    provider_composes_native: bool,
285    requested: &OutputMode,
286) -> OutputMode {
287    if !has_schema {
288        return OutputMode::Native;
289    }
290    match requested {
291        OutputMode::Native => OutputMode::Native,
292        OutputMode::Prompted => OutputMode::Prompted,
293        OutputMode::Tool if output_tool_callable => OutputMode::Tool,
294        OutputMode::Tool => OutputMode::Native,
295        OutputMode::Auto if has_tools && output_tool_callable && !provider_composes_native => {
296            OutputMode::Tool
297        }
298        OutputMode::Auto => OutputMode::Native,
299    }
300}
301
302#[cfg(test)]
303mod tests;