apex-audit-sdk 0.1.0__tar.gz

apex_audit_sdk-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+.next/
+coverage/
+*.tsbuildinfo
+.env
+.env.local
+.env.*.local
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+.DS_Store
+.venv/
+*.db
+.vercel

apex_audit_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: apex-audit-sdk
+Version: 0.1.0
+Summary: Python capture SDK for the Apex Audit service: hash-at-source, tamper-evident audit trails for AI agent decisions.
+License-Expression: MIT
+Keywords: ai-governance,audit,eu-ai-act,hash-chain,merkle
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: rfc8785>=0.1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# apex-audit-sdk (Python)
+
+Capture SDK for the **Apex Audit** service: tamper-evident, hash-at-source audit
+trails for AI agent decisions, sealed to a public ledger.
+
+Three lines is all an agent loop needs:
+
+```python
+txn = client.open_transaction(name="benefits eligibility review")
+txn.log("reasoning", {"rationale": "Income below threshold; criterion B met."})
+txn.log("output", {"recommendation": "approve", "confidence": 0.94})
+```
+
+Every entry is hashed **on your side** before it leaves the process
+(`sha256` over the RFC 8785 canonical form of
+`{transaction_id, seq, type, payload, prev_hash}`), chained to the previous
+entry, and re-verified by the server on receipt. Nobody — including the
+service — can silently rewrite what your agent did.
+
+## Install
+
+```bash
+pip install apex-audit-sdk            # package name
+python -c "import apex_audit"        # import name
+```
+
+From this repo (development):
+
+```bash
+cd packages/sdk-python
+python3 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+Requires Python >= 3.10. Runtime dependencies: `httpx`, `rfc8785`.
+
+## Quickstart
+
+```python
+from apex_audit import AuditClient
+
+client = AuditClient(
+    api_url="http://localhost:4000",
+    api_key="...",          # sent as Authorization: Bearer <key>
+    timeout=10.0,
+)
+
+txn = client.open_transaction(name="benefits eligibility review")
+txn.log("initiation", {"task": "benefits-eligibility-review", "case_ref": "EU-2026-00441"})
+txn.log("action", {"tool": "case_management.lookup", "applicant_ref": "APP-99182"})
+txn.log("reasoning", {"rationale": "Income below threshold; criterion B met."})
+txn.log("output", {"recommendation": "approve", "confidence": 0.94})
+
+txn.request_review()                                   # status -> in_review
+txn.record_oversight(decision="approved", reviewer="j.okafor",
+                     note="Consistent with policy 2026/14.")
+txn.complete()                                         # status -> complete
+sealed = txn.seal()                                    # Merkle root anchored on-ledger
+print(sealed["merkle_root"], sealed["anchor_topic_id"])
+
+client.close()   # or use:  with AuditClient(...) as client: ...
+```
+
+Context-manager style (opens the transaction on enter; nothing automatic on
+exit — review, completion and sealing stay explicit):
+
+```python
+with client.transaction(name="loan pre-screen") as txn:
+    txn.log("initiation", {...})
+    ...
+```
+
+Entry types are restricted to `initiation`, `action`, `reasoning`,
+`reference`, `output`, `oversight` — anything else raises `ValueError`
+before any network call.
+
+## Error handling
+
+The service reports errors as `{"error": {"code", "message", "details"}}`,
+mapped to exceptions:
+
+```python
+from apex_audit import ApexAPIError, ChainConflictError, EntryHashRejectedError
+
+try:
+    txn.log("action", {"tool": "lookup"})
+except ChainConflictError as e:       # 409 CHAIN_CONFLICT
+    # another writer extended the chain, or a previous attempt landed.
+    print(e.details["expected_seq"], e.details["expected_prev_hash"])
+except EntryHashRejectedError as e:   # 422 ENTRY_HASH_INVALID
+    # client/server canonicalisation disagreement — report it, don't retry.
+    print(e.details["computed_by_server"], e.details["submitted"])
+except ApexAPIError as e:             # everything else
+    print(e.code, e.status, e.message, e.details)
+```
+
+**The SDK never auto-retries POSTs.** Appending an entry is not idempotent:
+if a request times out *after* the server stored it, a blind retry would be
+rejected as `CHAIN_CONFLICT` — and retry loops can mask genuine chain breaks.
+On any failure, local `seq`/`prev_hash` state is left unchanged so you can
+inspect, resynchronise, and retry deliberately.
+
+## Payload rules (the number caveat)
+
+Payloads must be plain JSON: `dict` (string keys) / `list` / `str` / `int` /
+`float` / `bool` / `None`. `NaN`/`Infinity`, sets, datetimes, bytes, Decimals
+etc. raise `ValueError` with the offending path (e.g. `payload.scores[2]`).
+
+**Integers beyond 2^53 − 1 lose precision** once they hit IEEE-754 doubles
+(RFC 8785) and Postgres `jsonb`. The SDK warns (`PayloadPrecisionWarning`)
+and recommends sending such values as strings:
+
+```python
+txn.log("action", {"ledger_ref": str(9007199254740993)})   # exact
+txn.log("action", {"ledger_ref": 9007199254740993})        # warns; value will round
+```
+
+## Verifying later
+
+```python
+data = client.get_transaction(txn_id)    # transaction + ordered entries
+result = client.verify(txn_id)           # recompute + compare with ledger anchor
+                                         # (404 until the service ships verify, M4)
+```
+
+Hash utilities are exported for independent verification:
+
+```python
+from apex_audit import compute_entry_hash, compute_merkle_root, canonicalize, GENESIS_HASH
+```
+
+Full reference: [`docs/sdk/python.md`](../../docs/sdk/python.md).

apex_audit_sdk-0.1.0/README.md

@@ -0,0 +1,133 @@
+# apex-audit-sdk (Python)
+
+Capture SDK for the **Apex Audit** service: tamper-evident, hash-at-source audit
+trails for AI agent decisions, sealed to a public ledger.
+
+Three lines is all an agent loop needs:
+
+```python
+txn = client.open_transaction(name="benefits eligibility review")
+txn.log("reasoning", {"rationale": "Income below threshold; criterion B met."})
+txn.log("output", {"recommendation": "approve", "confidence": 0.94})
+```
+
+Every entry is hashed **on your side** before it leaves the process
+(`sha256` over the RFC 8785 canonical form of
+`{transaction_id, seq, type, payload, prev_hash}`), chained to the previous
+entry, and re-verified by the server on receipt. Nobody — including the
+service — can silently rewrite what your agent did.
+
+## Install
+
+```bash
+pip install apex-audit-sdk            # package name
+python -c "import apex_audit"        # import name
+```
+
+From this repo (development):
+
+```bash
+cd packages/sdk-python
+python3 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+Requires Python >= 3.10. Runtime dependencies: `httpx`, `rfc8785`.
+
+## Quickstart
+
+```python
+from apex_audit import AuditClient
+
+client = AuditClient(
+    api_url="http://localhost:4000",
+    api_key="...",          # sent as Authorization: Bearer <key>
+    timeout=10.0,
+)
+
+txn = client.open_transaction(name="benefits eligibility review")
+txn.log("initiation", {"task": "benefits-eligibility-review", "case_ref": "EU-2026-00441"})
+txn.log("action", {"tool": "case_management.lookup", "applicant_ref": "APP-99182"})
+txn.log("reasoning", {"rationale": "Income below threshold; criterion B met."})
+txn.log("output", {"recommendation": "approve", "confidence": 0.94})
+
+txn.request_review()                                   # status -> in_review
+txn.record_oversight(decision="approved", reviewer="j.okafor",
+                     note="Consistent with policy 2026/14.")
+txn.complete()                                         # status -> complete
+sealed = txn.seal()                                    # Merkle root anchored on-ledger
+print(sealed["merkle_root"], sealed["anchor_topic_id"])
+
+client.close()   # or use:  with AuditClient(...) as client: ...
+```
+
+Context-manager style (opens the transaction on enter; nothing automatic on
+exit — review, completion and sealing stay explicit):
+
+```python
+with client.transaction(name="loan pre-screen") as txn:
+    txn.log("initiation", {...})
+    ...
+```
+
+Entry types are restricted to `initiation`, `action`, `reasoning`,
+`reference`, `output`, `oversight` — anything else raises `ValueError`
+before any network call.
+
+## Error handling
+
+The service reports errors as `{"error": {"code", "message", "details"}}`,
+mapped to exceptions:
+
+```python
+from apex_audit import ApexAPIError, ChainConflictError, EntryHashRejectedError
+
+try:
+    txn.log("action", {"tool": "lookup"})
+except ChainConflictError as e:       # 409 CHAIN_CONFLICT
+    # another writer extended the chain, or a previous attempt landed.
+    print(e.details["expected_seq"], e.details["expected_prev_hash"])
+except EntryHashRejectedError as e:   # 422 ENTRY_HASH_INVALID
+    # client/server canonicalisation disagreement — report it, don't retry.
+    print(e.details["computed_by_server"], e.details["submitted"])
+except ApexAPIError as e:             # everything else
+    print(e.code, e.status, e.message, e.details)
+```
+
+**The SDK never auto-retries POSTs.** Appending an entry is not idempotent:
+if a request times out *after* the server stored it, a blind retry would be
+rejected as `CHAIN_CONFLICT` — and retry loops can mask genuine chain breaks.
+On any failure, local `seq`/`prev_hash` state is left unchanged so you can
+inspect, resynchronise, and retry deliberately.
+
+## Payload rules (the number caveat)
+
+Payloads must be plain JSON: `dict` (string keys) / `list` / `str` / `int` /
+`float` / `bool` / `None`. `NaN`/`Infinity`, sets, datetimes, bytes, Decimals
+etc. raise `ValueError` with the offending path (e.g. `payload.scores[2]`).
+
+**Integers beyond 2^53 − 1 lose precision** once they hit IEEE-754 doubles
+(RFC 8785) and Postgres `jsonb`. The SDK warns (`PayloadPrecisionWarning`)
+and recommends sending such values as strings:
+
+```python
+txn.log("action", {"ledger_ref": str(9007199254740993)})   # exact
+txn.log("action", {"ledger_ref": 9007199254740993})        # warns; value will round
+```
+
+## Verifying later
+
+```python
+data = client.get_transaction(txn_id)    # transaction + ordered entries
+result = client.verify(txn_id)           # recompute + compare with ledger anchor
+                                         # (404 until the service ships verify, M4)
+```
+
+Hash utilities are exported for independent verification:
+
+```python
+from apex_audit import compute_entry_hash, compute_merkle_root, canonicalize, GENESIS_HASH
+```
+
+Full reference: [`docs/sdk/python.md`](../../docs/sdk/python.md).

apex_audit_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apex-audit-sdk"
+version = "0.1.0"
+description = "Python capture SDK for the Apex Audit service: hash-at-source, tamper-evident audit trails for AI agent decisions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["audit", "ai-governance", "hash-chain", "merkle", "eu-ai-act"]
+dependencies = [
+    "httpx>=0.27",
+    "rfc8785>=0.1.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apex_audit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

apex_audit_sdk-0.1.0/scripts/bootstrap_env.py

@@ -0,0 +1,39 @@
+"""Dev bootstrap: create .venv for the SDK and install it editable with dev extras.
+
+Usage: python3 scripts/bootstrap_env.py
+Equivalent to:
+    python3 -m venv .venv && .venv/bin/python -m pip install -e ".[dev]"
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import venv
+from pathlib import Path
+
+PKG_DIR = Path(__file__).resolve().parents[1]
+VENV_DIR = PKG_DIR / ".venv"
+
+
+def main() -> int:
+    if not (VENV_DIR / "bin" / "python").exists():
+        print(f"creating venv at {VENV_DIR}", flush=True)
+        venv.create(VENV_DIR, with_pip=True)
+    else:
+        print(f"venv already exists at {VENV_DIR}", flush=True)
+
+    cmd = [
+        str(VENV_DIR / "bin" / "python"),
+        "-m",
+        "pip",
+        "install",
+        "-e",
+        f"{PKG_DIR}[dev]",
+    ]
+    print("running:", " ".join(cmd), flush=True)
+    return subprocess.call(cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

apex_audit_sdk-0.1.0/src/apex_audit/__init__.py

@@ -0,0 +1,44 @@
+"""Apex Audit capture SDK for Python.
+
+Hash-at-source, tamper-evident audit trails for AI agent decisions::
+
+    from apex_audit import AuditClient
+
+    client = AuditClient(api_url="http://localhost:4000", api_key="...")
+    txn = client.open_transaction(name="benefits eligibility review")
+    txn.log("initiation", {"task": "benefits-eligibility-review"})
+
+See ``docs/sdk/python.md`` for the full reference.
+"""
+
+from __future__ import annotations
+
+from ._canonical import canonicalize
+from ._validation import MAX_SAFE_INTEGER, validate_payload
+from .client import AuditClient, AuditTransaction
+from .errors import (
+    ApexAPIError,
+    ChainConflictError,
+    EntryHashRejectedError,
+    PayloadPrecisionWarning,
+)
+from .hashing import ENTRY_TYPES, GENESIS_HASH, compute_entry_hash, compute_merkle_root
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApexAPIError",
+    "AuditClient",
+    "AuditTransaction",
+    "ChainConflictError",
+    "ENTRY_TYPES",
+    "EntryHashRejectedError",
+    "GENESIS_HASH",
+    "MAX_SAFE_INTEGER",
+    "PayloadPrecisionWarning",
+    "__version__",
+    "canonicalize",
+    "compute_entry_hash",
+    "compute_merkle_root",
+    "validate_payload",
+]

apex_audit_sdk-0.1.0/src/apex_audit/_canonical.py

@@ -0,0 +1,39 @@
+"""RFC 8785 (JCS) canonicalisation.
+
+The Apex hash spec (decision 0007) defines the entry hash over the JCS
+canonical form of the entry record. This module is the single place the SDK
+turns a Python value into canonical bytes; everything hash-related goes
+through :func:`canonicalize`.
+
+The implementation delegates to the Trail of Bits ``rfc8785`` package, which
+is proven byte-for-byte against the cross-language vectors in
+``packages/core/test/fixtures/vectors.json`` (see ``tests/test_vectors.py``).
+If that package ever becomes unusable, replace the import below with a local
+``_jcs`` module — the vectors, not the library, are the source of truth.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import rfc8785
+
+__all__ = ["canonicalize"]
+
+
+def canonicalize(value: Any) -> bytes:
+    """Return the RFC 8785 (JCS) canonical UTF-8 encoding of ``value``.
+
+    ``value`` must be a plain JSON-representable Python value (dict with
+    string keys, list, str, int, float, bool, None). Callers are expected to
+    run :func:`apex_audit._validation.validate_payload` first for friendly,
+    path-annotated errors; anything the canonicaliser still rejects (e.g.
+    integers outside the IEEE-754 safe range, which RFC 8785 cannot
+    represent exactly) is re-raised as :class:`ValueError`.
+    """
+    try:
+        return bytes(rfc8785.dumps(value))
+    except ValueError:
+        raise
+    except Exception as exc:  # rfc8785 CanonicalizationError subclasses, TypeError
+        raise ValueError(f"value is not canonicalisable per RFC 8785: {exc}") from exc

apex_audit_sdk-0.1.0/src/apex_audit/_validation.py

@@ -0,0 +1,84 @@
+"""Payload validation, run before any payload is hashed or transmitted.
+
+Rules (decisions 0007/0008):
+
+- Only plain JSON values are allowed anywhere in the tree: ``dict`` (string
+  keys), ``list``, ``str``, ``int``, ``float``, ``bool``, ``None``.
+  Anything else (sets, tuples, datetimes, bytes, Decimals, custom objects)
+  raises :class:`ValueError` naming the offending path.
+- ``NaN``, ``Infinity`` and ``-Infinity`` floats raise :class:`ValueError`
+  (they are not JSON and not canonicalisable).
+- Integers with absolute value above ``2**53 - 1`` trigger a
+  :class:`~apex_audit.errors.PayloadPrecisionWarning`: Postgres ``jsonb``
+  and IEEE-754 doubles cannot represent them exactly, so the recommendation
+  is to send them as strings.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from typing import Any
+
+from .errors import PayloadPrecisionWarning
+
+__all__ = ["MAX_SAFE_INTEGER", "validate_payload"]
+
+MAX_SAFE_INTEGER = 2**53 - 1
+"""Largest integer exactly representable as an IEEE-754 double (9007199254740991)."""
+
+
+def validate_payload(payload: Any, *, root: str = "payload") -> None:
+    """Validate that ``payload`` is plain, canonicalisable JSON.
+
+    Raises:
+        ValueError: for NaN/Infinity floats, non-string object keys, or any
+            non-JSON type, with the path of the offending value
+            (e.g. ``payload.applicant.scores[2]``).
+
+    Warns:
+        PayloadPrecisionWarning: for integers ``|n| > 2**53 - 1`` anywhere in
+            the tree — they lose precision in jsonb / IEEE-754 doubles
+            (decision 0008); send such values as strings.
+    """
+    _validate(payload, root)
+
+
+def _validate(value: Any, path: str) -> None:
+    # bool must be checked before int (bool is an int subclass).
+    if value is None or isinstance(value, (bool, str)):
+        return
+    if isinstance(value, int):
+        if abs(value) > MAX_SAFE_INTEGER:
+            warnings.warn(
+                f"{path}: integer {value} exceeds 2**53 - 1 and will lose "
+                "precision in JSON number representations (IEEE-754 / "
+                "Postgres jsonb). Send it as a string to preserve it exactly.",
+                PayloadPrecisionWarning,
+                stacklevel=4,
+            )
+        return
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise ValueError(
+                f"{path}: {value!r} is not valid JSON — NaN and Infinity "
+                "cannot be canonicalised or stored"
+            )
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValueError(
+                    f"{path}: object key {key!r} ({type(key).__name__}) is "
+                    "not a string — JSON object keys must be strings"
+                )
+            _validate(item, f"{path}.{key}")
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            _validate(item, f"{path}[{index}]")
+        return
+    raise ValueError(
+        f"{path}: value of type {type(value).__name__} is not "
+        "JSON-serialisable — use dict/list/str/int/float/bool/None"
+    )