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
62/// Overlay `later` additional parameters on `base`: two JSON objects
63/// shallow-merge with later keys winning; otherwise `later` replaces `base`.
64pub(crate) fn overlay_params(
65    base: Option<serde_json::Value>,
66    later: Option<serde_json::Value>,
67) -> Option<serde_json::Value> {
68    match (base, later) {
69        (Some(base), Some(later)) if base.is_object() && later.is_object() => {
70            Some(rig_core::json_utils::merge(base, later))
71        }
72        (base, later) => later.or(base),
73    }
74}
75
76impl RequestPatch {
77    /// Creates an empty request patch.
78    pub fn new() -> Self {
79        Self::default()
80    }
81
82    /// Replaces the agent's configured preamble for this turn.
83    pub fn preamble(mut self, value: impl Into<String>) -> Self {
84        self.preamble = Some(value.into());
85        self
86    }
87
88    /// Sets the sampling temperature for this turn.
89    pub fn temperature(mut self, value: f64) -> Self {
90        self.temperature = Some(value);
91        self
92    }
93
94    /// Sets the maximum output-token count for this turn.
95    pub fn max_tokens(mut self, value: u64) -> Self {
96        self.max_tokens = Some(value);
97        self
98    }
99
100    /// Sets the tool-choice policy for this turn.
101    pub fn tool_choice(mut self, value: ToolChoice) -> Self {
102        self.tool_choice = Some(value);
103        self
104    }
105
106    /// Sets the allow-list used to narrow the tools advertised for this turn.
107    pub fn active_tools<I, S>(mut self, values: I) -> Self
108    where
109        I: IntoIterator<Item = S>,
110        S: Into<String>,
111    {
112        self.active_tools = Some(values.into_iter().map(Into::into).collect());
113        self
114    }
115
116    /// Sets provider-specific request parameters for this turn.
117    ///
118    /// When multiple patches provide JSON objects, their top-level keys are
119    /// shallow-merged and values from later hooks win.
120    pub fn additional_params(mut self, value: serde_json::Value) -> Self {
121        self.additional_params = Some(value);
122        self
123    }
124
125    /// Appends context documents to the request for this turn.
126    pub fn extra_context<I>(mut self, values: I) -> Self
127    where
128        I: IntoIterator<Item = Document>,
129    {
130        self.extra_context.extend(values);
131        self
132    }
133
134    /// Appends one context document to the request for this turn.
135    pub fn context(mut self, value: Document) -> Self {
136        self.extra_context.push(value);
137        self
138    }
139
140    /// Replaces the conversation history for this turn.
141    pub fn history<I>(mut self, values: I) -> Self
142    where
143        I: IntoIterator<Item: Into<Arc<Message>>>,
144    {
145        self.history = Some(values.into_iter().map(Into::into).collect());
146        self
147    }
148
149    /// Whether the patch sets nothing at all.
150    pub fn is_empty(&self) -> bool {
151        *self == Self::default()
152    }
153
154    /// Merge a later patch over this one under the rules documented on the
155    /// type: `extra_context` appends, object `additional_params` shallow-merge
156    /// (later keys win), `active_tools` intersect, scalars and `history` take
157    /// the later value (with a warning when both are set).
158    pub fn merge(mut self, later: Self) -> Self {
159        self.extra_context.extend(later.extra_context);
160        self.additional_params =
161            overlay_params(self.additional_params.take(), later.additional_params);
162        self.preamble = merge_last_wins(self.preamble, later.preamble, "preamble");
163        self.temperature = merge_last_wins(self.temperature, later.temperature, "temperature");
164        self.max_tokens = merge_last_wins(self.max_tokens, later.max_tokens, "max_tokens");
165        self.tool_choice = merge_last_wins(self.tool_choice, later.tool_choice, "tool_choice");
166        self.history = merge_last_wins(self.history, later.history, "history");
167        self.active_tools = match (self.active_tools.take(), later.active_tools) {
168            (Some(earlier), Some(later)) => {
169                let later: std::collections::BTreeSet<_> = later.iter().collect();
170                Some(
171                    earlier
172                        .into_iter()
173                        .filter(|name| later.contains(name))
174                        .collect(),
175                )
176            }
177            (earlier, later) => earlier.or(later),
178        };
179        self
180    }
181}
182
183#[cfg(test)]
184mod tests;