veerdiff 0.1.0

Semantic diff engine for LLM and agent execution traces — find exactly where two runs veer apart.
Documentation
//! Importers that turn provider-specific trace dumps into the normalized
//! [`Trace`] model.
//!
//! Supported inputs:
//!
//! * **`veer`** — the native schema ([`Trace`] as JSON, a bare array of
//!   [`Step`]s, or newline-delimited steps).
//! * **`openai`** — OpenAI chat-completions messages (an array, or a request
//!   body with a `messages` field). Assistant `tool_calls` become
//!   [`StepKind::ToolCall`]s; `role: "tool"` messages become
//!   [`StepKind::ToolResult`]s.
//! * **`anthropic`** — Anthropic Messages format, including `content` block
//!   arrays (`text`, `tool_use`, `tool_result`, `thinking`).
//!
//! [`Format::Auto`] sniffs the JSON shape and picks an importer.

use serde_json::Value;

use crate::error::{Error, Result};
use crate::model::{Step, StepKind, Trace};

/// A supported input format.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Format {
    /// Detect the format from the input shape.
    Auto,
    /// The native `veer` schema.
    Veer,
    /// OpenAI chat-completions messages.
    OpenAI,
    /// Anthropic Messages format.
    Anthropic,
}

impl Format {
    /// Parse a format name (`auto`, `veer`, `openai`, `anthropic`).
    pub fn parse(s: &str) -> Result<Format> {
        match s.to_ascii_lowercase().as_str() {
            "auto" => Ok(Format::Auto),
            "veer" | "native" => Ok(Format::Veer),
            "openai" | "oai" => Ok(Format::OpenAI),
            "anthropic" | "claude" => Ok(Format::Anthropic),
            other => Err(Error::Config(format!("unknown format `{other}`"))),
        }
    }

    /// The canonical name of the format.
    pub fn name(self) -> &'static str {
        match self {
            Format::Auto => "auto",
            Format::Veer => "veer",
            Format::OpenAI => "openai",
            Format::Anthropic => "anthropic",
        }
    }
}

/// Parse and import a trace from a string using the given format.
pub fn import_str(input: &str, format: Format) -> Result<Trace> {
    let value = parse_input(input)?;
    import_value(value, format)
}

/// Import a trace from an already-parsed JSON value.
pub fn import_value(value: Value, format: Format) -> Result<Trace> {
    let format = match format {
        Format::Auto => detect(&value),
        other => other,
    };
    match format {
        Format::Veer => import_native(value),
        Format::OpenAI => import_openai(&messages(&value)?),
        Format::Anthropic => import_anthropic(&messages(&value)?),
        Format::Auto => unreachable!("resolved above"),
    }
}

/// Determine the format of a value, falling back to OpenAI for message-shaped
/// input that is not clearly Anthropic or native.
pub fn detect(value: &Value) -> Format {
    if looks_native(value) {
        return Format::Veer;
    }
    if let Ok(msgs) = messages(value) {
        if looks_anthropic(&msgs) {
            return Format::Anthropic;
        }
        return Format::OpenAI;
    }
    // A lone object with no messages: treat as native (possibly empty).
    Format::Veer
}

/// Parse input as JSON, falling back to newline-delimited JSON.
fn parse_input(input: &str) -> Result<Value> {
    match serde_json::from_str::<Value>(input) {
        Ok(v) => Ok(v),
        Err(first_err) => {
            let mut items = Vec::new();
            for line in input.lines() {
                let line = line.trim();
                if line.is_empty() {
                    continue;
                }
                match serde_json::from_str::<Value>(line) {
                    Ok(v) => items.push(v),
                    Err(_) => return Err(Error::Json(first_err)),
                }
            }
            if items.is_empty() {
                Err(Error::Json(first_err))
            } else {
                Ok(Value::Array(items))
            }
        }
    }
}

fn looks_native(v: &Value) -> bool {
    if v.get("steps").is_some() {
        return true;
    }
    if let Some(arr) = v.as_array() {
        return !arr.is_empty() && arr.iter().all(|e| e.get("kind").is_some());
    }
    false
}

fn messages(v: &Value) -> Result<Vec<Value>> {
    if let Some(arr) = v.as_array() {
        Ok(arr.clone())
    } else if let Some(msgs) = v.get("messages").and_then(Value::as_array) {
        Ok(msgs.clone())
    } else {
        Err(Error::shape(
            "messages",
            "no top-level array or `messages` field",
        ))
    }
}

fn looks_anthropic(msgs: &[Value]) -> bool {
    msgs.iter().any(|m| {
        m.get("content")
            .and_then(Value::as_array)
            .is_some_and(|blocks| {
                blocks.iter().any(|b| {
                    b.get("type").and_then(Value::as_str).is_some_and(|t| {
                        matches!(t, "text" | "tool_use" | "tool_result" | "thinking")
                    })
                })
            })
    })
}

fn import_native(v: Value) -> Result<Trace> {
    if v.is_array() {
        let steps: Vec<Step> = serde_json::from_value(v)?;
        Ok(Trace::from_steps(steps))
    } else if v.get("steps").is_some() {
        Ok(serde_json::from_value(v)?)
    } else if v.is_object() {
        // An object without a `steps` field is an empty native trace, but we
        // still allow trace-level metadata to round-trip.
        Ok(serde_json::from_value(v).unwrap_or_default())
    } else {
        Err(Error::shape("veer", "expected an object or array"))
    }
}

fn str_field(m: &Value, key: &str) -> Option<String> {
    m.get(key).and_then(Value::as_str).map(str::to_string)
}

fn import_openai(msgs: &[Value]) -> Result<Trace> {
    let mut steps = Vec::new();
    for m in msgs {
        let role = str_field(m, "role");

        if role.as_deref() == Some("tool") {
            let mut step = Step::new(StepKind::ToolResult);
            step.role = Some("tool".into());
            // Prefer an explicit function name; the `tool_call_id` is volatile,
            // so keep it in metadata rather than treating it as identity.
            step.name = str_field(m, "name");
            step.content = content_text(m.get("content"));
            if let Some(id) = str_field(m, "tool_call_id") {
                step.meta.insert("tool_call_id".into(), Value::String(id));
            }
            steps.push(step);
            continue;
        }

        if let Some(text) = content_text(m.get("content"))
            && !text.is_empty()
        {
            let mut step = Step::new(StepKind::Message);
            step.role = role.clone();
            step.content = Some(text);
            steps.push(step);
        }

        if let Some(calls) = m.get("tool_calls").and_then(Value::as_array) {
            for tc in calls {
                let func = tc.get("function");
                let name = func
                    .and_then(|f| f.get("name"))
                    .and_then(Value::as_str)
                    .map(str::to_string);
                let args = func.and_then(|f| f.get("arguments")).map(parse_arguments);
                let mut step = Step::new(StepKind::ToolCall);
                step.role = role.clone();
                step.name = name;
                step.args = args;
                steps.push(step);
            }
        }
    }
    Ok(Trace::from_steps(steps))
}

/// OpenAI encodes tool-call arguments as a JSON *string*; decode it if possible,
/// otherwise keep the raw string.
fn parse_arguments(v: &Value) -> Value {
    if let Some(s) = v.as_str() {
        serde_json::from_str(s).unwrap_or_else(|_| Value::String(s.to_string()))
    } else {
        v.clone()
    }
}

/// Extract displayable text from a `content` field that may be a string or an
/// array of content parts.
fn content_text(v: Option<&Value>) -> Option<String> {
    match v {
        Some(Value::String(s)) => Some(s.clone()),
        Some(Value::Array(parts)) => {
            let mut out = String::new();
            for p in parts {
                if let Some(t) = p.get("text").and_then(Value::as_str) {
                    out.push_str(t);
                } else if let Some(s) = p.as_str() {
                    out.push_str(s);
                }
            }
            (!out.is_empty()).then_some(out)
        }
        _ => None,
    }
}

fn import_anthropic(msgs: &[Value]) -> Result<Trace> {
    let mut steps = Vec::new();
    for m in msgs {
        let role = str_field(m, "role");
        match m.get("content") {
            Some(Value::String(s)) => {
                steps.push(
                    Step::new(StepKind::Message)
                        .with_content(s.clone())
                        .with_role(role.clone().unwrap_or_default()),
                );
            }
            Some(Value::Array(blocks)) => {
                for b in blocks {
                    let ty = b.get("type").and_then(Value::as_str).unwrap_or("");
                    match ty {
                        "text" => {
                            let mut step = Step::new(StepKind::Message);
                            step.role = role.clone();
                            step.content = str_field(b, "text");
                            steps.push(step);
                        }
                        "thinking" => {
                            let mut step = Step::new(StepKind::Other("thinking".into()));
                            step.role = role.clone();
                            step.content = str_field(b, "thinking");
                            steps.push(step);
                        }
                        "tool_use" => {
                            let mut step = Step::new(StepKind::ToolCall);
                            step.role = role.clone();
                            step.name = str_field(b, "name");
                            step.args = b.get("input").cloned();
                            steps.push(step);
                        }
                        "tool_result" => {
                            let mut step = Step::new(StepKind::ToolResult);
                            step.role = Some("tool".into());
                            step.content = content_text(b.get("content"));
                            // Volatile linkage id lives in metadata, not identity.
                            if let Some(id) = str_field(b, "tool_use_id") {
                                step.meta.insert("tool_use_id".into(), Value::String(id));
                            }
                            steps.push(step);
                        }
                        _ => {}
                    }
                }
            }
            _ => {}
        }
    }
    Ok(Trace::from_steps(steps))
}

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

    #[test]
    fn imports_openai_messages_with_tool_calls() {
        let input = json!([
            {"role": "user", "content": "weather in Paris?"},
            {"role": "assistant", "content": null, "tool_calls": [
                {"id": "call_1", "type": "function",
                 "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}}
            ]},
            {"role": "tool", "tool_call_id": "call_1", "content": "18C"}
        ]);
        let trace = import_value(input, Format::Auto).unwrap();
        assert_eq!(trace.len(), 3);
        assert_eq!(trace.steps[0].kind, StepKind::Message);
        assert_eq!(trace.steps[1].kind, StepKind::ToolCall);
        assert_eq!(trace.steps[1].name.as_deref(), Some("get_weather"));
        assert_eq!(
            trace.steps[1].args.as_ref().unwrap()["city"],
            json!("Paris")
        );
        assert_eq!(trace.steps[2].kind, StepKind::ToolResult);
    }

    #[test]
    fn imports_anthropic_content_blocks() {
        let input = json!({"messages": [
            {"role": "user", "content": "weather in Paris?"},
            {"role": "assistant", "content": [
                {"type": "text", "text": "Let me check."},
                {"type": "tool_use", "id": "tu_1", "name": "get_weather",
                 "input": {"city": "Paris"}}
            ]},
            {"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": "tu_1", "content": "18C"}
            ]}
        ]});
        let trace = import_value(input, Format::Auto).unwrap();
        assert_eq!(trace.len(), 4);
        assert_eq!(trace.steps[2].kind, StepKind::ToolCall);
        assert_eq!(trace.steps[3].kind, StepKind::ToolResult);
    }

    #[test]
    fn detects_anthropic_over_openai() {
        let anthropic = json!([{"role": "assistant",
            "content": [{"type": "text", "text": "hi"}]}]);
        assert_eq!(detect(&anthropic), Format::Anthropic);

        let openai = json!([{"role": "assistant", "content": "hi"}]);
        assert_eq!(detect(&openai), Format::OpenAI);
    }

    #[test]
    fn imports_native_array_and_object() {
        let arr = json!([{"kind": "message", "role": "user", "content": "hi"}]);
        assert_eq!(detect(&arr), Format::Veer);
        let t = import_value(arr, Format::Auto).unwrap();
        assert_eq!(t.len(), 1);

        let obj = json!({"steps": [{"kind": "event", "name": "start"}], "meta": {"run": 1}});
        let t = import_value(obj, Format::Veer).unwrap();
        assert_eq!(t.len(), 1);
        assert_eq!(t.meta["run"], json!(1));
    }

    #[test]
    fn parses_newline_delimited_native_steps() {
        let jsonl = "{\"kind\":\"message\",\"role\":\"user\",\"content\":\"a\"}\n{\"kind\":\"message\",\"role\":\"assistant\",\"content\":\"b\"}";
        let t = import_str(jsonl, Format::Veer).unwrap();
        assert_eq!(t.len(), 2);
    }
}