vek 0.2.0__tar.gz

vek-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v --tb=short

vek-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+.vek/
+*.db
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

vek-0.2.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: vek
+Version: 0.2.0
+Summary: Content-addressed execution store for AI agents — git semantics for agent tool calls.
+Project-URL: Repository, https://github.com/AVIDS2/vek
+Author: AVIDS2
+License-Expression: AGPL-3.0-only
+License-File: LICENSE
+Keywords: DAG,agent,content-addressed,execution-history,git,tool-call
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vek
+
+> Content-addressed execution store for AI agents — git semantics for agent tool calls.
+
+[![CI](https://github.com/AVIDS2/vek/actions/workflows/ci.yml/badge.svg)](https://github.com/AVIDS2/vek/actions/workflows/ci.yml)
+
+Vek is a minimal execution history layer for AI agents. Every tool call's input and output is stored as an immutable, content-addressed blob, forming a traceable, forkable, replayable execution DAG. Framework-agnostic — plug in with a single function call.
+
+## Philosophy
+
+**Manage agent execution history like git manages code.**
+Git doesn't care what language you write in. Vek doesn't care what framework your agent runs on.
+
+## Install
+
+```
+pip install vek
+```
+
+## Quick Start
+
+```python
+import vek
+
+vek.init()
+
+# record a single tool call
+h = vek.store(tool="search", input={"q": "climate change"}, output={"results": [...]})
+
+# session — auto-chained, atomic recording
+with vek.session() as s:
+    s.store(tool="search", input=query, output=results)
+    s.store(tool="summarise", input=text, output=summary)
+
+# auto-record with decorator
+@vek.wrap
+def search(query: str) -> dict:
+    return {"results": [...]}
+
+# inspect
+node = vek.show(h)
+blob = vek.cat_file(node["input_hash"])
+```
+
+## CLI
+
+```
+vek init                  # create .vek/ repository
+vek status                # current branch, tip, stats
+vek log [-n 20] [--graph] # execution history / ASCII DAG
+vek show <hash>           # inspect a node (short hash OK)
+vek cat-file <hash>       # dump raw object content
+vek branch [name]         # list or create/switch branches
+vek fork <hash>           # fork at a node
+vek merge <branch>        # merge branch into current
+vek diff <hash1> <hash2>  # structural JSON diff
+vek replay <hash>         # replay execution chain
+vek tag [name] [hash]     # list or create tags
+vek fsck                  # verify repository integrity
+vek gc [--dry-run]        # remove unreachable objects
+vek export [--format json|jsonl] [--branch name]
+vek import <file> [--format auto|json|jsonl]
+vek --version
+```
+
+## Python API
+
+| Function | Description |
+|----------|-------------|
+| `vek.init()` | Initialise `.vek/` repository |
+| `vek.store(tool, input, output)` | Record one tool call |
+| `vek.session()` | Context manager for atomic batch recording |
+| `vek.async_session()` | Async context manager |
+| `vek.wrap(fn)` | Decorator for auto-recording |
+| `vek.hook(dispatch_fn)` | Wrap a dispatch function |
+| `vek.log(n=20)` | Recent execution history |
+| `vek.log_graph()` | ASCII DAG visualisation |
+| `vek.show(hash)` | Node details with materialised content |
+| `vek.cat_file(hash)` | Raw object bytes |
+| `vek.status()` | Repository summary |
+| `vek.branch(name)` | Create/switch branch |
+| `vek.fork(hash, name)` | Fork at a node |
+| `vek.merge(branch)` | Merge branch (creates multi-parent node) |
+| `vek.diff(h1, h2)` | Structural JSON diff |
+| `vek.replay(hash)` | Full chain from root to hash |
+| `vek.tag(name, hash)` | Lightweight tags |
+| `vek.fsck()` | Integrity verification |
+| `vek.gc()` | Garbage collection |
+| `vek.export()` | Export chains (JSON/JSONL) |
+| `vek.import_data(data)` | Import chains |
+
+All hash arguments accept short prefixes (e.g. `h[:8]`).
+
+## Storage Layout
+
+```
+.vek/
+├── objects/     # (reserved) content-addressed hash objects
+├── refs/        # (reserved) branch pointer files
+├── HEAD         # current branch
+├── config       # repository configuration
+└── vek.db       # SQLite — objects + nodes + refs
+```
+
+## Data Model
+
+```
+objects:  hash | content
+nodes:    hash | tool | input_hash | output_hash | parent_hash | timestamp | merge_parent
+refs:     name | hash                     (branches, tags with "tag/" prefix)
+```
+
+### Object Hashing (git-style)
+
+```
+SHA-256( "blob" + " " + size + "\0" + content )   # input/output blobs
+SHA-256( "node" + " " + size + "\0" + content )   # execution nodes
+```
+
+Same content stored exactly once. Different types with identical content produce different hashes.
+
+### Merge Nodes
+
+Merge creates a node with two parents: `parent_hash` (current branch) and `merge_parent` (target branch). Tool is `__merge__`.
+
+## Concurrency
+
+- SQLite WAL mode with 5s busy timeout
+- Advisory file lock (`HEAD.lock`) prevents concurrent branch pointer writes
+- Sessions batch all writes in a single transaction (atomic commit/rollback)
+
+## Design Principles
+
+- **Content-addressed** — identical content stored once, forever
+- **Immutable** — history cannot be tampered with
+- **Framework-agnostic** — no adapters, no shims
+- **Local-first** — `.vek/` directory, zero external dependencies
+- **Minimal API** — one function call to integrate
+- **Atomic sessions** — all-or-nothing batch writes
+- **Portable** — export/import execution chains as JSON/JSONL
+
+## License
+
+[AGPL-3.0](LICENSE)

vek-0.2.0/README.md

@@ -0,0 +1,144 @@
+# vek
+
+> Content-addressed execution store for AI agents — git semantics for agent tool calls.
+
+[![CI](https://github.com/AVIDS2/vek/actions/workflows/ci.yml/badge.svg)](https://github.com/AVIDS2/vek/actions/workflows/ci.yml)
+
+Vek is a minimal execution history layer for AI agents. Every tool call's input and output is stored as an immutable, content-addressed blob, forming a traceable, forkable, replayable execution DAG. Framework-agnostic — plug in with a single function call.
+
+## Philosophy
+
+**Manage agent execution history like git manages code.**
+Git doesn't care what language you write in. Vek doesn't care what framework your agent runs on.
+
+## Install
+
+```
+pip install vek
+```
+
+## Quick Start
+
+```python
+import vek
+
+vek.init()
+
+# record a single tool call
+h = vek.store(tool="search", input={"q": "climate change"}, output={"results": [...]})
+
+# session — auto-chained, atomic recording
+with vek.session() as s:
+    s.store(tool="search", input=query, output=results)
+    s.store(tool="summarise", input=text, output=summary)
+
+# auto-record with decorator
+@vek.wrap
+def search(query: str) -> dict:
+    return {"results": [...]}
+
+# inspect
+node = vek.show(h)
+blob = vek.cat_file(node["input_hash"])
+```
+
+## CLI
+
+```
+vek init                  # create .vek/ repository
+vek status                # current branch, tip, stats
+vek log [-n 20] [--graph] # execution history / ASCII DAG
+vek show <hash>           # inspect a node (short hash OK)
+vek cat-file <hash>       # dump raw object content
+vek branch [name]         # list or create/switch branches
+vek fork <hash>           # fork at a node
+vek merge <branch>        # merge branch into current
+vek diff <hash1> <hash2>  # structural JSON diff
+vek replay <hash>         # replay execution chain
+vek tag [name] [hash]     # list or create tags
+vek fsck                  # verify repository integrity
+vek gc [--dry-run]        # remove unreachable objects
+vek export [--format json|jsonl] [--branch name]
+vek import <file> [--format auto|json|jsonl]
+vek --version
+```
+
+## Python API
+
+| Function | Description |
+|----------|-------------|
+| `vek.init()` | Initialise `.vek/` repository |
+| `vek.store(tool, input, output)` | Record one tool call |
+| `vek.session()` | Context manager for atomic batch recording |
+| `vek.async_session()` | Async context manager |
+| `vek.wrap(fn)` | Decorator for auto-recording |
+| `vek.hook(dispatch_fn)` | Wrap a dispatch function |
+| `vek.log(n=20)` | Recent execution history |
+| `vek.log_graph()` | ASCII DAG visualisation |
+| `vek.show(hash)` | Node details with materialised content |
+| `vek.cat_file(hash)` | Raw object bytes |
+| `vek.status()` | Repository summary |
+| `vek.branch(name)` | Create/switch branch |
+| `vek.fork(hash, name)` | Fork at a node |
+| `vek.merge(branch)` | Merge branch (creates multi-parent node) |
+| `vek.diff(h1, h2)` | Structural JSON diff |
+| `vek.replay(hash)` | Full chain from root to hash |
+| `vek.tag(name, hash)` | Lightweight tags |
+| `vek.fsck()` | Integrity verification |
+| `vek.gc()` | Garbage collection |
+| `vek.export()` | Export chains (JSON/JSONL) |
+| `vek.import_data(data)` | Import chains |
+
+All hash arguments accept short prefixes (e.g. `h[:8]`).
+
+## Storage Layout
+
+```
+.vek/
+├── objects/     # (reserved) content-addressed hash objects
+├── refs/        # (reserved) branch pointer files
+├── HEAD         # current branch
+├── config       # repository configuration
+└── vek.db       # SQLite — objects + nodes + refs
+```
+
+## Data Model
+
+```
+objects:  hash | content
+nodes:    hash | tool | input_hash | output_hash | parent_hash | timestamp | merge_parent
+refs:     name | hash                     (branches, tags with "tag/" prefix)
+```
+
+### Object Hashing (git-style)
+
+```
+SHA-256( "blob" + " " + size + "\0" + content )   # input/output blobs
+SHA-256( "node" + " " + size + "\0" + content )   # execution nodes
+```
+
+Same content stored exactly once. Different types with identical content produce different hashes.
+
+### Merge Nodes
+
+Merge creates a node with two parents: `parent_hash` (current branch) and `merge_parent` (target branch). Tool is `__merge__`.
+
+## Concurrency
+
+- SQLite WAL mode with 5s busy timeout
+- Advisory file lock (`HEAD.lock`) prevents concurrent branch pointer writes
+- Sessions batch all writes in a single transaction (atomic commit/rollback)
+
+## Design Principles
+
+- **Content-addressed** — identical content stored once, forever
+- **Immutable** — history cannot be tampered with
+- **Framework-agnostic** — no adapters, no shims
+- **Local-first** — `.vek/` directory, zero external dependencies
+- **Minimal API** — one function call to integrate
+- **Atomic sessions** — all-or-nothing batch writes
+- **Portable** — export/import execution chains as JSON/JSONL
+
+## License
+
+[AGPL-3.0](LICENSE)

vek-0.2.0/examples/demo.py

@@ -0,0 +1,65 @@
+"""vek — 30-second demo.
+
+Run:
+    pip install -e .
+    python examples/demo.py
+"""
+
+import tempfile, os, vek
+
+# --- setup (use a temp dir so it's self-contained) ---
+os.chdir(tempfile.mkdtemp())
+vek.init()
+
+
+# --- 1. @vek.wrap: one decorator, every call recorded ---
+
+@vek.wrap
+def search(query: str) -> dict:
+    """Simulate a web search tool."""
+    return {"results": [f"Result for '{query}'"]}
+
+@vek.wrap
+def summarise(text: str) -> str:
+    """Simulate an LLM summariser."""
+    return f"Summary: {text[:50]}..."
+
+@vek.wrap
+def decide(options: list) -> str:
+    """Simulate an agent decision."""
+    return options[0]  # always pick first
+
+
+# --- 2. Run an "agent" ---
+
+results = search("climate change effects")
+summary = summarise(str(results))
+action  = decide(["publish report", "gather more data"])
+
+
+# --- 3. Inspect what happened ---
+
+print("=== Execution Log ===")
+for node in vek.log():
+    print(f"  {node['hash'][:10]}  {node['tool']}")
+
+print()
+print("=== Status ===")
+s = vek.status()
+print(f"  Branch: {s['branch']}, Nodes: {s['nodes']}, Objects: {s['objects']}")
+
+print()
+print("=== Replay (full chain) ===")
+tip = vek.log()[0]["hash"]
+for i, step in enumerate(vek.replay(tip)):
+    print(f"  [{i}] {step['tool']}")
+    print(f"      in:  {step['input']}")
+    print(f"      out: {step['output']}")
+
+print(f"\n=== Integrity Check ===")
+errors = vek.fsck()
+print(f"  {'OK - clean' if not errors else f'{len(errors)} error(s)'}")
+
+print(f"\n=== Export (portable JSON) ===")
+data = vek.export()
+print(f"  {len(data['nodes'])} nodes, {len(data['objects'])} objects — ready to share")

vek-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vek"
+version = "0.2.0"
+description = "Content-addressed execution store for AI agents — git semantics for agent tool calls."
+readme = "README.md"
+license = "AGPL-3.0-only"
+requires-python = ">=3.10"
+authors = [
+    { name = "AVIDS2" },
+]
+keywords = ["agent", "git", "content-addressed", "execution-history", "DAG", "tool-call"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+vek = "vek.cli:main"
+
+[project.urls]
+Repository = "https://github.com/AVIDS2/vek"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vek"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vek-0.2.0/src/vek/__init__.py

@@ -0,0 +1,28 @@
+"""vek - Content-addressed execution store for AI agents."""
+
+from vek.api import (
+    init, store, log, branch, fork, diff, replay,
+    show, cat_file, status, tag, fsck, gc,
+    merge, log_graph, export, import_data,
+)
+from vek.hooks import AsyncSession as _AsyncSession
+from vek.hooks import hook, wrap
+from vek.session import Session as _Session
+
+__version__ = "0.2.0"
+__all__ = [
+    "init", "store", "log", "branch", "fork", "diff", "replay",
+    "show", "cat_file", "status", "tag", "fsck", "gc",
+    "merge", "log_graph", "export", "import_data",
+    "session", "async_session", "wrap", "hook",
+]
+
+
+def session(**kwargs):
+    """Open an auto-recording execution session."""
+    return _Session(**kwargs)
+
+
+def async_session(**kwargs):
+    """Open an async auto-recording execution session."""
+    return _AsyncSession(**kwargs)