reef_core/runtime/agent/config.rs
1//! Consumed Agent configuration and immutable revision metadata.
2
3use std::fmt::{self, Debug, Formatter};
4use std::num::NonZeroU64;
5use std::sync::Arc;
6
7use crate::opaque::Envelope;
8use crate::runtime::hook;
9use crate::runtime::model::{Client, SamplingParams};
10use crate::runtime::tool;
11use crate::value::content::Part;
12
13/// Mutable owned assembly consumed into one immutable Agent revision.
14///
15/// Everything an Agent will hold is gathered here and then frozen: the model
16/// client, the tools, the hooks, and the default request material every Step
17/// starts from. [`Agent::new`](super::Agent::new) consumes it.
18///
19/// ```
20/// # use std::future::{Future, ready};
21/// # use std::pin::Pin;
22/// # use std::sync::Arc;
23/// # use std::task::{Context, Poll};
24/// # use reef_core::futures_core::Stream;
25/// # use reef_core::runtime::model;
26/// # #[derive(Debug)] struct Offline;
27/// # #[derive(Debug)] struct Once(bool);
28/// # impl Stream for Once {
29/// # type Item = Result<model::Event, std::convert::Infallible>;
30/// # fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
31/// # if std::mem::replace(&mut self.0, true) { return Poll::Ready(None); }
32/// # Poll::Ready(Some(Ok(model::Event::Done { finish_reason: "stop".to_owned(), completion: model::CompletionReason::Stop, provider_data: Vec::new() })))
33/// # }
34/// # }
35/// # impl model::Client for Offline {
36/// # type Error = std::convert::Infallible;
37/// # type Stream = Once;
38/// # fn info(&self) -> model::Info { model::Info::new("offline".to_owned(), 8_192) }
39/// # fn generate(&self, _: model::Request) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send { ready(Ok(Once(false))) }
40/// # }
41/// use reef_core::runtime::{agent, hook, tool};
42/// use reef_core::value::content;
43///
44/// let tools = tool::RegistryBuilder::new().build().unwrap();
45/// let hooks = hook::RegistryBuilder::new();
46///
47/// let mut config = agent::Config::new(Arc::new(Offline), tools, hooks);
48/// config.push_system_instruction(content::Part::text("Be terse.".to_owned()));
49/// config.sampling_mut().temperature = Some(0.2);
50///
51/// assert_eq!(config.system_instruction().len(), 1);
52/// let agent = agent::Agent::new(config).unwrap();
53/// # let _ = agent;
54/// ```
55pub struct Config<M: Client> {
56 pub(super) model: Arc<M>,
57 pub(super) tools: tool::Registry,
58 pub(super) hooks: hook::RegistryBuilder,
59 pub(super) system_instruction: Vec<Part>,
60 pub(super) sampling: SamplingParams,
61 pub(super) model_extensions: Vec<Envelope>,
62}
63
64impl<M: Client> Debug for Config<M> {
65 /// Shows everything a revision will freeze except the model itself.
66 ///
67 /// `M` carries no `Debug` bound, because requiring one would make an Agent
68 /// unprintable for every provider that has not opted in — a cost paid by
69 /// users to describe the one field they already know, since they supplied
70 /// it. The trailing `..` says so rather than pretending the field is absent.
71 fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
72 formatter
73 .debug_struct("Config")
74 .field("tools", &self.tools)
75 .field("hooks", &self.hooks)
76 .field("system_instruction", &self.system_instruction)
77 .field("sampling", &self.sampling)
78 .field("model_extensions", &self.model_extensions)
79 .finish_non_exhaustive()
80 }
81}
82
83impl<M: Client> Config<M> {
84 /// Creates a configuration with empty, provider-neutral defaults.
85 ///
86 /// # Why the two registries arrive in different states
87 ///
88 /// `tools` is a built [`tool::Registry`] and `hooks` is still a
89 /// [`hook::RegistryBuilder`]. A tool registry is an immutable value: it is
90 /// `Clone`, it holds no authority, and several agents may share one. The hook
91 /// builder is instead consumed here so [`Agent::new`](super::Agent::new) can
92 /// build exactly one Agent-private runtime registry from it. Nothing reachable
93 /// from [`Config`], [`Agent`](super::Agent), [`Revision`](super::Revision), or
94 /// a [`Run`](crate::runtime::run::Run) hands that registry back, which makes
95 /// [`Agent::close`](super::Agent::close) its only teardown route.
96 #[must_use]
97 pub fn new(model: Arc<M>, tools: tool::Registry, hooks: hook::RegistryBuilder) -> Self {
98 Self {
99 model,
100 tools,
101 hooks,
102 system_instruction: Vec::new(),
103 sampling: SamplingParams::default(),
104 model_extensions: Vec::new(),
105 }
106 }
107
108 /// Returns the ordered default system instruction.
109 #[must_use]
110 pub fn system_instruction(&self) -> &[Part] {
111 &self.system_instruction
112 }
113
114 /// Appends one block to the default system instruction.
115 pub fn push_system_instruction(&mut self, part: Part) -> &mut Self {
116 self.system_instruction.push(part);
117 self
118 }
119
120 /// Appends blocks to the default system instruction in iteration order.
121 pub fn extend_system_instruction(
122 &mut self,
123 parts: impl IntoIterator<Item = Part>,
124 ) -> &mut Self {
125 self.system_instruction.extend(parts);
126 self
127 }
128
129 /// Removes every default system-instruction block.
130 pub fn clear_system_instruction(&mut self) -> &mut Self {
131 self.system_instruction.clear();
132 self
133 }
134
135 /// Returns the default sampling controls.
136 pub const fn sampling_mut(&mut self) -> &mut SamplingParams {
137 &mut self.sampling
138 }
139
140 /// Returns the default provider-hosted extension lane.
141 #[must_use]
142 pub fn model_extensions(&self) -> &[Envelope] {
143 &self.model_extensions
144 }
145
146 /// Appends one provider-hosted extension.
147 pub fn push_model_extension(&mut self, extension: Envelope) -> &mut Self {
148 self.model_extensions.push(extension);
149 self
150 }
151
152 /// Appends provider-hosted extensions in iteration order.
153 pub fn extend_model_extensions(
154 &mut self,
155 extensions: impl IntoIterator<Item = Envelope>,
156 ) -> &mut Self {
157 self.model_extensions.extend(extensions);
158 self
159 }
160
161 /// Removes every provider-hosted extension.
162 pub fn clear_model_extensions(&mut self) -> &mut Self {
163 self.model_extensions.clear();
164 self
165 }
166}
167
168/// Owned immutable configuration snapshot identified within this process.
169///
170/// This is the unit that a Run freezes, and the exact extent of the rule that
171/// configuration does not change inside a Run: the model client, the tool
172/// registry *including its provider roster*, the hook roster, and the default
173/// system instruction, sampling params and model extensions.
174/// Changing any of them means stopping the Run, waiting for the Session lease
175/// to be released, and starting a successor Run with a new revision.
176///
177/// It is **not** a claim that everything downstream of those bindings is
178/// constant. Two things a revision deliberately leaves free:
179///
180/// - **The resolved tool set.**
181/// [`tool::Provider::resolve`](crate::runtime::tool::Provider::resolve) runs
182/// once per Step, so the exposed tools may differ at every Step of one Run.
183/// The roster is frozen; the resolution is a per-Step observation of it. A
184/// proposal to relax Run granularity so that the tool set can vary is
185/// therefore answering a problem that does not exist.
186/// - **The request.** System instruction, sampling params and extensions are
187/// *defaults* seeded into each Step's
188/// [`RequestPlan`](crate::runtime::model::RequestPlan);
189/// [`ModelHooks::before_model`](crate::runtime::hook::ModelHooks::before_model)
190/// and the plan's own mutators adjust this one request without touching the
191/// binding. Anything that needs to change per Turn is request content, not
192/// configuration, and almost every proposal to make configuration mutable is
193/// really this.
194pub struct Revision<M: Client> {
195 pub(super) id: NonZeroU64,
196 pub(super) model: Arc<M>,
197 pub(super) tools: tool::Registry,
198 pub(super) hook_names: Arc<[String]>,
199 pub(super) hooks_require_session_state: bool,
200 pub(super) system_instruction: Arc<[Part]>,
201 pub(super) sampling: SamplingParams,
202 pub(super) model_extensions: Arc<[Envelope]>,
203}
204
205impl<M: Client> Debug for Revision<M> {
206 /// Shows the frozen configuration, identified by its revision number.
207 ///
208 /// As with [`Config`], the model is the one field left out: `M` has no
209 /// `Debug` bound, and the trailing `..` records the omission.
210 fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
211 formatter
212 .debug_struct("Revision")
213 .field("id", &self.id)
214 .field("tools", &self.tools)
215 .field("hook_names", &self.hook_names)
216 .field(
217 "hooks_require_session_state",
218 &self.hooks_require_session_state,
219 )
220 .field("system_instruction", &self.system_instruction)
221 .field("sampling", &self.sampling)
222 .field("model_extensions", &self.model_extensions)
223 .finish_non_exhaustive()
224 }
225}
226
227impl<M: Client> Clone for Revision<M> {
228 fn clone(&self) -> Self {
229 Self {
230 id: self.id,
231 model: Arc::clone(&self.model),
232 tools: self.tools.clone(),
233 hook_names: Arc::clone(&self.hook_names),
234 hooks_require_session_state: self.hooks_require_session_state,
235 system_instruction: Arc::clone(&self.system_instruction),
236 sampling: self.sampling.clone(),
237 model_extensions: Arc::clone(&self.model_extensions),
238 }
239 }
240}
241
242impl<M: Client> Revision<M> {
243 /// Returns the process-monotonic nonzero revision identity.
244 #[must_use]
245 pub const fn id(&self) -> NonZeroU64 {
246 self.id
247 }
248
249 /// Returns the shared model implementation.
250 #[must_use]
251 pub const fn model(&self) -> &Arc<M> {
252 &self.model
253 }
254
255 /// Returns the immutable tool registry.
256 #[must_use]
257 pub const fn tools(&self) -> &tool::Registry {
258 &self.tools
259 }
260
261 /// Returns close-free hook names in registration order.
262 #[must_use]
263 pub fn hook_names(&self) -> &[String] {
264 &self.hook_names
265 }
266
267 /// Reports whether any hook declared Session-state access.
268 #[must_use]
269 pub const fn hooks_require_session_state(&self) -> bool {
270 self.hooks_require_session_state
271 }
272
273 /// Returns the frozen default system instruction.
274 #[must_use]
275 pub fn system_instruction(&self) -> &[Part] {
276 &self.system_instruction
277 }
278
279 /// Returns the frozen sampling controls.
280 #[must_use]
281 pub const fn sampling(&self) -> &SamplingParams {
282 &self.sampling
283 }
284
285 /// Returns the frozen provider-hosted extensions.
286 #[must_use]
287 pub fn model_extensions(&self) -> &[Envelope] {
288 &self.model_extensions
289 }
290}