Skip to main content

rig_agent/run/
patch.rs

1//! Per-turn overrides applied before request preparation without changing agent defaults.
2//!
3//! ```
4//! use rig_agent::run::patch::RequestPatch;
5//! let patch = RequestPatch::new().temperature(0.2).max_tokens(256);
6//! assert!(!patch.is_empty());
7//! ```
8
9use std::sync::Arc;
10
11use rig_core::completion::Document;
12use rig_core::message::{Message, ToolChoice};
13use serde::{Deserialize, Serialize};
14
15/// A non-sticky patch applied only to the current turn's completion request.
16///
17/// A driver's hook stack merges patches in hook registration order according to these
18/// rules:
19///
20/// - `extra_context` documents are appended in order.
21/// - JSON-object `additional_params` values are shallow-merged, with later
22///   top-level keys winning; a later non-object value replaces an earlier value.
23/// - `active_tools` allow-lists are intersected.
24/// - Scalar fields and `history` use last-writer-wins semantics, with a warning
25///   when multiple hooks set the same field.
26///
27/// The merged patch does not mutate the agent's configured baseline and is not
28/// carried into subsequent turns.
29#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
30pub struct RequestPatch {
31    /// Preamble to use instead of the agent's configured preamble for this turn.
32    pub preamble: Option<String>,
33    /// Sampling temperature to use for this turn.
34    pub temperature: Option<f64>,
35    /// Maximum output-token count to use for this turn.
36    pub max_tokens: Option<u64>,
37    /// Tool-choice policy to use for this turn.
38    pub tool_choice: Option<ToolChoice>,
39    /// Allow-list used to narrow the tools advertised for this turn.
40    pub active_tools: Option<Vec<String>>,
41    /// Provider-specific request parameters to apply for this turn.
42    pub additional_params: Option<serde_json::Value>,
43    /// Context documents appended to the request for this turn.
44    pub extra_context: Vec<Document>,
45    /// Conversation history to use instead of the current history for this turn.
46    pub history: Option<Vec<Arc<Message>>>,
47}
48
49fn merge_last_wins<T>(earlier: Option<T>, later: Option<T>, field: &str) -> Option<T> {
50    match (earlier, later) {
51        (Some(_), Some(later)) => {
52            tracing::warn!(
53                patch_field = field,
54                "two hooks set the same request field; later wins"
55            );
56            Some(later)
57        }
58        (earlier, later) => later.or(earlier),
59    }
60}
61
62impl RequestPatch {
63    /// Creates an empty request patch.
64    pub fn new() -> Self {
65        Self::default()
66    }
67
68    /// Replaces the agent's configured preamble for this turn.
69    pub fn preamble(mut self, value: impl Into<String>) -> Self {
70        self.preamble = Some(value.into());
71        self
72    }
73
74    /// Sets the sampling temperature for this turn.
75    pub fn temperature(mut self, value: f64) -> Self {
76        self.temperature = Some(value);
77        self
78    }
79
80    /// Sets the maximum output-token count for this turn.
81    pub fn max_tokens(mut self, value: u64) -> Self {
82        self.max_tokens = Some(value);
83        self
84    }
85
86    /// Sets the tool-choice policy for this turn.
87    pub fn tool_choice(mut self, value: ToolChoice) -> Self {
88        self.tool_choice = Some(value);
89        self
90    }
91
92    /// Sets the allow-list used to narrow the tools advertised for this turn.
93    pub fn active_tools<I, S>(mut self, values: I) -> Self
94    where
95        I: IntoIterator<Item = S>,
96        S: Into<String>,
97    {
98        self.active_tools = Some(values.into_iter().map(Into::into).collect());
99        self
100    }
101
102    /// Sets provider-specific request parameters for this turn.
103    ///
104    /// When multiple patches provide JSON objects, their top-level keys are
105    /// shallow-merged and values from later hooks win.
106    pub fn additional_params(mut self, value: serde_json::Value) -> Self {
107        self.additional_params = Some(value);
108        self
109    }
110
111    /// Appends context documents to the request for this turn.
112    pub fn extra_context<I>(mut self, values: I) -> Self
113    where
114        I: IntoIterator<Item = Document>,
115    {
116        self.extra_context.extend(values);
117        self
118    }
119
120    /// Appends one context document to the request for this turn.
121    pub fn context(mut self, value: Document) -> Self {
122        self.extra_context.push(value);
123        self
124    }
125
126    /// Replaces the conversation history for this turn.
127    pub fn history<I>(mut self, values: I) -> Self
128    where
129        I: IntoIterator<Item: Into<Arc<Message>>>,
130    {
131        self.history = Some(values.into_iter().map(Into::into).collect());
132        self
133    }
134
135    /// Whether the patch sets nothing at all.
136    pub fn is_empty(&self) -> bool {
137        self.preamble.is_none()
138            && self.temperature.is_none()
139            && self.max_tokens.is_none()
140            && self.tool_choice.is_none()
141            && self.active_tools.is_none()
142            && self.additional_params.is_none()
143            && self.extra_context.is_empty()
144            && self.history.is_none()
145    }
146
147    /// Merge a later patch over this one under the rules documented on the
148    /// type: `extra_context` appends, object `additional_params` shallow-merge
149    /// (later keys win), `active_tools` intersect, scalars and `history` take
150    /// the later value (with a warning when both are set).
151    pub fn merge(mut self, later: Self) -> Self {
152        self.extra_context.extend(later.extra_context);
153        self.additional_params = match (self.additional_params.take(), later.additional_params) {
154            (Some(base), Some(patch)) if base.is_object() && patch.is_object() => {
155                Some(rig_core::json_utils::merge(base, patch))
156            }
157            (base, patch) => patch.or(base),
158        };
159        self.preamble = merge_last_wins(self.preamble, later.preamble, "preamble");
160        self.temperature = merge_last_wins(self.temperature, later.temperature, "temperature");
161        self.max_tokens = merge_last_wins(self.max_tokens, later.max_tokens, "max_tokens");
162        self.tool_choice = merge_last_wins(self.tool_choice, later.tool_choice, "tool_choice");
163        self.history = merge_last_wins(self.history, later.history, "history");
164        self.active_tools = match (self.active_tools.take(), later.active_tools) {
165            (Some(earlier), Some(later)) => {
166                let later: std::collections::BTreeSet<_> = later.iter().collect();
167                Some(
168                    earlier
169                        .into_iter()
170                        .filter(|name| later.contains(name))
171                        .collect(),
172                )
173            }
174            (earlier, later) => earlier.or(later),
175        };
176        self
177    }
178}
179
180#[cfg(test)]
181mod tests;