AI system governance logger with prompt, response, and model lineage tracking.
Provides immutable, hash-chained audit logging for AI systems with model lineage tracking, compliance reporting, role-based access control, and GDPR-compatible data management.
+------------------------------------------------------------------+
| AuditTrail |
+------------------------------------------------------------------+
| |
| +------------------+ +------------------+ |
| | CLI (Click) | | Python API | |
| | audittrail log | | AuditLogger() | |
| | audittrail query| | QueryEngine() | |
| | audittrail verify | AccessControl() | |
| | audittrail report | Compliance() | |
| | audittrail lineage | Retention() | |
| +--------+---------+ +--------+---------+ |
| | | |
| v v |
| +------------------------------------------------+ |
| | Core Event Logger | |
| | - Append-only JSONL storage | |
| | - SHA-256 hash chain (tamper detection) | |
| | - Thread-safe writes | |
| +------------------------+-----------------------+ |
| | |
| +---------------+---------------+ |
| | | | |
| v v v |
| +----------------+ +----------+ +------------------+ |
| | Model Lineage | | Access | | Retention | |
| | - Dataset reg | | Control | | - Auto-archival | |
| | - Training runs| | - RBAC | | - GDPR deletion | |
| | - Model vers | | - Tokens | | - Policy engine | |
| | - DAG visual | | - Audit | | - Chain rebuild | |
| +----------------+ +----------+ +------------------+ |
| | | |
| v v |
| +----------------+ +------------------+ |
| | Compliance | | Query Engine | |
| | Reporter | | - Time range | |
| | - Model inv. | | - Filter by model| |
| | - Usage stats | | - Filter by user | |
| | - Safety rpt | | - Full-text srch | |
| | - Chain verify | | - Aggregations | |
| +----------------+ +------------------+ |
| |
+------------------------------------------------------------------+
| Storage: audit.jsonl (append-only, hash-chained) |
+------------------------------------------------------------------+
pip install .For development:
pip install -e ".[dev]"from audittrail import AuditLogger, EventType
logger = AuditLogger("audit.jsonl")
# Log an AI interaction
event = logger.log(
EventType.PROMPT,
model_id="gpt-4",
model_version="4.0",
user_id="user-001",
prompt="What is machine learning?",
response="Machine learning is a subset of AI...",
latency_ms=150.5,
input_tokens=10,
output_tokens=50,
)
# Verify chain integrity
is_valid, errors = logger.verify_chain()# Log an event
audittrail log -t prompt -m gpt-4 -u user-001 -p "What is AI?"
# Query events
audittrail query -t prompt -m gpt-4
audittrail query --text "machine learning" --limit 10
audittrail query --count-only
# Verify hash chain integrity
audittrail verify
# Generate compliance reports
audittrail report --type full
audittrail report --type safety --start 2026-01-01T00:00:00+00:00
audittrail report --type usage
# View model lineage
audittrail lineage
audittrail lineage --show-dagImmutable append-only log with SHA-256 hash chain. Every event is cryptographically linked to its predecessor, enabling tamper detection.
Track the full provenance of AI models: datasets -> training runs -> model versions -> deployments. DAG visualization for audit trails.
from audittrail import LineageTracker, Dataset, TrainingRun, ModelVersion
tracker = LineageTracker()
ds = Dataset(name="training-data", version="1.0", record_count=100000)
tracker.register_dataset(ds)
run = TrainingRun(model_name="my-model", dataset_ids=[ds.dataset_id])
tracker.register_training_run(run)
model = ModelVersion(model_name="my-model", version="1.0", training_run_id=run.run_id)
tracker.register_model_version(model)
tracker.deploy_model(model.model_id)Role-based access: admin, auditor, viewer. Token-based authentication with automatic expiration and revocation tracking.
from audittrail import AccessController, Role
ac = AccessController()
token = ac.grant_access("user-001", Role.AUDITOR)
assert ac.check_permission(token, "read_events")
assert not ac.check_permission(token, "delete_data")Time-range queries, filter by model/user/event type, full-text search on prompts and responses, aggregation by model or user.
from audittrail import QueryEngine, EventType
engine = QueryEngine(logger)
results = engine.query(
event_types=[EventType.PROMPT],
model_id="gpt-4",
text_search="machine learning",
limit=10,
)Generate audit reports: model inventory, usage statistics, safety incidents, data lineage summary, and hash chain integrity verification.
from audittrail import ComplianceReporter
reporter = ComplianceReporter(logger, lineage_tracker)
report = reporter.generate_full_report()Configurable retention periods, automatic archival, GDPR-compatible data deletion that redacts personal data while preserving audit trail structure and hash chain integrity.
from audittrail import RetentionManager, RetentionPolicy
policy = RetentionPolicy(name="production", retention_days=365, archive_path="./archive")
manager = RetentionManager(logger, policy)
manager.apply_retention()
manager.gdpr_delete("user-001")# Build
docker compose build
# Run all services
docker compose up
# Log an event
docker compose run logger log -t prompt -m gpt-4 -p "test"
# Query events
docker compose run query-api# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest -v
# Lint
ruff check src/ tests/
ruff format src/ tests/MIT License (c) 2026 Corey Wade