veerdiff 0.1.0

Semantic diff engine for LLM and agent execution traces — find exactly where two runs veer apart.
Documentation
//! # veer
//!
//! A semantic diff engine for LLM and agent execution traces — *find exactly
//! where two runs veer apart*.
//!
//! Ordinary text diffs are useless on agent traces: request ids and timestamps
//! churn, JSON keys come back in a different order, and "the same" step is
//! rarely byte-identical between runs. `veer` imports traces from several
//! formats into a normalized [`model::Trace`], strips incidental noise with a
//! configurable [`normalize::Normalizer`], and then *aligns* the two runs with
//! an edit-distance dynamic program whose substitution cost is a semantic
//! similarity score. The result pinpoints the first meaningful divergence and
//! gives a field-level account of every change.
//!
//! ## Quick start
//!
//! ```
//! use veerdiff::{Config, diff};
//! use veerdiff::model::{Step, StepKind, Trace};
//! use serde_json::json;
//!
//! let before = Trace::from_steps(vec![
//!     Step::new(StepKind::ToolCall)
//!         .with_name("get_weather")
//!         .with_args(json!({"city": "Paris"})),
//! ]);
//! let after = Trace::from_steps(vec![
//!     Step::new(StepKind::ToolCall)
//!         .with_name("get_weather")
//!         .with_args(json!({"city": "Berlin"})),
//! ]);
//!
//! let d = diff(&before, &after, &Config::default());
//! assert_eq!(d.stats.changed, 1);
//! assert!(!d.is_identical());
//! ```
//!
//! ## Importing provider traces
//!
//! ```
//! use veerdiff::{Config, import, diff};
//!
//! let a = import::import_str(r#"[{"role":"user","content":"hi"}]"#, import::Format::Auto).unwrap();
//! let b = import::import_str(r#"[{"role":"user","content":"hi there"}]"#, import::Format::Auto).unwrap();
//! let d = diff(&a, &b, &Config::default());
//! assert_eq!(d.stats.changed, 1);
//! ```

#![forbid(unsafe_code)]

pub mod align;
pub mod config;
pub mod error;
pub mod import;
pub mod model;
pub mod normalize;
pub mod report;
pub mod similarity;

pub use align::{Diff, Op, Stats};
pub use config::Config;
pub use error::{Error, Result};
pub use model::{Step, StepKind, Trace};

/// Diff two traces, applying the configuration's normalization first.
///
/// This clones and normalizes both inputs, then aligns them. If you need the
/// normalized traces for rendering, normalize explicitly and call
/// [`align::align`] instead:
///
/// ```
/// use veerdiff::{Config, align, model::{Step, StepKind, Trace}};
///
/// let cfg = Config::default();
/// let mut a = Trace::from_steps(vec![Step::new(StepKind::Message).with_content("  hi ")]);
/// let mut b = Trace::from_steps(vec![Step::new(StepKind::Message).with_content("hi")]);
/// cfg.normalizer.apply(&mut a);
/// cfg.normalizer.apply(&mut b);
/// let d = align::align(&a, &b, &cfg);
/// assert!(d.is_identical()); // whitespace was normalized away
/// ```
pub fn diff(a: &Trace, b: &Trace, cfg: &Config) -> Diff {
    let mut a = a.clone();
    let mut b = b.clone();
    cfg.normalizer.apply(&mut a);
    cfg.normalizer.apply(&mut b);
    align::align(&a, &b, cfg)
}

/// Normalize two traces in place and diff them, returning the diff alongside the
/// normalized traces (handy for rendering with [`report`]).
pub fn diff_normalized(mut a: Trace, mut b: Trace, cfg: &Config) -> (Diff, Trace, Trace) {
    cfg.normalizer.apply(&mut a);
    cfg.normalizer.apply(&mut b);
    let d = align::align(&a, &b, cfg);
    (d, a, b)
}

#[cfg(test)]
mod tests {
    use super::*;
    use model::{Step, StepKind};

    #[test]
    fn end_to_end_whitespace_is_normalized() {
        let a = Trace::from_steps(vec![
            Step::new(StepKind::Message).with_content("hello  world"),
        ]);
        let b = Trace::from_steps(vec![
            Step::new(StepKind::Message).with_content("hello world"),
        ]);
        let cfg = Config {
            normalizer: normalize::Normalizer {
                collapse_whitespace: true,
                ..normalize::Normalizer::default()
            },
            ..Config::default()
        };
        let d = diff(&a, &b, &cfg);
        assert!(d.is_identical());
    }
}