---
title: TimelineDiff  Differential Reproducibility
emoji: 🐠
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false
license: other
short_description: Diff agent timelines. Find first divergence. Export forensic
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/cc2glLOtiZJWxbbDoELfT.jpeg
---
TimelineDiff — Differential Reproducibility Protocol (DRP)

Production agents diverge: sampling variance, flaky tools, drifting data, timing/race effects.
Benchmarks tell you *whether* you failed. Logs tell you *what happened once*.
TimelineDiff tells you **why two runs diverged**.

## What this Space does
- Upload **two DRP trace bundles (.zip)**
- Computes:
  - **Timeline alignment** (same / diff / missing)
  - **First divergence index**
  - Divergence class (sampling / tool / memory / control-flow / governance / state)
  - Per-event structured diffs (JSON)
- Exports:
  - `report.md` (human-readable)
  - `report.pdf` (stakeholder-ready)
  - `diff.json` (machine-readable)
  - `drp-diff-report.zip` (all of the above)

## DRP bundle format (v0)
A bundle is a `.zip` containing:
- `manifest.json`
- `events.jsonl`

Each event is hash-chained:
- `prev` is the previous event hash
- `hash` is SHA-256 of canonical event JSON
This makes the timeline tamper-evident.

## Optional ReplayProof deep-linking
If you include either of the following in `manifest.json`, TimelineDiff will generate per-event links:

### Option A (recommended)
```json
"replay": {
  "base_url": "https://your-space-or-site",
  "pattern": "/?run_id={run_id}&i={i}"
}

### Option B
"run_url": "https://your-viewer/run/demo-123"
Links will appear in the report and in the diff JSON.

Suggested event kinds
	•	llm_sample
	•	tool_call
	•	tool_result
	•	memory_write
	•	plan_step
	•	guardrail
	•	state_snapshot

Optional reward delta

If your state_snapshot.payload includes:
	•	reward_total, or
	•	metrics.reward_total

…TimelineDiff will compute final_reward_delta.
---

## `drp/__init__.py`

```python
__all__ = [
    "canon",
    "sha256_hex",
    "now_utc_iso",
    "load_bundle",
    "verify_bundle",
    "write_bundle_zip",
    "diff_bundles",
    "render_report_markdown",
    "write_pdf_report",
    "make_demo_bundle_zip",
    "fork_patch_bundle",
]

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference