kvgit 🔀
Git-style versioning for your data. Commits, branches, and merges -- backed by a dict-like MutableMapping.
| Features | Description |
|---|---|
| Dict interface | MutableMapping[str, Any] -- reads and writes work like a dict |
| Commits | Immutable, content-addressable snapshots with rollback |
| Branches | Cheap forks with CAS-based optimistic concurrency |
| Tags | Immutable names for commits; a tagged commit outlives every branch that reached it, in every kvgit version |
| Three-way merge | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
| Pluggable backends | In-memory, disk (diskcache), IndexedDB (Pyodide/browser), or bring your own KVStore |
| Chunked codecs | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
Install
pip install kvgit # in-memory only
pip install kvgit[disk] # adds disk backend via diskcache
pip install kvgit[scientific] # adds chunked codecs for numpy / pandas
# IndexedDB backend is available automatically in Pyodide (browser) environments
Quick example
import kvgit
main = kvgit.store()
main["user"] = "alice"
main["score"] = 0
main.commit()
# Branch and diverge
dev = main.create_branch("dev")
dev["score"] = 999
dev.commit()
print(main["score"]) # 0 (main unchanged)
print(dev["score"]) # 999 (dev branch)
# Tag a commit by name -- immutable, and safe from garbage collection
main.tag("v1")
print(main.peek("score", tag="v1")) # 0
Chunked codecs (numpy / pandas)
Large numpy arrays and pandas DataFrames -- and any sliced views of them -- can be stored once and shared across keys, commits, and branches:
import kvgit
import numpy as np
s = kvgit.store(codecs="scientific")
big = np.arange(1_000_000, dtype="float64") # ~8 MB
s["full"] = big
s["head"] = big[:100_000]
s["tail"] = big[-100_000:]
s.commit()
# All three keys reference the same chunk on disk -- ~8 MB total, not ~24 MB.
Pandas DataFrames piggyback on the numpy codec via their underlying block ndarrays. See docs/quick-start.md and the API reference.
Part of the agex stack
kvgit provides versioned agent memory in agex with branching and rollback. It also works as a versioned backing store for monkeyfs virtual filesystems -- pass a Staged instance anywhere a dict is expected.
Development
uv sync --extra dev
uv run pytest
Documentation
See docs/ for detailed documentation:
- Quick Start -- common patterns with runnable examples
- API Reference -- full reference for all classes, methods, and types
- Browser persistence (Pyodide) -- choosing between the IndexedDB and OPFS-mounted-disk backends, plus the syncfs flush requirement and recommended host-side patterns
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file kvgit-0.3.5.tar.gz.
File metadata
- Download URL: kvgit-0.3.5.tar.gz
- Upload date:
- Size: 80.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
05ab905da1fe6eabc7274b4074f3839eff32cf2473daa1d2d49f62f771b5eba4
|
|
| MD5 |
29fafa84350103fb6903a1fd06e20774
|
|
| BLAKE2b-256 |
66b425767e5307cae606d3083f721cddaa100ec941933e1b55de2fd4a36cd8e0
|
File details
Details for the file kvgit-0.3.5-py3-none-any.whl.
File metadata
- Download URL: kvgit-0.3.5-py3-none-any.whl
- Upload date:
- Size: 74.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8fc7804cfc51e68121dcf3c7cade51abe66f2af0a50e8ba9e993c40e17e172dd
|
|
| MD5 |
23b6fc38614fe8a72d6d3051898575a3
|
|
| BLAKE2b-256 |
ed7884f236a75457f3225e17efb2c93e42fc2b42b464525f474d82d138ecdff9
|
