verityledger 0.1.0__tar.gz

verityledger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tracewell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verityledger-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: verityledger
+Version: 0.1.0
+Summary: Tamper-evident decision and tool-call logging for AI agents.
+Author: VerityLedger
+License: MIT
+Project-URL: Homepage, https://github.com/verityledger/verityledger
+Project-URL: Issues, https://github.com/verityledger/verityledger/issues
+Keywords: ai,agents,audit,logging,llm,observability
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# VerityLedger
+
+**Know exactly what your AI agent did, and prove nothing was changed after the fact.**
+
+VerityLedger is a small Python library that wraps your agent's tool calls and
+decisions in a tamper-evident, hash-chained log. When something goes wrong —
+a bad refund, a broken deploy, a strange customer reply — you can pull up the
+exact sequence of tool calls, model inputs/outputs, and reasoning that led
+there, and prove the record hasn't been altered.
+
+No database. No external service. No blockchain. Just an append-only file
+and SHA-256.
+
+```python
+from verityledger import Tracer
+
+tracer = Tracer()  # writes to ./verityledger_log.jsonl
+
+with tracer.session(agent="support-bot", user="user_123") as session:
+
+    @session.trace_tool
+    def issue_refund(order_id: str, amount: float) -> str:
+        return f"refunded {amount} for {order_id}"
+
+    issue_refund("ORD-4471", 42.00)
+
+    session.log_decision(
+        "approved refund",
+        reasoning="customer reported damaged item, photo provided, within policy",
+    )
+```
+
+Every call to `issue_refund`, every `log_decision`, and any model calls you
+log are written as chained entries — each one includes a hash of the
+previous entry. If anyone edits a past entry, the chain breaks at exactly
+that point.
+
+## Why this exists
+
+Agents are making real decisions — refunds, emails, code pushes, customer
+replies — and most teams have no record of *why* beyond scattered print
+statements and provider dashboards. When a regulator, a customer, or your
+own team asks "why did the bot do that?", you want an answer that's both
+complete and verifiable.
+
+## Install
+
+```bash
+pip install verityledger
+```
+
+## Verify the chain
+
+```python
+valid, break_index = tracer.verify(session.id)
+# valid == True, break_index == None  (until someone tampers with the log)
+
+# Or raise on problems:
+tracer.assert_valid(session.id)
+# raises ChainIntegrityError or SessionNotFoundError
+```
+
+## Export an audit report
+
+```python
+tracer.export_report(session.id, "incident_report.json")
+```
+
+Produces a single JSON file with every entry for that session, plus the
+verification result — ready to attach to an incident review or compliance
+request.
+
+## CLI
+
+Installing the package also installs a `verityledger` command:
+
+```bash
+verityledger sessions                          # list session ids in the log
+verityledger show <session_id>                 # print all entries for a session
+verityledger verify <session_id>               # check the hash chain for tampering
+verityledger export <session_id> report.json   # write a JSON audit report
+```
+
+All commands accept `--log PATH` to point at a specific log file
+(default: `./verityledger_log.jsonl`).
+
+## Architecture
+
+The library is layered so each piece can be tested and replaced independently:
+
+- **`chain.py`** — the cryptographic primitive. Defines `Entry`, hashing,
+  and `verify_chain`. No I/O, no dependencies.
+- **`storage/`** — the `Store` interface plus `LocalStore` (append-only
+  JSONL). A hosted backend (SQLite/Postgres/API) implements the same
+  interface and drops in without touching anything above it.
+- **`core.py`** — the public API: `Tracer` and `Session`.
+- **`cli/`** — the `verityledger` terminal command. Built entirely on top of
+  the public API above; no logic of its own beyond argument parsing
+  and output formatting.
+- **`exceptions.py`** — shared error types (`StorageError`,
+  `ChainIntegrityError`, `SessionNotFoundError`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .          # lint
+mypy src/verityledger    # strict type check
+pytest                # tests + coverage
+```
+
+## Status
+
+Early release. The local file-based logger (above) is free and open source
+(MIT) — your data never leaves your machine. A hosted dashboard for
+searching across sessions, team access, and longer retention is in
+development.
+
+## Roadmap
+
+- [x] Hash-chained local logging (Python)
+- [x] Tool-call decorator, decision logging, model-call logging
+- [x] Tamper detection / chain verification
+- [x] Audit report export
+- [x] Full test suite, type checking, CI
+- [x] CLI (`verityledger sessions/show/verify/export`)
+- [ ] JavaScript/TypeScript SDK
+- [ ] Hosted dashboard (search, team accounts, retention policies)
+- [ ] LangChain / OpenAI / Anthropic tool-use integrations
+- [ ] Remote ingestion endpoint (send logs to VerityLedger Cloud)
+
+## License
+
+MIT

verityledger-0.1.0/README.md

@@ -0,0 +1,134 @@
+# VerityLedger
+
+**Know exactly what your AI agent did, and prove nothing was changed after the fact.**
+
+VerityLedger is a small Python library that wraps your agent's tool calls and
+decisions in a tamper-evident, hash-chained log. When something goes wrong —
+a bad refund, a broken deploy, a strange customer reply — you can pull up the
+exact sequence of tool calls, model inputs/outputs, and reasoning that led
+there, and prove the record hasn't been altered.
+
+No database. No external service. No blockchain. Just an append-only file
+and SHA-256.
+
+```python
+from verityledger import Tracer
+
+tracer = Tracer()  # writes to ./verityledger_log.jsonl
+
+with tracer.session(agent="support-bot", user="user_123") as session:
+
+    @session.trace_tool
+    def issue_refund(order_id: str, amount: float) -> str:
+        return f"refunded {amount} for {order_id}"
+
+    issue_refund("ORD-4471", 42.00)
+
+    session.log_decision(
+        "approved refund",
+        reasoning="customer reported damaged item, photo provided, within policy",
+    )
+```
+
+Every call to `issue_refund`, every `log_decision`, and any model calls you
+log are written as chained entries — each one includes a hash of the
+previous entry. If anyone edits a past entry, the chain breaks at exactly
+that point.
+
+## Why this exists
+
+Agents are making real decisions — refunds, emails, code pushes, customer
+replies — and most teams have no record of *why* beyond scattered print
+statements and provider dashboards. When a regulator, a customer, or your
+own team asks "why did the bot do that?", you want an answer that's both
+complete and verifiable.
+
+## Install
+
+```bash
+pip install verityledger
+```
+
+## Verify the chain
+
+```python
+valid, break_index = tracer.verify(session.id)
+# valid == True, break_index == None  (until someone tampers with the log)
+
+# Or raise on problems:
+tracer.assert_valid(session.id)
+# raises ChainIntegrityError or SessionNotFoundError
+```
+
+## Export an audit report
+
+```python
+tracer.export_report(session.id, "incident_report.json")
+```
+
+Produces a single JSON file with every entry for that session, plus the
+verification result — ready to attach to an incident review or compliance
+request.
+
+## CLI
+
+Installing the package also installs a `verityledger` command:
+
+```bash
+verityledger sessions                          # list session ids in the log
+verityledger show <session_id>                 # print all entries for a session
+verityledger verify <session_id>               # check the hash chain for tampering
+verityledger export <session_id> report.json   # write a JSON audit report
+```
+
+All commands accept `--log PATH` to point at a specific log file
+(default: `./verityledger_log.jsonl`).
+
+## Architecture
+
+The library is layered so each piece can be tested and replaced independently:
+
+- **`chain.py`** — the cryptographic primitive. Defines `Entry`, hashing,
+  and `verify_chain`. No I/O, no dependencies.
+- **`storage/`** — the `Store` interface plus `LocalStore` (append-only
+  JSONL). A hosted backend (SQLite/Postgres/API) implements the same
+  interface and drops in without touching anything above it.
+- **`core.py`** — the public API: `Tracer` and `Session`.
+- **`cli/`** — the `verityledger` terminal command. Built entirely on top of
+  the public API above; no logic of its own beyond argument parsing
+  and output formatting.
+- **`exceptions.py`** — shared error types (`StorageError`,
+  `ChainIntegrityError`, `SessionNotFoundError`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .          # lint
+mypy src/verityledger    # strict type check
+pytest                # tests + coverage
+```
+
+## Status
+
+Early release. The local file-based logger (above) is free and open source
+(MIT) — your data never leaves your machine. A hosted dashboard for
+searching across sessions, team access, and longer retention is in
+development.
+
+## Roadmap
+
+- [x] Hash-chained local logging (Python)
+- [x] Tool-call decorator, decision logging, model-call logging
+- [x] Tamper detection / chain verification
+- [x] Audit report export
+- [x] Full test suite, type checking, CI
+- [x] CLI (`verityledger sessions/show/verify/export`)
+- [ ] JavaScript/TypeScript SDK
+- [ ] Hosted dashboard (search, team accounts, retention policies)
+- [ ] LangChain / OpenAI / Anthropic tool-use integrations
+- [ ] Remote ingestion endpoint (send logs to VerityLedger Cloud)
+
+## License
+
+MIT

verityledger-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "verityledger"
+version = "0.1.0"
+description = "Tamper-evident decision and tool-call logging for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "VerityLedger" }]
+keywords = ["ai", "agents", "audit", "logging", "llm", "observability"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+verityledger = "verityledger.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/verityledger/verityledger"
+Issues = "https://github.com/verityledger/verityledger/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+verityledger = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=verityledger --cov-report=term-missing"
+
+[tool.ruff]
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+mypy_path = "src"

verityledger-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

verityledger-0.1.0/src/verityledger/__init__.py

@@ -0,0 +1,24 @@
+from .chain import Entry, verify_chain
+from .core import Session, Tracer
+from .exceptions import (
+    ChainIntegrityError,
+    SessionNotFoundError,
+    StorageError,
+    VerityLedgerError,
+)
+from .storage import LocalStore, Store
+
+__all__ = [
+    "Tracer",
+    "Session",
+    "Entry",
+    "verify_chain",
+    "Store",
+    "LocalStore",
+    "VerityLedgerError",
+    "StorageError",
+    "ChainIntegrityError",
+    "SessionNotFoundError",
+]
+
+__version__ = "0.1.0"

verityledger-0.1.0/src/verityledger/chain.py

@@ -0,0 +1,107 @@
+"""
+Hash-chained, tamper-evident log entries.
+
+Each entry includes a hash of the previous entry, forming a chain.
+Any modification to a past entry breaks the chain for everything after it,
+making tampering detectable without needing a blockchain or external service.
+
+This module has zero dependencies on storage or the public API — it is the
+single source of truth for what an "entry" is and how the chain is verified.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+GENESIS_HASH = "0" * 64
+
+
+def _canonical_json(data: dict[str, Any]) -> str:
+    """Serialize a dict deterministically so hashes are reproducible."""
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), default=str)
+
+
+@dataclass(frozen=True)
+class Entry:
+    """A single chained log entry."""
+
+    id: str
+    session_id: str
+    timestamp: float
+    event_type: str
+    data: dict[str, Any]
+    previous_hash: str
+    hash: str = field(default="")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> Entry:
+        return cls(**raw)
+
+    @property
+    def content_hash(self) -> str:
+        """Hash of this entry's content, excluding the stored `hash` field."""
+        content = {k: v for k, v in self.to_dict().items() if k != "hash"}
+        return hashlib.sha256(_canonical_json(content).encode("utf-8")).hexdigest()
+
+
+def make_entry(
+    session_id: str,
+    event_type: str,
+    data: dict[str, Any],
+    previous_hash: str,
+) -> Entry:
+    """
+    Build a single chained log entry, with its hash computed and set.
+
+    Args:
+        session_id: identifier for the agent run / conversation this belongs to.
+        event_type: e.g. "tool_call", "model_call", "decision".
+        data: arbitrary JSON-serializable payload for this event.
+        previous_hash: hash of the prior entry in this session's chain
+                        (use GENESIS_HASH for the first entry).
+
+    Returns:
+        A completed, hashed Entry.
+    """
+    entry = Entry(
+        id=str(uuid.uuid4()),
+        session_id=session_id,
+        timestamp=time.time(),
+        event_type=event_type,
+        data=data,
+        previous_hash=previous_hash,
+        hash="",
+    )
+    return Entry(**{**entry.to_dict(), "hash": entry.content_hash})
+
+
+def verify_chain(entries: list[Entry]) -> tuple[bool, int | None]:
+    """
+    Verify a list of entries forms an unbroken, untampered hash chain.
+
+    The list is assumed to be in chronological order for a single session.
+    An empty list is considered valid (vacuously).
+
+    Returns:
+        (is_valid, index_of_first_break_or_none)
+    """
+    expected_previous = GENESIS_HASH
+
+    for i, entry in enumerate(entries):
+        if entry.previous_hash != expected_previous:
+            return False, i
+
+        if entry.content_hash != entry.hash:
+            return False, i
+
+        expected_previous = entry.hash
+
+    return True, None

verityledger-0.1.0/src/verityledger/cli/__init__.py

@@ -0,0 +1,3 @@
+from .__main__ import main
+
+__all__ = ["main"]

verityledger-0.1.0/src/verityledger/cli/__main__.py

@@ -0,0 +1,134 @@
+"""
+VerityLedger CLI.
+
+Lets you inspect, verify, and export logs from the terminal without
+writing any Python. Built entirely on top of the public `verityledger`
+API (Tracer/LocalStore) - the CLI has no logic of its own beyond
+argument parsing and formatting.
+
+Usage:
+    verityledger sessions [--log PATH]
+    verityledger show SESSION_ID [--log PATH]
+    verityledger verify SESSION_ID [--log PATH]
+    verityledger export SESSION_ID OUT_PATH [--log PATH]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timezone
+
+from ..core import Tracer
+from ..exceptions import ChainIntegrityError, SessionNotFoundError, VerityLedgerError
+
+DEFAULT_LOG_PATH = "./verityledger_log.jsonl"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="verityledger",
+        description="Inspect, verify, and export VerityLedger agent logs.",
+    )
+    parser.add_argument(
+        "--log",
+        default=DEFAULT_LOG_PATH,
+        help=f"Path to the log file (default: {DEFAULT_LOG_PATH})",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("sessions", help="List all session ids in the log.")
+
+    show = subparsers.add_parser("show", help="Print all entries for a session.")
+    show.add_argument("session_id")
+
+    verify = subparsers.add_parser("verify", help="Check a session's hash chain for tampering.")
+    verify.add_argument("session_id")
+
+    export = subparsers.add_parser("export", help="Export a session as a JSON audit report.")
+    export.add_argument("session_id")
+    export.add_argument("out_path")
+
+    return parser
+
+
+def _format_timestamp(ts: float) -> str:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def cmd_sessions(tracer: Tracer) -> int:
+    sessions = tracer.store.all_sessions()
+    if not sessions:
+        print("No sessions found.")
+        return 0
+    for sid in sessions:
+        count = len(tracer.store.get_session(sid))
+        print(f"{sid}  ({count} entries)")
+    return 0
+
+
+def cmd_show(tracer: Tracer, session_id: str) -> int:
+    entries = tracer.store.get_session(session_id)
+    if not entries:
+        print(f"No entries found for session '{session_id}'.", file=sys.stderr)
+        return 1
+    for entry in entries:
+        print(f"[{_format_timestamp(entry.timestamp)}] {entry.event_type}")
+        for key, value in entry.data.items():
+            print(f"    {key}: {value}")
+        print(f"    hash: {entry.hash[:12]}...")
+    return 0
+
+
+def cmd_verify(tracer: Tracer, session_id: str) -> int:
+    try:
+        tracer.assert_valid(session_id)
+    except SessionNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    except ChainIntegrityError as exc:
+        print(f"TAMPERING DETECTED: {exc}", file=sys.stderr)
+        return 1
+
+    entry_count = len(tracer.store.get_session(session_id))
+    print(f"Chain valid: {entry_count} entries, no tampering detected.")
+    return 0
+
+
+def cmd_export(tracer: Tracer, session_id: str, out_path: str) -> int:
+    try:
+        report = tracer.export_report(session_id, out_path)
+    except SessionNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    status = "valid" if report["chain_valid"] else "TAMPERED"
+    print(f"Exported {report['entry_count']} entries to {out_path} (chain: {status}).")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    tracer = Tracer(log_path=args.log)
+
+    try:
+        if args.command == "sessions":
+            return cmd_sessions(tracer)
+        if args.command == "show":
+            return cmd_show(tracer, args.session_id)
+        if args.command == "verify":
+            return cmd_verify(tracer, args.session_id)
+        if args.command == "export":
+            return cmd_export(tracer, args.session_id, args.out_path)
+    except VerityLedgerError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())