pipecrab_core/frame/

model.rs

//! Native language-model protocol frames: one generation's boundaries and the
//! structured items it consumes or produces. See [`ModelFrame`] for the
//! ordering contract.

use std::sync::Arc;

/// A complete tool call emitted by a language model. Only *complete* calls enter
/// the pipeline: an adapter assembles provider-specific fragments into one
/// [`arguments_json`](ToolCall::arguments_json), synthesizes an [`id`](ToolCall::id)
/// where the provider has none, and owns all JSON validation — core does none.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ToolCall {
    /// Correlates the call with a later tool result.
    pub id: Arc<str>,
    /// Model-facing tool name.
    pub name: Arc<str>,
    /// Complete tool arguments as one JSON object; never a fragment.
    pub arguments_json: Arc<str>,
}

/// Non-user input to the LM conversation — from another stage or external
/// system. User speech stays a final [`Role::User`](crate::Role::User)
/// [`Transcript`](crate::Transcript) and assistant messages are built
/// internally, so v1 has no `User` or `Assistant` variant.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ModelMessage {
    /// The result corresponding to a previous model [`ToolCall`], correlated by
    /// `tool_call_id`.
    ToolResult {
        /// The [`ToolCall::id`] this result answers.
        tool_call_id: Arc<str>,
        /// Model-facing name of the tool that produced the result.
        name: Arc<str>,
        /// The tool's output, as text.
        content: Arc<str>,
    },
    /// An event generated by another system rather than the user.
    Event {
        /// Identifier of the system that produced the event.
        source: Arc<str>,
        /// The kind of event, in the producer's own vocabulary.
        kind: Arc<str>,
        /// The event payload, as text.
        content: Arc<str>,
    },
}

/// Non-user input to an LM stage, tagged with whether it triggers a generation.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ModelInput {
    /// Add the message to conversation history without generating.
    Context(ModelMessage),
    /// Add the message and begin a new generation.
    Respond(ModelMessage),
}

/// Native language-model protocol frames: one generation's boundaries and the
/// structured items it consumes or produces. On the data lane the exact
/// interleaving is preserved:
///
/// ```text
/// Model(GenerationStarted)
/// Transcript(agent partial)
/// Model(ToolCall)
/// Transcript(agent final)
/// Model(GenerationFinished)
/// ```
///
/// Text may come *before or after* a tool call, and a tool-call-only generation
/// emits no transcript — so don't assume text precedes tool calls. No generation
/// id in v1: a stage runs one at a time, bounded by
/// [`GenerationStarted`](ModelFrame::GenerationStarted) /
/// [`GenerationFinished`](ModelFrame::GenerationFinished).
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ModelFrame {
    /// Add non-user information to the LM conversation; see [`ModelInput`].
    Input(ModelInput),
    /// Marks the beginning of one LM generation.
    GenerationStarted,
    /// A complete structured [`ToolCall`] emitted by the model.
    ToolCall(ToolCall),
    /// Marks successful completion of the generation stream.
    GenerationFinished,
}

impl ModelFrame {
    /// Model frames that outlive an interrupt flush: [`Input`](ModelFrame::Input)
    /// (external input) and [`ToolCall`](ModelFrame::ToolCall) (a completed call).
    /// The generation boundaries belong to the interrupted turn and are dropped.
    /// Consulted by [`DataFrame::survives_flush`](crate::DataFrame::survives_flush).
    pub fn survives_flush(&self) -> bool {
        matches!(self, ModelFrame::Input(_) | ModelFrame::ToolCall(_))
    }
}

impl From<ToolCall> for ModelFrame {
    /// Wrap a complete [`ToolCall`] as [`ModelFrame::ToolCall`].
    fn from(call: ToolCall) -> Self {
        ModelFrame::ToolCall(call)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::DataFrame;

    fn call() -> ToolCall {
        ToolCall {
            id: Arc::from("call-1"),
            name: Arc::from("lookup"),
            arguments_json: Arc::from(r#"{"q":"weather"}"#),
        }
    }

    #[test]
    fn subtypes_construct_and_compare() {
        // Equal field-for-field; distinct when any field differs.
        assert_eq!(call(), call());
        assert_ne!(
            call(),
            ToolCall {
                name: Arc::from("other"),
                ..call()
            }
        );

        let ctx = ModelInput::Context(ModelMessage::Event {
            source: Arc::from("clock"),
            kind: Arc::from("tick"),
            content: Arc::from("12:00"),
        });
        assert_eq!(ctx.clone(), ctx);
        // Context and Respond wrapping the same message are distinct.
        let respond = match &ctx {
            ModelInput::Context(m) => ModelInput::Respond(m.clone()),
            ModelInput::Respond(m) => ModelInput::Context(m.clone()),
        };
        assert_ne!(ctx, respond);

        let result = ModelMessage::ToolResult {
            tool_call_id: Arc::from("call-1"),
            name: Arc::from("lookup"),
            content: Arc::from("sunny"),
        };
        assert_eq!(result.clone(), result);
    }

    #[test]
    fn tool_call_holds_complete_argument_json_verbatim() {
        // Core stores whatever complete JSON text the adapter assembled; it does
        // not parse, split, or re-encode it.
        let json = r#"{"city":"paris","units":"c"}"#;
        let c = ToolCall {
            id: Arc::from("call-9"),
            name: Arc::from("weather"),
            arguments_json: Arc::from(json),
        };
        assert_eq!(&*c.arguments_json, json);
    }

    #[test]
    fn tool_call_converts_to_model_frame_and_data_frame() {
        assert_eq!(ModelFrame::from(call()), ModelFrame::ToolCall(call()));

        // ToolCall reaches the data lane as a Model frame, not a Custom one.
        match DataFrame::from(call()) {
            DataFrame::Model(ModelFrame::ToolCall(c)) => assert_eq!(c, call()),
            other => panic!("expected Model(ToolCall), got {other:?}"),
        }
    }

    #[test]
    fn model_frame_rides_the_data_lane() {
        // The only home for a ModelFrame is DataFrame::Model — it is never a
        // SystemFrame (there is no such variant to construct).
        match DataFrame::from(ModelFrame::GenerationStarted) {
            DataFrame::Model(ModelFrame::GenerationStarted) => {}
            other => panic!("expected Model(GenerationStarted), got {other:?}"),
        }
    }

    #[test]
    fn survival_matches_the_interrupt_contract() {
        // Survive: external input and completed tool calls.
        assert!(
            ModelFrame::Input(ModelInput::Respond(ModelMessage::Event {
                source: Arc::from("cal"),
                kind: Arc::from("reminder"),
                content: Arc::from("standup"),
            }))
            .survives_flush()
        );
        assert!(ModelFrame::ToolCall(call()).survives_flush());

        // Do not survive: in-progress generation bookkeeping.
        assert!(!ModelFrame::GenerationStarted.survives_flush());
        assert!(!ModelFrame::GenerationFinished.survives_flush());

        // The same decision through the data-lane entry point.
        assert!(DataFrame::from(call()).survives_flush());
        assert!(!DataFrame::from(ModelFrame::GenerationFinished).survives_flush());
    }
}