trrack

Branching, tree-based provenance tracking for Python. A pure model with no UI dependencies: a ProvenanceGraph of full-state snapshots you can navigate, branch, label, and persist.

Part of the trrackpy monorepo; the trrack-widget package is one consumer of this core.

Install

uv add trrack          # or: pip install trrack

Concepts

• Every state you record is stored as a full snapshot in a Node. Nodes form a tree: committing from an earlier node creates a branch rather than discarding the later history.
• The model is deterministic and I/O-free. It never reads the clock — timestamps are passed in by the caller via now — so behavior is fully reproducible and easy to test.
• Persistence is an optional, swappable seam (Store); the model itself holds no opinion about where state is saved.

Quick start

from trrack import ProvenanceGraph

g = ProvenanceGraph({"count": 0}, now="t0")
g.commit({"count": 1}, now="t1")
g.commit({"count": 2}, now="t2")

g.undo()                 # back to {"count": 1}
g.redo()                 # forward to {"count": 2}

# Branch: go back, then commit a different state off the earlier node.
g.go_to(g.root.id)
g.commit({"count": 99}, now="t3")   # new branch from the root

g.current.state          # {"count": 99}
g.is_at_root, g.is_at_latest

Commits are auto-labeled from what changed; pass label= to name them, or relabel later with g.relabel("checkpoint").

Persistence

Round-trip the whole graph to a JSON file:

g.save("graph.json")
restored = ProvenanceGraph.load("graph.json")   # None if the file is absent

save/load use atomic writes (write-to-temp, then os.replace) so a crash mid-write can never leave a half-written file.

For anything other than a local file, use the Store seam — any object with save(dict) -> None and load() -> dict | None qualifies (a database, browser storage, a remote service), with no registry or plugin machinery. JsonFileStore is the built-in implementation:

from trrack import JsonFileStore

store = JsonFileStore("graph.json")
store.save(g.to_dict())
data = store.load()                  # None if nothing saved yet

API

A Node exposes id, parent, children, created_at, label, and state.

License

BSD-3-Clause.