Expand description
§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);Re-exports§
pub use align::Diff;pub use align::Op;pub use align::Stats;pub use config::Config;pub use error::Error;pub use error::Result;pub use model::Step;pub use model::StepKind;pub use model::Trace;
Modules§
- align
- Alignment: the core diff algorithm.
- config
- Runtime configuration for a diff: how to normalize, how to weight fields, and where the thresholds sit.
- error
- Error types for the
veerlibrary. - import
- Importers that turn provider-specific trace dumps into the normalized
Tracemodel. - model
- The normalized trace model.
- normalize
- Normalization: deterministic transformations applied to a
Tracebefore it is diffed. - report
- Rendering a
Difffor humans and machines. - similarity
- Similarity metrics used to score how alike two steps (or two JSON values)
are. Alignment turns these
[0, 1]scores into edit costs.
Functions§
- diff
- Diff two traces, applying the configuration’s normalization first.
- diff_
normalized - Normalize two traces in place and diff them, returning the diff alongside the
normalized traces (handy for rendering with
report).