Skip to main content

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}