powerailabs-acttrace 0.1.0__tar.gz

powerailabs_acttrace-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.uv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+.DS_Store
+*.log

powerailabs_acttrace-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: powerailabs-acttrace
+Version: 0.1.0
+Summary: Audit: a tamper-evident, hash-chained, auto-populated record of every AI decision — verifiable offline. Evidence, not a compliance guarantee.
+Author: Raghav Mishra
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: powerailabs-core<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# powerailabs-acttrace
+
+A tamper-evident, append-only record of every AI decision — what model, what context, what it
+cost, which tools, and who signed off — mapped to control templates and exportable as an evidence
+pack. No database, no infra: integrity comes from a hash chain, not a server.
+
+**Audit-ready evidence in 5 lines — and verifiable offline.**
+
+![status](https://img.shields.io/badge/status-building-yellow) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+🚧 building (v0) · `pip install powerailabs-acttrace` · `from powerailabs.acttrace import AuditLog`
+
+```python
+from powerailabs.core import instrument
+from powerailabs.acttrace import AuditLog
+
+client = instrument(OpenAI())
+audit = AuditLog(system="loan_triage", risk_tier="high")     # auto-subscribes to core events
+
+with audit.decision(input=application, actor="agent") as d:
+    resp = client.chat.completions.create(model="gpt-4o", messages=msgs)  # auto-logged
+    d.record(model="gpt-4o", prompt_id="triage@v3")          # cost/context captured for free
+    d.human_oversight(reviewer="ops@bank", action="approved")
+
+audit.export("evidence_q3.jsonl", framework="eu_ai_act")     # evidence pack
+```
+
+```bash
+acttrace verify evidence_q3.jsonl     # re-walks the hash chain; exits non-zero if broken
+```
+
+**Wrap-around, auto-subscribing.** Because cost (`tokenguard`) and context decisions (`contextkit`)
+ride core's shared event stream, the log fills itself — install the stack, call `instrument()`
+once, and the record already knows the model, the context, the cost, and the tools. Each entry is
+chained (`hash = sha256(prev + canonical(entry))`), so any later edit breaks the chain.
+
+> `acttrace` produces **evidence to support** compliance — it is **not** legal advice and not a
+> compliance guarantee. Control mappings are a starting template for your compliance team.
+
+See [`docs/acttrace.md`](../../docs/acttrace.md). *Part of the PowerAI Labs stack — github.com/PowerAI-Labs/powerailabs.*

powerailabs_acttrace-0.1.0/README.md

@@ -0,0 +1,40 @@
+# powerailabs-acttrace
+
+A tamper-evident, append-only record of every AI decision — what model, what context, what it
+cost, which tools, and who signed off — mapped to control templates and exportable as an evidence
+pack. No database, no infra: integrity comes from a hash chain, not a server.
+
+**Audit-ready evidence in 5 lines — and verifiable offline.**
+
+![status](https://img.shields.io/badge/status-building-yellow) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+🚧 building (v0) · `pip install powerailabs-acttrace` · `from powerailabs.acttrace import AuditLog`
+
+```python
+from powerailabs.core import instrument
+from powerailabs.acttrace import AuditLog
+
+client = instrument(OpenAI())
+audit = AuditLog(system="loan_triage", risk_tier="high")     # auto-subscribes to core events
+
+with audit.decision(input=application, actor="agent") as d:
+    resp = client.chat.completions.create(model="gpt-4o", messages=msgs)  # auto-logged
+    d.record(model="gpt-4o", prompt_id="triage@v3")          # cost/context captured for free
+    d.human_oversight(reviewer="ops@bank", action="approved")
+
+audit.export("evidence_q3.jsonl", framework="eu_ai_act")     # evidence pack
+```
+
+```bash
+acttrace verify evidence_q3.jsonl     # re-walks the hash chain; exits non-zero if broken
+```
+
+**Wrap-around, auto-subscribing.** Because cost (`tokenguard`) and context decisions (`contextkit`)
+ride core's shared event stream, the log fills itself — install the stack, call `instrument()`
+once, and the record already knows the model, the context, the cost, and the tools. Each entry is
+chained (`hash = sha256(prev + canonical(entry))`), so any later edit breaks the chain.
+
+> `acttrace` produces **evidence to support** compliance — it is **not** legal advice and not a
+> compliance guarantee. Control mappings are a starting template for your compliance team.
+
+See [`docs/acttrace.md`](../../docs/acttrace.md). *Part of the PowerAI Labs stack — github.com/PowerAI-Labs/powerailabs.*

powerailabs_acttrace-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "powerailabs-acttrace"
+version = "0.1.0"
+description = "Audit: a tamper-evident, hash-chained, auto-populated record of every AI decision — verifiable offline. Evidence, not a compliance guarantee."
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Raghav Mishra" }]
+readme = "README.md"
+dependencies = ["powerailabs-core>=0.1,<0.2"]
+
+[project.scripts]
+acttrace = "powerailabs.acttrace.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/powerailabs"]     # contributes powerailabs/acttrace only — NEVER add src/powerailabs/__init__.py

powerailabs_acttrace-0.1.0/src/powerailabs/acttrace/__init__.py

@@ -0,0 +1,234 @@
+"""powerailabs.acttrace — a tamper-evident, auto-populated audit log for AI decisions.
+
+Construct an :class:`AuditLog` and it **subscribes** to ``powerailabs.core``'s event stream: every
+instrumented model/tool call — and the context decisions ``contextkit`` and cost ``tokenguard``
+ride on that same stream — becomes an audit entry with no per-call wiring. You add only the
+explicit human-facing events (``decision``, ``human_oversight``).
+
+Integrity comes from a **hash chain**, not a server: ``entry.hash = sha256(prev_hash +
+canonical(entry))``, so editing any past entry breaks every entry after it. ``acttrace verify
+file.jsonl`` re-walks the chain offline.
+
+> This produces **evidence to support** compliance (e.g. EU AI Act record-keeping / human
+> oversight). It is **not** legal advice and not a compliance guarantee. Control mappings are a
+> starting template for your compliance team to adjust.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from powerailabs.core import bus
+from powerailabs.core.types import LLMCall, ToolCall
+
+__all__ = ["AuditLog", "AuditEntry", "verify", "GENESIS"]
+
+GENESIS = "0" * 64
+
+_active_decision: ContextVar[str | None] = ContextVar("powerailabs_acttrace_decision", default=None)
+
+# Starting-template control mapping (NOT legal advice). docs/acttrace.md §5, §7.
+_CONTROLS: dict[str, dict[str, list[str]]] = {
+    "eu_ai_act": {
+        "decision": ["Art.12 record-keeping"],
+        "llm_call": ["Art.12 logging"],
+        "tool_call": ["Art.12 logging"],
+        "context_assembly": ["Art.12 logging"],
+        "human_oversight": ["Art.14 human oversight"],
+    },
+}
+
+
+@dataclass
+class AuditEntry:
+    """One link in the hash chain. docs/acttrace.md §5."""
+
+    seq: int
+    ts: str
+    type: str  # decision | llm_call | tool_call | human_oversight | context_assembly | ...
+    payload: dict
+    prev_hash: str
+    hash: str
+
+
+def _jsonable(obj: Any) -> Any:
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, dict):
+        return {str(k): _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    if hasattr(obj, "amount") and hasattr(obj, "currency"):  # Money
+        return f"{obj.amount} {obj.currency}"
+    if hasattr(obj, "__dict__"):
+        return _jsonable(vars(obj))
+    return str(obj)
+
+
+def _canonical(payload: dict) -> str:
+    return json.dumps(_jsonable(payload), sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+
+
+def _chain_hash(prev_hash: str, seq: int, ts: str, etype: str, payload: dict) -> str:
+    body = _canonical({"seq": seq, "ts": ts, "type": etype, "payload": payload})
+    return hashlib.sha256((prev_hash + body).encode("utf-8")).hexdigest()
+
+
+class AuditLog:
+    """A hash-chained, append-only, auto-populating audit log. docs/acttrace.md §3, §5."""
+
+    def __init__(self, system: str, risk_tier: str = "limited", path: str | None = None) -> None:
+        self.system = system
+        self.risk_tier = risk_tier
+        self.path = Path(path) if path else None
+        self.entries: list[AuditEntry] = []
+        self._head = GENESIS
+        if self.path is not None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text("", encoding="utf-8")
+        self._append("audit_open", {"system": system, "risk_tier": risk_tier})
+        bus.subscribe(self._on_event)
+
+    # ------------------------------------------------------------------ chain
+
+    def _append(self, etype: str, payload: dict) -> AuditEntry:
+        seq = len(self.entries)
+        ts = datetime.now(UTC).isoformat()
+        h = _chain_hash(self._head, seq, ts, etype, payload)
+        entry = AuditEntry(seq, ts, etype, _jsonable(payload), self._head, h)
+        self.entries.append(entry)
+        self._head = h
+        if self.path is not None:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(entry.__dict__, ensure_ascii=False) + "\n")
+        return entry
+
+    # ------------------------------------------------------------------ auto-capture
+
+    def _on_event(self, event: Any) -> None:
+        did = _active_decision.get()
+        if isinstance(event, LLMCall):
+            self._append(
+                "llm_call",
+                {
+                    "decision_id": did,
+                    "provider": event.provider,
+                    "model": event.model,
+                    "usage": _jsonable(event.usage),
+                    "cost": _jsonable(event.cost),
+                    "latency_ms": event.latency_ms,
+                    "replayed": event.metadata.get("replayed", False),
+                },
+            )
+        elif isinstance(event, ToolCall):
+            self._append(
+                "tool_call",
+                {"decision_id": did, "name": event.name, "arguments": _jsonable(event.arguments)},
+            )
+        elif hasattr(event, "decisions") and hasattr(event, "budget"):  # contextkit AssemblyReport
+            self._append(
+                "context_assembly",
+                {
+                    "decision_id": did,
+                    "model": getattr(event, "model", None),
+                    "budget": event.budget,
+                    "used": getattr(event, "used", None),
+                    "decisions": _jsonable(event.decisions),
+                },
+            )
+
+    def detach(self) -> None:
+        """Stop subscribing to the core event stream."""
+        if self._on_event in bus._subscribers:
+            bus._subscribers.remove(self._on_event)
+
+    # ------------------------------------------------------------------ explicit events
+
+    @contextmanager
+    def decision(self, input: Any = None, actor: str = "agent") -> Iterator[Decision]:
+        """Group a unit of work. Auto-captured calls inside it are tagged with this decision."""
+        did = uuid.uuid4().hex
+        self._append("decision", {"decision_id": did, "input": _jsonable(input), "actor": actor})
+        token = _active_decision.set(did)
+        try:
+            yield Decision(self, did)
+        finally:
+            _active_decision.reset(token)
+            self._append("decision_end", {"decision_id": did})
+
+    # ------------------------------------------------------------------ export
+
+    def export(self, path: str, framework: str | None = None) -> None:
+        """Write the chain as a JSONL evidence pack, optionally annotated with control IDs."""
+        controls = _CONTROLS.get(framework or "", {})
+        out = Path(path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        with out.open("w", encoding="utf-8") as fh:
+            meta = {
+                "_meta": {
+                    "system": self.system,
+                    "risk_tier": self.risk_tier,
+                    "framework": framework,
+                    "head_hash": self._head,
+                    "entries": len(self.entries),
+                    "disclaimer": "Evidence to support compliance — not legal advice.",
+                }
+            }
+            fh.write(json.dumps(meta, ensure_ascii=False) + "\n")
+            for entry in self.entries:
+                row = dict(entry.__dict__)
+                if framework:
+                    row["controls"] = controls.get(entry.type, [])
+                fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+@dataclass
+class Decision:
+    """Handle for the active decision span (yielded by :meth:`AuditLog.decision`)."""
+
+    log: AuditLog
+    id: str
+
+    def record(self, **fields: Any) -> None:
+        """Record decision metadata (e.g. ``model``, ``prompt_id``)."""
+        self.log._append("decision_record", {"decision_id": self.id, **fields})
+
+    def human_oversight(self, reviewer: str, action: str, note: str = "") -> None:
+        """Record an Art. 14-style human-oversight event: who reviewed, what action, when."""
+        self.log._append(
+            "human_oversight",
+            {"decision_id": self.id, "reviewer": reviewer, "action": action, "note": note},
+        )
+
+
+def verify(path: str) -> tuple[bool, str]:
+    """Re-walk the hash chain in a JSONL file. Returns ``(ok, detail)``. docs/acttrace.md §5."""
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    prev = GENESIS
+    seen = 0
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        row = json.loads(line)
+        if "_meta" in row:  # export header, not a chain entry
+            continue
+        expected = _chain_hash(prev, row["seq"], row["ts"], row["type"], row["payload"])
+        if row["prev_hash"] != prev:
+            return False, f"broken link at seq {row['seq']}: prev_hash mismatch"
+        if row["hash"] != expected:
+            return False, f"tampered entry at seq {row['seq']}: hash mismatch"
+        prev = row["hash"]
+        seen += 1
+    return True, f"ok: {seen} entries, head {prev[:12]}…"

powerailabs_acttrace-0.1.0/src/powerailabs/acttrace/cli.py

@@ -0,0 +1,31 @@
+"""``acttrace`` CLI: an offline verifier for the hash chain. docs/acttrace.md §3.
+
+acttrace verify evidence_q3.jsonl     # exits non-zero if the chain is broken
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import verify
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the ``acttrace`` console script. Returns a process exit code."""
+    parser = argparse.ArgumentParser(prog="acttrace", description="Audit-log tools.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    verify_cmd = sub.add_parser("verify", help="re-walk a JSONL log's hash chain")
+    verify_cmd.add_argument("path", help="path to the .jsonl audit/evidence file")
+
+    args = parser.parse_args(argv)
+    if args.command == "verify":
+        ok, detail = verify(args.path)
+        print(detail)
+        return 0 if ok else 1
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

powerailabs_acttrace-0.1.0/tests/test_acttrace.py

@@ -0,0 +1,118 @@
+"""Auto-populated, hash-chained, tamper-evident audit log. Offline; mock clients only."""
+
+import json
+from types import SimpleNamespace
+
+import pytest
+from powerailabs.acttrace import AuditLog, verify
+from powerailabs.core import bus, instrument
+
+
+@pytest.fixture(autouse=True)
+def _clean_bus():
+    bus._reset()
+    yield
+    bus._reset()
+
+
+def _client():
+    class Completions:
+        def create(self, **kwargs):
+            return SimpleNamespace(usage=SimpleNamespace(prompt_tokens=100, completion_tokens=50))
+
+    return instrument(SimpleNamespace(chat=SimpleNamespace(completions=Completions())))
+
+
+def test_auto_populates_from_instrumented_calls(tmp_path):
+    log = AuditLog(system="loan_triage", risk_tier="high", path=str(tmp_path / "audit.jsonl"))
+    try:
+        client = _client()
+        with log.decision(input={"amount": 5000}, actor="agent") as d:
+            client.chat.completions.create(
+                model="gpt-4o", messages=[{"role": "user", "content": "x"}]
+            )
+            d.record(model="gpt-4o", prompt_id="triage@v3")
+            d.human_oversight(reviewer="ops@bank", action="approved", note="manual check")
+    finally:
+        log.detach()
+
+    types = [e.type for e in log.entries]
+    assert "decision" in types
+    assert "llm_call" in types  # captured with zero per-call wiring
+    assert "human_oversight" in types
+    # the llm_call carries cost + is tagged with the active decision
+    llm = next(e for e in log.entries if e.type == "llm_call")
+    assert llm.payload["cost"] is not None
+    assert llm.payload["decision_id"] is not None
+
+
+def test_chain_verifies_and_detects_tampering(tmp_path):
+    path = tmp_path / "audit.jsonl"
+    log = AuditLog(system="s", path=str(path))
+    try:
+        with log.decision(input="app") as d:
+            d.human_oversight(reviewer="r", action="approved")
+    finally:
+        log.detach()
+
+    ok, detail = verify(str(path))
+    assert ok, detail
+
+    # Tamper: edit a payload in the middle of the chain.
+    lines = path.read_text(encoding="utf-8").splitlines()
+    row = json.loads(lines[1])
+    row["payload"]["actor"] = "HACKED"
+    lines[1] = json.dumps(row)
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+    ok, detail = verify(str(path))
+    assert not ok and "tampered" in detail
+
+
+def test_context_assembly_auto_captured(tmp_path):
+    # contextkit emits an AssemblyReport on the bus; acttrace records it without importing it.
+    from powerailabs.contextkit import Block, Context
+
+    log = AuditLog(system="s", path=str(tmp_path / "a.jsonl"))
+    try:
+        with log.decision(input="q"):
+            ctx = Context(budget_tokens=1000, model="gpt-4o")
+            ctx.add(Block("system", priority=10, role="system"))
+            ctx.assemble()
+    finally:
+        log.detach()
+    assert any(e.type == "context_assembly" for e in log.entries)
+
+
+def test_export_with_control_mapping(tmp_path):
+    log = AuditLog(system="s", risk_tier="high")
+    try:
+        with log.decision(input="x") as d:
+            d.human_oversight(reviewer="r", action="approved")
+    finally:
+        log.detach()
+    out = tmp_path / "evidence.jsonl"
+    log.export(str(out), framework="eu_ai_act")
+
+    rows = [json.loads(ln) for ln in out.read_text(encoding="utf-8").splitlines()]
+    assert "_meta" in rows[0]
+    assert "not legal advice" in rows[0]["_meta"]["disclaimer"].lower()
+    oversight = next(r for r in rows if r.get("type") == "human_oversight")
+    assert oversight["controls"] == ["Art.14 human oversight"]
+    # exported evidence still verifies
+    ok, _ = verify(str(out))
+    assert ok
+
+
+def test_cli_verify(tmp_path, capsys):
+    from powerailabs.acttrace.cli import main
+
+    path = tmp_path / "audit.jsonl"
+    log = AuditLog(system="s", path=str(path))
+    log.detach()
+    assert main(["verify", str(path)]) == 0
+
+    path.write_text(
+        path.read_text(encoding="utf-8").replace('"system"', '"SYSTEM"'), encoding="utf-8"
+    )
+    assert main(["verify", str(path)]) == 1