Metadata-Version: 2.4
Name: forgesight-audit
Version: 0.1.1
Summary: ForgeSight audit trail — a tamper-evident, hash-chained, complete-capture projection of agent telemetry with a compliance query/export surface.
Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
Project-URL: Repository, https://github.com/Scaffoldic/forgesight
Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
Author: kjoshi
License-Expression: Apache-2.0
Keywords: ai-agents,audit,compliance,forgesight,governance,observability
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: forgesight-core
Description-Content-Type: text/markdown

# forgesight-audit

A **tamper-evident, complete-capture audit trail** for ForgeSight — a governance-grade
projection of the telemetry the SDK already emits ([feat-023](../../docs/features/feat-023-tamper-evident-audit-trail.md)).

It adds the three things ordinary telemetry lacks:

- **Integrity** — every `AuditEvent` is hash-chained (`prev_hash`/`hash`); `verify()` walks
  the chain so deletion, alteration, or reordering is detectable.
- **Complete capture** — it rides the event bus, so it records every run *even when the
  trace was head-sampled out* of the exporters.
- **A compliance query/export surface** — query by principal / team / kind / time, roll up
  cost, and export an auditor bundle (JSONL + a manifest carrying the head hash).

```python
import forgesight
from forgesight_audit import AuditListener, JsonlAuditSink, AuditQuery, verify

sink = JsonlAuditSink("audit/agent-audit.jsonl")
forgesight.configure(sample_rate=0.1, listeners=[AuditListener(sink)])  # 10% traces, 100% audit

# ... run agents as usual; audit events are recorded at source ...

assert verify(sink).intact                       # prove the log wasn't altered
report = sink.query(AuditQuery(principal="clinician-bot"))
print(report.event_count, report.cost_usd_total)
sink.export(AuditQuery(), to="audit/full.bundle") # JSONL + .manifest.json(head_hash)
```

**Drivers:** `jsonl` (default), `sqlite`, `otel` (emit as OTel log records), `siem`
(JSON lines to a syslog/collector). **Wire it** as a listener (above), via
`configure(listeners=["audit"])`, or `forgesight_audit.install({...})` after `configure()`.

It records — it does not enforce. Policy/budget enforcement is `forgesight-governance`.
Apache-2.0.
