Metadata-Version: 2.4
Name: arcaeon-audit
Version: 0.1.1
Summary: Tamper-evident, audit-ready logs for AI agents — ISO 42001 / SOC 2 / EU AI Act evidence. Prove what your agent did.
Author: Arcaeon
License: MIT
Project-URL: Homepage, https://arcaeon.io
Project-URL: Source, https://github.com/dan8433-user/arcaeon-audit
Keywords: ai,agent,audit,audit-log,tamper-evident,provenance,eu-ai-act,article-12,compliance,hash-chain,observability
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: arcaeon-ledger>=0.5.1

# arcaeon-audit

**Tamper-evident, audit-ready logs for AI agents.**
*Observability shows you what your agent did. This lets you **prove** it wasn't altered —
the evidence your ISO 42001 / SOC 2 auditor (and, by 2027, the EU AI Act) asks for.*

```bash
pip install arcaeon-audit
```

## Why this exists

If you ship an AI agent into anything regulated or enterprise-sold, you're already
being asked to **keep records of what it did and produce them on demand** — by your
**SOC 2** auditor, by **ISO/IEC 42001** (Annex A.6.2.8: keep AI event logs across the
lifecycle), and by the security/AI-governance questionnaires your enterprise customers
send *today*. The **EU AI Act, Article 12** adds a hard tamper-evident-logging
mandate for high-risk systems from **2 December 2027** (Digital Omnibus, Reg. (EU)
2026/1744; penalties to €35M or 7% of revenue).

Almost all of that forces you to *keep* records. Almost none of it is satisfied by a
plain log file — anyone with write access can edit, delete, or reorder a past record
and nothing shows. What auditors and regulators want is an **append-only,
integrity-protected** record you can hand over and have *independently verified*.
That integrity layer — the provable part — is exactly what this gives you.

A normal log file doesn't meet the bar: anyone with write access can edit,
delete, or reorder a past record and nothing shows. The regulators' expectation
is an **append-only, integrity-protected** record — in practice, a hash chain.

`arcaeon-audit` is the small, boring, correct layer that gives you exactly that,
in two lines and a folder. It wraps [`arcaeon-ledger`](https://pypi.org/project/arcaeon-ledger/)
(a hash-chained append-only log, zero heavy deps) with the event vocabulary and
the **regulator-ready export** that Article 12 asks for.

## Use

```python
from arcaeon_audit import AuditLog

log = AuditLog("agent-audit.jsonl", system_id="triage-agent-v3", provider="Acme AI")

log.record(event="system_start", agent="triage-agent-v3")
log.record(event="input",  agent="triage-agent-v3", inputs={"patient_msg": "chest pain"})
log.record(event="decision", agent="triage-agent-v3", decision="escalate",
           outputs={"routed_to": "ER", "priority": 1}, capability_version="v2")

log.verify().ok            # True — any edit to history would make this False
log.export_bundle("audit-export/")   # regulator-ready folder
```

`export_bundle()` writes a self-verifying folder:

| file | what it is |
|------|------------|
| `records.jsonl` | the full hash-chained audit log, verbatim |
| `integrity.json` | verification result — ok?, row count, exact first break if any |
| `manifest.json` | system id, provider, period covered, counts by event type |
| `ARTICLE_12_SUMMARY.md` | human-readable mapping to Article 12's requirements |

The bundle is **self-verifying**: `records.jsonl` is hash-chained, so anyone can
re-run `arcaeon-ledger`'s `verify_file()` and reproduce `integrity.json`. Tamper
evidence does not depend on trusting this tool or its author — that's the point.

## CLI

```bash
arcaeon-audit verify  agent-audit.jsonl
arcaeon-audit export  agent-audit.jsonl audit-export/ --system-id triage-v3 --provider "Acme AI"
```

## What this is and isn't

**Is:** an engineering control that produces automatic, tamper-evident, exportable
records — the integrity + export primitive Article 12 leans on.

**Isn't:** legal advice, and not compliance-in-a-box on its own. Article 12
compliance also depends on **what** you choose to log and your broader obligations
under the Act. This tool gives you the hard part (provable integrity + a clean
export); the coverage is yours to define.

## How it works

Every record is hash-chained: `chain = sha256(prev_chain + canonical(row))`. Edit,
delete, or reorder any record and every later link breaks; `verify()` names the
exact row. Records also carry an `authority` block (principal + capability version)
so "was this edited?" sharpens to "was this edited **and** was the writer authorized?"

MIT licensed. Built by [Arcaeon](https://arcaeon.io) — the evidence layer for AI.
