xz-agent-core 0.10.0

use std::future::Future;

use crate::error::EngineError;

/// Context builder — prepares context before each thinking turn.
///
/// Multiple context builders can be chained: each receives the output of the
/// previous one and can modify it before passing it to the next.
/// The context type is abstract — the engine never inspects its contents.
///
/// # Example
///
/// ```rust
/// use xz_agent_core::traits::context::ContextBuilder;
/// use xz_agent_core::error::EngineError;
///
/// struct AppendHello;
///
/// impl ContextBuilder for AppendHello {
///     type Context = String;
///     async fn build(&self, mut ctx: Self::Context) -> Result<Self::Context, EngineError> {
///         ctx.push_str(" hello");
///         Ok(ctx)
///     }
/// }
/// ```
pub trait ContextBuilder: Send + Sync {
    /// The type of context this builder operates on.
    type Context;
    /// Build/modify the context.
    ///
    /// Takes ownership of the previous context and returns a (possibly
    /// modified) context.
    fn build(
        &self,
        ctx: Self::Context,
    ) -> impl Future<Output = Result<Self::Context, EngineError>> + Send;
}