$ dprovenancekit

dprovenance.dev / docs

Documentation

Everything to record, diff, attest, and CI-gate your AI's reasoning — on device. This hub links to the on-site guides and the interactive Explorer, and to the canonical reference docs in the repository. One source of truth per topic — nothing here is a stale copy.

Add to an existing agent in 15 min → Open the Explorer README on GitHub

▸ start here

New here

Getting started

Install, the five-minute quickstart, and the 15-minute onboarding tutorial.

Why it matters

Reasoning, not requests — the semantic model behind structural diffing.

Ship it

Operations & CI

Fail the pull request when the reasoning path drifts.

# 01 · getting started

Getting started

From zero to a recorded, diffable, offline-verifiable run.

Install & requirements GitHub

Add via SwiftPM, platform support, and the Swift 6.0 floor / 6.2 live-FM note.

Five-minute quickstart GitHub

Record → query → diff → align → gate, end to end.

Add to an existing agent in 15 min tutorial

Instrument an agent you already have — no refactor — and prove a run offline.

Trace a Foundation Models session GitHub

One-liner capture for Apple's on-device model — live, post-hoc, or standalone.

Try it in the browser live

The interactive Explorer renders a reasoning-trace diff with zero setup.

# 02 · core concepts

Core concepts

What a reasoning trace is, and why structure is more stable than output.

Regression testing for AI agents guide

Record a golden run, diff execution structure, fail CI when reasoning drifts.

The semantic model GitHub

Alignment, behavioral equivalence, and the invariants queries and diffs rely on.

Proof of work: an invisible regression GitHub

A real case where output tests stayed green and a structural diff caught the drift.

Design & engine internals GitHub

Concurrency, backpressure, durability, and the design tradeoffs behind the core.

# 03 · adapters & integrations

Adapters & integrations

Wire DProvenanceKit into the framework you already run. The core stays zero-dependency.

Foundation Models GitHub

Live + post-hoc capture, the event vocabulary, span-path grammar, and redaction.

Foundation Models regression demo GitHub

A runnable end-to-end scenario: an OS update drops a tool call, CI catches it.

OpenTelemetry / OTLP bridge GitHub

Export traces to Langfuse or any OTLP collector — zero-dependency bridge.

LangChain / LangGraph on-site

Python-port adapter for LangChain and LangGraph.

Event-bus listener for the CrewAI 1.x line.

LlamaIndex on-site

Callback-based capture for LlamaIndex workflows.

OpenAI Agents SDK on-site

Listed in the official OpenAI Agents SDK tracing docs.

Cloud ingestion experimental

CloudTraceStore ships events to an HTTP endpoint you operate.

# 04 · attestation & verification

Attestation & verification

Turn a completed run into a signed, offline-verifiable artifact.

Trace attestation GitHub

P-256 signing, Secure Enclave keys, canonicalization, and the offline verify path.

Proof packs GitHub

One JSON bundle binding a signed attestation to the artifact bytes it vouches for.

# 05 · trace tooling

Replay, diff & inspect

Reconstruct, compare, and explore a run after it happened.

Trace replay GitHub

Reconstruct a run's span tree as of any point in time, with an integrity manifest.

Snapshot diffing GitHub

Span- and event-level changes between two replay states, with exact divergence points.

Live queries GitHub

Register a query once; get a callback the moment a run starts matching it.

Trace inspector UI GitHub

DProvenanceUI — a SwiftUI run list, replay timeline scrubber, and live diff mode.

Web Explorer live

Drop in your own web-export JSON and read the structural diff in-browser.

# 06 · operations & CI

Operations & CI

Fail the pull request when the reasoning path drifts — not just when a string changes.

A CI gate for reasoning regressions (Swift) tutorial

The Swift-native gate the site guide doesn't cover — recipes and an honest look at what dpk does and doesn't gate.

A CI gate for LLM agents (Python) guide

The dprovenancekit gate CLI, the GitHub Action, and a GitLab template.

Common regression patterns tutorial

Dropped tool call, reordered steps, path divergence, silent drift — and the exact mechanism that fires for each.

GitHub Action Marketplace

Drop-in regression gate that comments the diff on the pull request.

DProvenanceKit vs LangSmith on-site

A local-first library and a deterministic gate, versus a hosted platform.

# 07 · reference

Reference

Architecture, measured performance, and project docs — the canonical markdown in the repo.

Architecture overview GitHub

The components and how a trace flows from record to query to diff.

Benchmarks & operating envelope GitHub

The measured (informative) envelope for align() and diff() at scale.

Changelog GitHub

Keep-a-Changelog history, currently at 0.7.0.

Security policy GitHub

How to report a vulnerability.

Contributing GitHub

Build, test, the free/paid boundary, and the PR checklist.

Python port GitHub

The Python implementation, kept behaviorally equivalent via Trace Spec v1.

License & commercial GitHub

Apache-2.0 core; where the commercial boundary sits.