veerdiff 0.1.0

Semantic diff engine for LLM and agent execution traces — find exactly where two runs veer apart.
Documentation
//! The normalized trace model.
//!
//! Every supported input format (OpenAI, Anthropic, the native `veer` format,
//! …) is converted into a [`Trace`]: a flat, ordered sequence of [`Step`]s.
//! Diffing always operates on this normalized representation, which is what lets
//! `veer` compare runs recorded by different SDKs on equal footing.

use serde::{Deserialize, Serialize};
use serde_json::Value;

/// A JSON object map. Uses insertion-order preservation (via the
/// `preserve_order` feature of `serde_json`) so round-tripping a trace does not
/// reshuffle keys.
pub type Map = serde_json::Map<String, Value>;

/// A complete execution trace: an ordered list of steps plus optional
/// trace-level metadata.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Trace {
    /// Ordered steps that make up the run.
    #[serde(default)]
    pub steps: Vec<Step>,
    /// Arbitrary trace-level metadata (model name, run id, timings, …).
    ///
    /// Metadata never participates in alignment; it is carried for reporting
    /// and can be selectively masked by normalizers.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub meta: Map,
}

/// The category of a step. Alignment treats steps of different kinds as
/// fundamentally dissimilar, so getting the kind right during import matters.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StepKind {
    /// A chat message (system / user / assistant prose).
    Message,
    /// A model-issued call to a tool or function.
    ToolCall,
    /// The result returned to the model from a tool.
    ToolResult,
    /// A structured event that does not fit the categories above.
    Event,
    /// An unrecognized kind, preserved verbatim from the source.
    #[serde(untagged)]
    Other(String),
}

impl StepKind {
    /// A short, stable tag used in reports and structural comparison.
    pub fn tag(&self) -> &str {
        match self {
            StepKind::Message => "message",
            StepKind::ToolCall => "tool_call",
            StepKind::ToolResult => "tool_result",
            StepKind::Event => "event",
            StepKind::Other(s) => s,
        }
    }
}

/// A single step in a trace.
///
/// A step is intentionally a *superset* of what any one format needs: a chat
/// message populates [`role`](Step::role) and [`content`](Step::content); a tool
/// call populates [`name`](Step::name) and [`args`](Step::args); a tool result
/// populates [`name`](Step::name) and [`content`](Step::content). Unmapped
/// source fields are preserved in [`meta`](Step::meta).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Step {
    /// What kind of step this is.
    pub kind: StepKind,
    /// The actor, e.g. `system`, `user`, `assistant`, `tool`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub role: Option<String>,
    /// A name identifying the step, e.g. the tool or function being called.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Free-text content (message body, tool output rendered as text).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
    /// Structured arguments (tool-call input, structured tool output).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub args: Option<Value>,
    /// Source fields that do not map onto a first-class slot (ids, timestamps,
    /// token counts, …). Prime target for masking normalizers.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub meta: Map,
}

impl Step {
    /// Create a bare step of the given kind.
    pub fn new(kind: StepKind) -> Self {
        Step {
            kind,
            role: None,
            name: None,
            content: None,
            args: None,
            meta: Map::new(),
        }
    }

    /// Builder: set the role.
    pub fn with_role(mut self, role: impl Into<String>) -> Self {
        self.role = Some(role.into());
        self
    }

    /// Builder: set the name.
    pub fn with_name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// Builder: set the text content.
    pub fn with_content(mut self, content: impl Into<String>) -> Self {
        self.content = Some(content.into());
        self
    }

    /// Builder: set structured args.
    pub fn with_args(mut self, args: Value) -> Self {
        self.args = Some(args);
        self
    }

    /// A compact single-line label for reports, e.g. `tool_call get_weather`.
    pub fn label(&self) -> String {
        let mut s = self.kind.tag().to_string();
        if let Some(role) = &self.role {
            s.push(' ');
            s.push_str(role);
        }
        if let Some(name) = &self.name {
            s.push_str(" ·");
            s.push(' ');
            s.push_str(name);
        }
        s
    }
}

impl Trace {
    /// Create an empty trace.
    pub fn new() -> Self {
        Trace::default()
    }

    /// Create a trace from a list of steps.
    pub fn from_steps(steps: Vec<Step>) -> Self {
        Trace {
            steps,
            meta: Map::new(),
        }
    }

    /// Number of steps in the trace.
    pub fn len(&self) -> usize {
        self.steps.len()
    }

    /// Whether the trace has no steps.
    pub fn is_empty(&self) -> bool {
        self.steps.is_empty()
    }
}

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

    #[test]
    fn step_label_includes_kind_role_and_name() {
        let step = Step::new(StepKind::ToolCall).with_name("get_weather");
        assert_eq!(step.label(), "tool_call · get_weather");

        let msg = Step::new(StepKind::Message).with_role("assistant");
        assert_eq!(msg.label(), "message assistant");
    }

    #[test]
    fn kind_roundtrips_through_json_including_other() {
        for kind in [
            StepKind::Message,
            StepKind::ToolCall,
            StepKind::ToolResult,
            StepKind::Event,
            StepKind::Other("reasoning".into()),
        ] {
            let json = serde_json::to_string(&kind).unwrap();
            let back: StepKind = serde_json::from_str(&json).unwrap();
            assert_eq!(kind, back);
        }
    }

    #[test]
    fn other_kind_tag_is_the_inner_string() {
        assert_eq!(StepKind::Other("reasoning".into()).tag(), "reasoning");
    }
}