reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
//! Consumed Agent configuration and immutable revision metadata.

use std::fmt::{self, Debug, Formatter};
use std::num::NonZeroU64;
use std::sync::Arc;

use crate::opaque::Envelope;
use crate::runtime::hook;
use crate::runtime::model::{Client, SamplingParams};
use crate::runtime::tool;
use crate::value::content::Part;

/// Mutable owned assembly consumed into one immutable Agent revision.
///
/// Everything an Agent will hold is gathered here and then frozen: the model
/// client, the tools, the hooks, and the default request material every Step
/// starts from. [`Agent::new`](super::Agent::new) consumes it.
///
/// ```
/// # use std::future::{Future, ready};
/// # use std::pin::Pin;
/// # use std::sync::Arc;
/// # use std::task::{Context, Poll};
/// # use reef_core::futures_core::Stream;
/// # use reef_core::runtime::model;
/// # #[derive(Debug)] struct Offline;
/// # #[derive(Debug)] struct Once(bool);
/// # impl Stream for Once {
/// #     type Item = Result<model::Event, std::convert::Infallible>;
/// #     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
/// #         if std::mem::replace(&mut self.0, true) { return Poll::Ready(None); }
/// #         Poll::Ready(Some(Ok(model::Event::Done { finish_reason: "stop".to_owned(), completion: model::CompletionReason::Stop, provider_data: Vec::new() })))
/// #     }
/// # }
/// # impl model::Client for Offline {
/// #     type Error = std::convert::Infallible;
/// #     type Stream = Once;
/// #     fn info(&self) -> model::Info { model::Info::new("offline".to_owned(), 8_192) }
/// #     fn generate(&self, _: model::Request) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send { ready(Ok(Once(false))) }
/// # }
/// use reef_core::runtime::{agent, hook, tool};
/// use reef_core::value::content;
///
/// let tools = tool::RegistryBuilder::new().build().unwrap();
/// let hooks = hook::RegistryBuilder::new();
///
/// let mut config = agent::Config::new(Arc::new(Offline), tools, hooks);
/// config.push_system_instruction(content::Part::text("Be terse.".to_owned()));
/// config.sampling_mut().temperature = Some(0.2);
///
/// assert_eq!(config.system_instruction().len(), 1);
/// let agent = agent::Agent::new(config).unwrap();
/// # let _ = agent;
/// ```
pub struct Config<M: Client> {
    pub(super) model: Arc<M>,
    pub(super) tools: tool::Registry,
    pub(super) hooks: hook::RegistryBuilder,
    pub(super) system_instruction: Vec<Part>,
    pub(super) sampling: SamplingParams,
    pub(super) model_extensions: Vec<Envelope>,
}

impl<M: Client> Debug for Config<M> {
    /// Shows everything a revision will freeze except the model itself.
    ///
    /// `M` carries no `Debug` bound, because requiring one would make an Agent
    /// unprintable for every provider that has not opted in — a cost paid by
    /// users to describe the one field they already know, since they supplied
    /// it. The trailing `..` says so rather than pretending the field is absent.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Config")
            .field("tools", &self.tools)
            .field("hooks", &self.hooks)
            .field("system_instruction", &self.system_instruction)
            .field("sampling", &self.sampling)
            .field("model_extensions", &self.model_extensions)
            .finish_non_exhaustive()
    }
}

impl<M: Client> Config<M> {
    /// Creates a configuration with empty, provider-neutral defaults.
    ///
    /// # Why the two registries arrive in different states
    ///
    /// `tools` is a built [`tool::Registry`] and `hooks` is still a
    /// [`hook::RegistryBuilder`]. A tool registry is an immutable value: it is
    /// `Clone`, it holds no authority, and several agents may share one. The hook
    /// builder is instead consumed here so [`Agent::new`](super::Agent::new) can
    /// build exactly one Agent-private runtime registry from it. Nothing reachable
    /// from [`Config`], [`Agent`](super::Agent), [`Revision`](super::Revision), or
    /// a [`Run`](crate::runtime::run::Run) hands that registry back, which makes
    /// [`Agent::close`](super::Agent::close) its only teardown route.
    #[must_use]
    pub fn new(model: Arc<M>, tools: tool::Registry, hooks: hook::RegistryBuilder) -> Self {
        Self {
            model,
            tools,
            hooks,
            system_instruction: Vec::new(),
            sampling: SamplingParams::default(),
            model_extensions: Vec::new(),
        }
    }

    /// Returns the ordered default system instruction.
    #[must_use]
    pub fn system_instruction(&self) -> &[Part] {
        &self.system_instruction
    }

    /// Appends one block to the default system instruction.
    pub fn push_system_instruction(&mut self, part: Part) -> &mut Self {
        self.system_instruction.push(part);
        self
    }

    /// Appends blocks to the default system instruction in iteration order.
    pub fn extend_system_instruction(
        &mut self,
        parts: impl IntoIterator<Item = Part>,
    ) -> &mut Self {
        self.system_instruction.extend(parts);
        self
    }

    /// Removes every default system-instruction block.
    pub fn clear_system_instruction(&mut self) -> &mut Self {
        self.system_instruction.clear();
        self
    }

    /// Returns the default sampling controls.
    pub const fn sampling_mut(&mut self) -> &mut SamplingParams {
        &mut self.sampling
    }

    /// Returns the default provider-hosted extension lane.
    #[must_use]
    pub fn model_extensions(&self) -> &[Envelope] {
        &self.model_extensions
    }

    /// Appends one provider-hosted extension.
    pub fn push_model_extension(&mut self, extension: Envelope) -> &mut Self {
        self.model_extensions.push(extension);
        self
    }

    /// Appends provider-hosted extensions in iteration order.
    pub fn extend_model_extensions(
        &mut self,
        extensions: impl IntoIterator<Item = Envelope>,
    ) -> &mut Self {
        self.model_extensions.extend(extensions);
        self
    }

    /// Removes every provider-hosted extension.
    pub fn clear_model_extensions(&mut self) -> &mut Self {
        self.model_extensions.clear();
        self
    }
}

/// Owned immutable configuration snapshot identified within this process.
///
/// This is the unit that a Run freezes, and the exact extent of the rule that
/// configuration does not change inside a Run: the model client, the tool
/// registry *including its provider roster*, the hook roster, and the default
/// system instruction, sampling params and model extensions.
/// Changing any of them means stopping the Run, waiting for the Session lease
/// to be released, and starting a successor Run with a new revision.
///
/// It is **not** a claim that everything downstream of those bindings is
/// constant. Two things a revision deliberately leaves free:
///
/// - **The resolved tool set.**
///   [`tool::Provider::resolve`](crate::runtime::tool::Provider::resolve) runs
///   once per Step, so the exposed tools may differ at every Step of one Run.
///   The roster is frozen; the resolution is a per-Step observation of it. A
///   proposal to relax Run granularity so that the tool set can vary is
///   therefore answering a problem that does not exist.
/// - **The request.** System instruction, sampling params and extensions are
///   *defaults* seeded into each Step's
///   [`RequestPlan`](crate::runtime::model::RequestPlan);
///   [`ModelHooks::before_model`](crate::runtime::hook::ModelHooks::before_model)
///   and the plan's own mutators adjust this one request without touching the
///   binding. Anything that needs to change per Turn is request content, not
///   configuration, and almost every proposal to make configuration mutable is
///   really this.
pub struct Revision<M: Client> {
    pub(super) id: NonZeroU64,
    pub(super) model: Arc<M>,
    pub(super) tools: tool::Registry,
    pub(super) hook_names: Arc<[String]>,
    pub(super) hooks_require_session_state: bool,
    pub(super) system_instruction: Arc<[Part]>,
    pub(super) sampling: SamplingParams,
    pub(super) model_extensions: Arc<[Envelope]>,
}

impl<M: Client> Debug for Revision<M> {
    /// Shows the frozen configuration, identified by its revision number.
    ///
    /// As with [`Config`], the model is the one field left out: `M` has no
    /// `Debug` bound, and the trailing `..` records the omission.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Revision")
            .field("id", &self.id)
            .field("tools", &self.tools)
            .field("hook_names", &self.hook_names)
            .field(
                "hooks_require_session_state",
                &self.hooks_require_session_state,
            )
            .field("system_instruction", &self.system_instruction)
            .field("sampling", &self.sampling)
            .field("model_extensions", &self.model_extensions)
            .finish_non_exhaustive()
    }
}

impl<M: Client> Clone for Revision<M> {
    fn clone(&self) -> Self {
        Self {
            id: self.id,
            model: Arc::clone(&self.model),
            tools: self.tools.clone(),
            hook_names: Arc::clone(&self.hook_names),
            hooks_require_session_state: self.hooks_require_session_state,
            system_instruction: Arc::clone(&self.system_instruction),
            sampling: self.sampling.clone(),
            model_extensions: Arc::clone(&self.model_extensions),
        }
    }
}

impl<M: Client> Revision<M> {
    /// Returns the process-monotonic nonzero revision identity.
    #[must_use]
    pub const fn id(&self) -> NonZeroU64 {
        self.id
    }

    /// Returns the shared model implementation.
    #[must_use]
    pub const fn model(&self) -> &Arc<M> {
        &self.model
    }

    /// Returns the immutable tool registry.
    #[must_use]
    pub const fn tools(&self) -> &tool::Registry {
        &self.tools
    }

    /// Returns close-free hook names in registration order.
    #[must_use]
    pub fn hook_names(&self) -> &[String] {
        &self.hook_names
    }

    /// Reports whether any hook declared Session-state access.
    #[must_use]
    pub const fn hooks_require_session_state(&self) -> bool {
        self.hooks_require_session_state
    }

    /// Returns the frozen default system instruction.
    #[must_use]
    pub fn system_instruction(&self) -> &[Part] {
        &self.system_instruction
    }

    /// Returns the frozen sampling controls.
    #[must_use]
    pub const fn sampling(&self) -> &SamplingParams {
        &self.sampling
    }

    /// Returns the frozen provider-hosted extensions.
    #[must_use]
    pub fn model_extensions(&self) -> &[Envelope] {
        &self.model_extensions
    }
}