---
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 fail in non-deterministic ways: 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:
  - **First divergence point**
  - Divergence class (sampling / tool / memory / control-flow / state)
  - Per-event structured JSON diffs
- Exports:
  - `report.md`, `diff.json`, `drp-diff-report.zip`
- Can also:
  - Verify hash-chained integrity of a bundle
  - Generate demo bundles to test the UI
  - Create a patched “fork” bundle (counterfactual edit) for sandbox what-if workflows

## 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 gives a tamper-evident timeline, and makes diffs trustworthy.

## Integrations (where this plugs in)
- Agent frameworks can export DRP events at decision points (LLM call, tool call, memory write, planner step).
- Observability can be ingested and mapped to DRP (spans → events).
- Verification primitives (signing / zk / attestations) can be layered later.

## Quick start (local)
```bash
pip install -r requirements.txt
python app.py
Suggested event kinds
	•	llm_sample
	•	tool_call
	•	tool_result
	•	memory_write
	•	plan_step
	•	guardrail
	•	state_snapshot
---

# `drp/__init__.py`

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

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