aiauditlog 0.1.0a3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. aiauditlog-0.1.0a3/.gitignore +17 -0
  2. aiauditlog-0.1.0a3/CHANGELOG.md +21 -0
  3. aiauditlog-0.1.0a3/LICENSE +21 -0
  4. aiauditlog-0.1.0a3/PKG-INFO +299 -0
  5. aiauditlog-0.1.0a3/README.md +259 -0
  6. aiauditlog-0.1.0a3/docs/api.md +22 -0
  7. aiauditlog-0.1.0a3/docs/cli.md +26 -0
  8. aiauditlog-0.1.0a3/docs/event-envelope.md +17 -0
  9. aiauditlog-0.1.0a3/docs/getting-started.md +40 -0
  10. aiauditlog-0.1.0a3/docs/interoperability.md +24 -0
  11. aiauditlog-0.1.0a3/docs/roadmap.md +43 -0
  12. aiauditlog-0.1.0a3/docs/security.md +33 -0
  13. aiauditlog-0.1.0a3/examples/basic/event.json +57 -0
  14. aiauditlog-0.1.0a3/examples/basic/legacy-event.json +19 -0
  15. aiauditlog-0.1.0a3/examples/privacy/minimal.yaml +18 -0
  16. aiauditlog-0.1.0a3/examples/tampered/README.md +5 -0
  17. aiauditlog-0.1.0a3/pyproject.toml +105 -0
  18. aiauditlog-0.1.0a3/src/ai_audit_log/__init__.py +45 -0
  19. aiauditlog-0.1.0a3/src/ai_audit_log/adapters.py +35 -0
  20. aiauditlog-0.1.0a3/src/ai_audit_log/builder.py +48 -0
  21. aiauditlog-0.1.0a3/src/ai_audit_log/canonical.py +60 -0
  22. aiauditlog-0.1.0a3/src/ai_audit_log/chain.py +99 -0
  23. aiauditlog-0.1.0a3/src/ai_audit_log/checkpoint.py +80 -0
  24. aiauditlog-0.1.0a3/src/ai_audit_log/checkpoint_policy.py +78 -0
  25. aiauditlog-0.1.0a3/src/ai_audit_log/cli.py +337 -0
  26. aiauditlog-0.1.0a3/src/ai_audit_log/compression.py +29 -0
  27. aiauditlog-0.1.0a3/src/ai_audit_log/constants.py +127 -0
  28. aiauditlog-0.1.0a3/src/ai_audit_log/digest.py +36 -0
  29. aiauditlog-0.1.0a3/src/ai_audit_log/ecosystem.py +111 -0
  30. aiauditlog-0.1.0a3/src/ai_audit_log/exceptions.py +25 -0
  31. aiauditlog-0.1.0a3/src/ai_audit_log/exports.py +75 -0
  32. aiauditlog-0.1.0a3/src/ai_audit_log/ids.py +22 -0
  33. aiauditlog-0.1.0a3/src/ai_audit_log/migration.py +47 -0
  34. aiauditlog-0.1.0a3/src/ai_audit_log/models.py +330 -0
  35. aiauditlog-0.1.0a3/src/ai_audit_log/otel.py +29 -0
  36. aiauditlog-0.1.0a3/src/ai_audit_log/privacy.py +162 -0
  37. aiauditlog-0.1.0a3/src/ai_audit_log/py.typed +1 -0
  38. aiauditlog-0.1.0a3/src/ai_audit_log/query.py +33 -0
  39. aiauditlog-0.1.0a3/src/ai_audit_log/recorder.py +53 -0
  40. aiauditlog-0.1.0a3/src/ai_audit_log/reports.py +70 -0
  41. aiauditlog-0.1.0a3/src/ai_audit_log/rotation.py +70 -0
  42. aiauditlog-0.1.0a3/src/ai_audit_log/schema.py +31 -0
  43. aiauditlog-0.1.0a3/src/ai_audit_log/schemas/audit-event-v1.schema.json +804 -0
  44. aiauditlog-0.1.0a3/src/ai_audit_log/signatures.py +133 -0
  45. aiauditlog-0.1.0a3/src/ai_audit_log/storage.py +237 -0
  46. aiauditlog-0.1.0a3/src/ai_audit_log/time.py +38 -0
  47. aiauditlog-0.1.0a3/tests/test_core.py +202 -0
  48. aiauditlog-0.1.0a3/tests/test_roadmap_a2_a3.py +187 -0
@@ -0,0 +1,17 @@
1
+ build/
2
+ dist/
3
+ *.egg-info/
4
+ .coverage
5
+ .mypy_cache/
6
+ .pytest_cache/
7
+ .ruff_cache/
8
+ __pycache__/
9
+ *.py[cod]
10
+ *.db
11
+ *.sqlite
12
+ *.jsonl
13
+ *.pem
14
+ .env
15
+ .venv/
16
+ venv/
17
+ htmlcov/
@@ -0,0 +1,21 @@
1
+ # Changelog
2
+
3
+ All notable changes to AIAuditLog are documented here.
4
+
5
+ ## 0.1.0a3 - Unreleased
6
+
7
+ - Add a versioned, typed audit-event envelope and packaged JSON Schema.
8
+ - Add RFC 8785-backed serialization after AIAuditLog-specific value normalization.
9
+ - Add SHA-256 event digests, optional hash chains, stream verification, and checkpoints.
10
+ - Add optional Ed25519 checkpoint signatures and signature policies.
11
+ - Add JSONL storage, optional SQLite indexing, querying, summaries, rotation, and migration helpers.
12
+ - Add privacy profiles, heuristic secret filtering and classification redaction.
13
+ - Add JSON, JSONL, CSV-safe, Markdown, redacted, and deterministic gzip exports.
14
+ - Add W3C Trace Context helpers and neutral dictionary-based ecosystem adapters.
15
+ - Add the `aiaudit` CLI and typed Python API.
16
+
17
+ This is alpha software. Hash chaining is tamper-evident, not immutable. Signatures
18
+ authenticate bytes to a key but do not prove real-world identity or legal
19
+ non-repudiation. Privacy filtering is heuristic. This release does not provide
20
+ automatic compliance, immutable storage, trusted timestamping, or external
21
+ anchoring. Neutral adapters have not been tested against sibling packages.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 sekacorn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,299 @@
1
+ Metadata-Version: 2.4
2
+ Name: aiauditlog
3
+ Version: 0.1.0a3
4
+ Summary: A vendor-neutral, tamper-evident audit-event format and local toolkit for AI systems and agents.
5
+ Project-URL: Homepage, https://github.com/sekacorn/AIAuditLog
6
+ Project-URL: Repository, https://github.com/sekacorn/AIAuditLog
7
+ Project-URL: Issues, https://github.com/sekacorn/AIAuditLog/issues
8
+ Project-URL: Documentation, https://github.com/sekacorn/AIAuditLog/tree/main/docs
9
+ Author: sekacorn
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Security
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Classifier: Topic :: System :: Logging
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: <3.14,>=3.11
24
+ Requires-Dist: cryptography>=48.0.1
25
+ Requires-Dist: pydantic>=2.7
26
+ Requires-Dist: pyyaml>=6
27
+ Requires-Dist: rfc8785>=0.1.4
28
+ Requires-Dist: typer>=0.12
29
+ Provides-Extra: dev
30
+ Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
31
+ Requires-Dist: build>=1.2; extra == 'dev'
32
+ Requires-Dist: mypy>=1.10; extra == 'dev'
33
+ Requires-Dist: pip-audit>=2.7; extra == 'dev'
34
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
35
+ Requires-Dist: pytest>=9.0.3; extra == 'dev'
36
+ Requires-Dist: ruff>=0.5; extra == 'dev'
37
+ Requires-Dist: twine>=5; extra == 'dev'
38
+ Requires-Dist: types-pyyaml>=6; extra == 'dev'
39
+ Description-Content-Type: text/markdown
40
+
41
+ # AIAuditLog
42
+
43
+ AIAuditLog provides portable, privacy-aware, tamper-evident evidence for AI
44
+ models, agents, tools, policies, reviews, and workflow outcomes.
45
+
46
+ This is an alpha release candidate for `0.1.0a3`. It is ready for public alpha
47
+ release with documented limitations, not production certification.
48
+
49
+ ## Why AI Audit Logs Are Different
50
+
51
+ Ordinary application logs usually explain what software printed while it ran.
52
+ AI audit evidence must also preserve model choices, tool access, policy
53
+ decisions, human approvals, data references, redaction decisions, and workflow
54
+ outcomes in a vendor-neutral format that survives framework and provider
55
+ changes.
56
+
57
+ ## Problem Statement
58
+
59
+ Organizations need inspectable evidence of what an AI system did, why it acted,
60
+ which models and policies were involved, what data and tools were accessed, and
61
+ what outcome occurred. AIAuditLog keeps that evidence local-first, append
62
+ oriented, deterministic, and suitable for CI review.
63
+
64
+ ## Ecosystem Position
65
+
66
+ AIAuditLog is project six in the sekacorn AI infrastructure roadmap. It is
67
+ designed for future optional integration with Forge, PrivateAIStack,
68
+ ModelSwapBench, OpenOntologyLite, AgentPolicyPack, and OpenAIMeter. The first
69
+ alpha works independently and offline.
70
+
71
+ ## Core Capabilities
72
+
73
+ - Versioned JSON event envelope and JSON Schema export.
74
+ - Typed Python models for AI, agent, tool, policy, ontology, and benchmark context.
75
+ - RFC8785-backed canonical JSON after AIAuditLog value normalization.
76
+ - SHA-256 event digests.
77
+ - Optional hash-chain metadata for tamper evidence.
78
+ - Checkpoints, optional Ed25519 checkpoint signatures, and signature policies.
79
+ - JSONL storage and SQLite indexing.
80
+ - Stream rotation, lock-file guarded appends, compressed exports, and schema migration helpers.
81
+ - Privacy modes, deterministic redaction, secret-key filtering, classification redaction, and CSV-safe export.
82
+ - CLI and Python API.
83
+ - Neutral adapter protocols for future ecosystem packages.
84
+
85
+ ## Event Architecture
86
+
87
+ Each event contains `schema_version`, `event_id`, `event_type`, UTC
88
+ `event_time`, UTC `recorded_time`, `source`, `actor`, `outcome`, `data`,
89
+ optional context, and `integrity`. Core event types cover system, agent, model,
90
+ tool, data, retrieval, policy, review, security, evaluation, benchmark, and
91
+ audit-log lifecycle categories. Custom event types must be namespaced and may
92
+ not collide with reserved core namespaces.
93
+
94
+ ## Installation
95
+
96
+ ```powershell
97
+ python -m pip install aiauditlog
98
+ ```
99
+
100
+ For development:
101
+
102
+ ```powershell
103
+ python -m pip install -e ".[dev]"
104
+ ```
105
+
106
+ ## Quick Start
107
+
108
+ ```powershell
109
+ aiaudit validate examples/basic/event.json
110
+ aiaudit append build/audit.jsonl --event examples/basic/event.json
111
+ aiaudit verify build/audit.jsonl
112
+ aiaudit summarize build/audit.jsonl
113
+ ```
114
+
115
+ ## JSON Event Example
116
+
117
+ See `examples/basic/event.json` for a complete model invocation event. Prompts
118
+ and responses are not stored by default; use hashes, references, counts, and
119
+ explicitly configured safe excerpts.
120
+
121
+ ## Recorder Example
122
+
123
+ ```python
124
+ from ai_audit_log import AuditRecorder, EventBuilder, JsonlStore, Outcome, Source
125
+ from ai_audit_log.models import Actor
126
+
127
+ builder = EventBuilder(
128
+ source=Source(service="claims-agent"),
129
+ actor=Actor(actor_id="agent-17", actor_type="ai_agent"),
130
+ )
131
+ recorder = AuditRecorder(builder=builder, store=JsonlStore("build/audit.jsonl"))
132
+ recorder.record(
133
+ event_type="model.invocation.completed",
134
+ outcome=Outcome(status="success", code="COMPLETED"),
135
+ data={"provider": "example", "model_name": "example-model"},
136
+ )
137
+ ```
138
+
139
+ ## Chain Verification
140
+
141
+ ```powershell
142
+ aiaudit verify build/audit.jsonl
143
+ ```
144
+
145
+ Hash chaining is tamper-evident, not immutable. An attacker who can rewrite an
146
+ entire unsigned log can recompute the chain.
147
+
148
+ ## Privacy Modes
149
+
150
+ The default mode is `minimal`: identifiers, metadata, hashes, counts, outcomes,
151
+ and policy evidence are preserved, while prompts, responses, and common secret
152
+ keys are redacted. `balanced` may keep short configured excerpts.
153
+ `full-content` requires explicit opt-in and can expose sensitive data.
154
+
155
+ ## Checkpoints And Signatures
156
+
157
+ Checkpoints summarize stream ID, event count, terminal digest, and checkpoint
158
+ digest. Ed25519 signatures authenticate the checkpoint bytes to a public key,
159
+ and checkpoint signature policies can require allowed key IDs, fingerprints, and
160
+ minimum signature counts. Signatures do not prove real-world actor identity,
161
+ legal non-repudiation, or correct key custody.
162
+
163
+ ```powershell
164
+ aiaudit checkpoint create build/audit.jsonl --output build/checkpoint.json
165
+ aiaudit key generate --private-key build/development-private.pem --public-key build/development-public.pem
166
+ aiaudit sign build/checkpoint.json --private-key build/development-private.pem --key-id development-key
167
+ aiaudit signature verify build/checkpoint.json --public-key build/development-public.pem
168
+ ```
169
+
170
+ Never commit generated private keys.
171
+
172
+ ## CLI Examples
173
+
174
+ ```powershell
175
+ aiaudit inspect examples/basic/event.json
176
+ aiaudit query build/audit.jsonl --event-type model.invocation.completed
177
+ aiaudit export build/audit.jsonl --format markdown --output build/audit-report.md --compress
178
+ aiaudit redact build/audit.jsonl --profile examples/privacy/minimal.yaml --output build/audit-redacted.jsonl
179
+ aiaudit migrate examples/basic/legacy-event.json --output build/migrated-event.json
180
+ aiaudit rotate build/audit.jsonl
181
+ aiaudit schema list
182
+ aiaudit schema export --output build/schemas
183
+ ```
184
+
185
+ ## Storage
186
+
187
+ JSONL is the canonical local stream format. SQLite indexing is optional and is
188
+ not tamper-proof; chain verification recalculates event digests from stored
189
+ events.
190
+
191
+ ## Adapters
192
+
193
+ The package includes neutral protocols for framework, policy, ontology, and
194
+ benchmark adapters. No external ecosystem package is required in core.
195
+
196
+ ## Security Model
197
+
198
+ AIAuditLog distinguishes application logs, telemetry, audit evidence,
199
+ cryptographic integrity, authenticity, non-repudiation, and legal
200
+ admissibility. It provides local tamper evidence and optional checkpoint
201
+ signatures. It does not provide immutable storage, identity proofing, legal
202
+ certification, a SIEM, or policy enforcement.
203
+
204
+ ## Threat Model And Limitations
205
+
206
+ - Hash chaining is tamper-evident, not immutable.
207
+ - An attacker who can rewrite the entire log may recompute an unsigned chain.
208
+ - Signatures depend on secure key custody.
209
+ - The package does not establish real-world actor identity.
210
+ - Timestamps depend on system clocks.
211
+ - Local storage can be deleted.
212
+ - SQLite is not tamper-proof.
213
+ - Full-content logging may expose sensitive data.
214
+ - Redaction and secret detection are heuristic and not perfect.
215
+ - Adapters depend on external framework APIs.
216
+ - Event completeness depends on correct instrumentation.
217
+ - Missing events cannot always be distinguished from actions that never occurred.
218
+ - Audit records do not guarantee model correctness.
219
+ - Audit records do not enforce policy.
220
+ - Compliance mappings are informational.
221
+ - This project is not legal advice.
222
+ - The schema may evolve before version 1.0.
223
+ - External anchoring and trusted timestamping are not included in this alpha.
224
+ - Concurrent multi-process writing has documented limitations unless explicitly tested.
225
+
226
+ ## Interoperability
227
+
228
+ Canonical JSON serialization uses the maintained `rfc8785` package after
229
+ AIAuditLog normalizes datetimes, Decimals, bytes, and model objects. Timestamps
230
+ are RFC 3339-compatible UTC strings. Trace and span fields can carry W3C Trace
231
+ Context or OpenTelemetry identifiers, and helper functions can parse and emit
232
+ `traceparent` values. CloudEvents concepts influenced envelope naming, but this
233
+ package does not claim CloudEvents compliance.
234
+
235
+ ## Roadmap
236
+
237
+ Implemented in 0.1.0a2:
238
+
239
+ - RFC8785-backed canonicalization with an RFC8785 sample vector.
240
+ - Signed checkpoint policies.
241
+ - Stream rotation.
242
+ - Deterministic gzip exports.
243
+ - Richer privacy profiles.
244
+ - Lock-file guarded appends.
245
+ - Conservative schema migration helpers.
246
+
247
+ Implemented in 0.1.0a3:
248
+
249
+ - Neutral Forge-like agent step adapter.
250
+ - Neutral AgentPolicyPack-like policy decision adapter.
251
+ - Neutral ModelSwapBench-like benchmark context adapter.
252
+ - Neutral OpenOntologyLite-like ontology context adapter.
253
+ - Neutral PrivateAIStack metadata adapter.
254
+ - OpenTelemetry/W3C Trace Context helpers.
255
+
256
+ The 0.1.0a3 adapters intentionally use plain dictionaries and are not claimed as
257
+ externally tested against sibling packages.
258
+
259
+ Next candidates for 0.1.0a4:
260
+
261
+ - Broader export test coverage for JSON, JSONL, CSV, Markdown, and compressed outputs.
262
+ - Signed stream manifests.
263
+ - Stronger rotation manifests and rotation verification.
264
+ - More complete schema migration fixtures.
265
+ - Optional dependency-license report generation.
266
+ - Improved concurrent-writer stress tests.
267
+
268
+ 0.2 candidates:
269
+
270
+ - External checkpoint anchoring.
271
+ - Optional PostgreSQL storage.
272
+ - Retention policies.
273
+ - Audit package bundles.
274
+ - Provenance attestations.
275
+ - Organization-specific event profiles.
276
+ - SIEM exporters.
277
+
278
+ 1.0 considerations:
279
+
280
+ - Stable schema.
281
+ - Compatibility policy.
282
+ - Formal canonicalization profile.
283
+ - Migration policy.
284
+ - Interoperability test suite.
285
+ - Independent security review.
286
+
287
+ ## Contributing
288
+
289
+ Use the development commands in `docs/getting-started.md`. Keep claims
290
+ verifiable and do not commit secrets, private keys, local audit logs, databases,
291
+ or generated distribution artifacts.
292
+
293
+ ## License
294
+
295
+ MIT.
296
+
297
+ ## Author
298
+
299
+ sekacorn
@@ -0,0 +1,259 @@
1
+ # AIAuditLog
2
+
3
+ AIAuditLog provides portable, privacy-aware, tamper-evident evidence for AI
4
+ models, agents, tools, policies, reviews, and workflow outcomes.
5
+
6
+ This is an alpha release candidate for `0.1.0a3`. It is ready for public alpha
7
+ release with documented limitations, not production certification.
8
+
9
+ ## Why AI Audit Logs Are Different
10
+
11
+ Ordinary application logs usually explain what software printed while it ran.
12
+ AI audit evidence must also preserve model choices, tool access, policy
13
+ decisions, human approvals, data references, redaction decisions, and workflow
14
+ outcomes in a vendor-neutral format that survives framework and provider
15
+ changes.
16
+
17
+ ## Problem Statement
18
+
19
+ Organizations need inspectable evidence of what an AI system did, why it acted,
20
+ which models and policies were involved, what data and tools were accessed, and
21
+ what outcome occurred. AIAuditLog keeps that evidence local-first, append
22
+ oriented, deterministic, and suitable for CI review.
23
+
24
+ ## Ecosystem Position
25
+
26
+ AIAuditLog is project six in the sekacorn AI infrastructure roadmap. It is
27
+ designed for future optional integration with Forge, PrivateAIStack,
28
+ ModelSwapBench, OpenOntologyLite, AgentPolicyPack, and OpenAIMeter. The first
29
+ alpha works independently and offline.
30
+
31
+ ## Core Capabilities
32
+
33
+ - Versioned JSON event envelope and JSON Schema export.
34
+ - Typed Python models for AI, agent, tool, policy, ontology, and benchmark context.
35
+ - RFC8785-backed canonical JSON after AIAuditLog value normalization.
36
+ - SHA-256 event digests.
37
+ - Optional hash-chain metadata for tamper evidence.
38
+ - Checkpoints, optional Ed25519 checkpoint signatures, and signature policies.
39
+ - JSONL storage and SQLite indexing.
40
+ - Stream rotation, lock-file guarded appends, compressed exports, and schema migration helpers.
41
+ - Privacy modes, deterministic redaction, secret-key filtering, classification redaction, and CSV-safe export.
42
+ - CLI and Python API.
43
+ - Neutral adapter protocols for future ecosystem packages.
44
+
45
+ ## Event Architecture
46
+
47
+ Each event contains `schema_version`, `event_id`, `event_type`, UTC
48
+ `event_time`, UTC `recorded_time`, `source`, `actor`, `outcome`, `data`,
49
+ optional context, and `integrity`. Core event types cover system, agent, model,
50
+ tool, data, retrieval, policy, review, security, evaluation, benchmark, and
51
+ audit-log lifecycle categories. Custom event types must be namespaced and may
52
+ not collide with reserved core namespaces.
53
+
54
+ ## Installation
55
+
56
+ ```powershell
57
+ python -m pip install aiauditlog
58
+ ```
59
+
60
+ For development:
61
+
62
+ ```powershell
63
+ python -m pip install -e ".[dev]"
64
+ ```
65
+
66
+ ## Quick Start
67
+
68
+ ```powershell
69
+ aiaudit validate examples/basic/event.json
70
+ aiaudit append build/audit.jsonl --event examples/basic/event.json
71
+ aiaudit verify build/audit.jsonl
72
+ aiaudit summarize build/audit.jsonl
73
+ ```
74
+
75
+ ## JSON Event Example
76
+
77
+ See `examples/basic/event.json` for a complete model invocation event. Prompts
78
+ and responses are not stored by default; use hashes, references, counts, and
79
+ explicitly configured safe excerpts.
80
+
81
+ ## Recorder Example
82
+
83
+ ```python
84
+ from ai_audit_log import AuditRecorder, EventBuilder, JsonlStore, Outcome, Source
85
+ from ai_audit_log.models import Actor
86
+
87
+ builder = EventBuilder(
88
+ source=Source(service="claims-agent"),
89
+ actor=Actor(actor_id="agent-17", actor_type="ai_agent"),
90
+ )
91
+ recorder = AuditRecorder(builder=builder, store=JsonlStore("build/audit.jsonl"))
92
+ recorder.record(
93
+ event_type="model.invocation.completed",
94
+ outcome=Outcome(status="success", code="COMPLETED"),
95
+ data={"provider": "example", "model_name": "example-model"},
96
+ )
97
+ ```
98
+
99
+ ## Chain Verification
100
+
101
+ ```powershell
102
+ aiaudit verify build/audit.jsonl
103
+ ```
104
+
105
+ Hash chaining is tamper-evident, not immutable. An attacker who can rewrite an
106
+ entire unsigned log can recompute the chain.
107
+
108
+ ## Privacy Modes
109
+
110
+ The default mode is `minimal`: identifiers, metadata, hashes, counts, outcomes,
111
+ and policy evidence are preserved, while prompts, responses, and common secret
112
+ keys are redacted. `balanced` may keep short configured excerpts.
113
+ `full-content` requires explicit opt-in and can expose sensitive data.
114
+
115
+ ## Checkpoints And Signatures
116
+
117
+ Checkpoints summarize stream ID, event count, terminal digest, and checkpoint
118
+ digest. Ed25519 signatures authenticate the checkpoint bytes to a public key,
119
+ and checkpoint signature policies can require allowed key IDs, fingerprints, and
120
+ minimum signature counts. Signatures do not prove real-world actor identity,
121
+ legal non-repudiation, or correct key custody.
122
+
123
+ ```powershell
124
+ aiaudit checkpoint create build/audit.jsonl --output build/checkpoint.json
125
+ aiaudit key generate --private-key build/development-private.pem --public-key build/development-public.pem
126
+ aiaudit sign build/checkpoint.json --private-key build/development-private.pem --key-id development-key
127
+ aiaudit signature verify build/checkpoint.json --public-key build/development-public.pem
128
+ ```
129
+
130
+ Never commit generated private keys.
131
+
132
+ ## CLI Examples
133
+
134
+ ```powershell
135
+ aiaudit inspect examples/basic/event.json
136
+ aiaudit query build/audit.jsonl --event-type model.invocation.completed
137
+ aiaudit export build/audit.jsonl --format markdown --output build/audit-report.md --compress
138
+ aiaudit redact build/audit.jsonl --profile examples/privacy/minimal.yaml --output build/audit-redacted.jsonl
139
+ aiaudit migrate examples/basic/legacy-event.json --output build/migrated-event.json
140
+ aiaudit rotate build/audit.jsonl
141
+ aiaudit schema list
142
+ aiaudit schema export --output build/schemas
143
+ ```
144
+
145
+ ## Storage
146
+
147
+ JSONL is the canonical local stream format. SQLite indexing is optional and is
148
+ not tamper-proof; chain verification recalculates event digests from stored
149
+ events.
150
+
151
+ ## Adapters
152
+
153
+ The package includes neutral protocols for framework, policy, ontology, and
154
+ benchmark adapters. No external ecosystem package is required in core.
155
+
156
+ ## Security Model
157
+
158
+ AIAuditLog distinguishes application logs, telemetry, audit evidence,
159
+ cryptographic integrity, authenticity, non-repudiation, and legal
160
+ admissibility. It provides local tamper evidence and optional checkpoint
161
+ signatures. It does not provide immutable storage, identity proofing, legal
162
+ certification, a SIEM, or policy enforcement.
163
+
164
+ ## Threat Model And Limitations
165
+
166
+ - Hash chaining is tamper-evident, not immutable.
167
+ - An attacker who can rewrite the entire log may recompute an unsigned chain.
168
+ - Signatures depend on secure key custody.
169
+ - The package does not establish real-world actor identity.
170
+ - Timestamps depend on system clocks.
171
+ - Local storage can be deleted.
172
+ - SQLite is not tamper-proof.
173
+ - Full-content logging may expose sensitive data.
174
+ - Redaction and secret detection are heuristic and not perfect.
175
+ - Adapters depend on external framework APIs.
176
+ - Event completeness depends on correct instrumentation.
177
+ - Missing events cannot always be distinguished from actions that never occurred.
178
+ - Audit records do not guarantee model correctness.
179
+ - Audit records do not enforce policy.
180
+ - Compliance mappings are informational.
181
+ - This project is not legal advice.
182
+ - The schema may evolve before version 1.0.
183
+ - External anchoring and trusted timestamping are not included in this alpha.
184
+ - Concurrent multi-process writing has documented limitations unless explicitly tested.
185
+
186
+ ## Interoperability
187
+
188
+ Canonical JSON serialization uses the maintained `rfc8785` package after
189
+ AIAuditLog normalizes datetimes, Decimals, bytes, and model objects. Timestamps
190
+ are RFC 3339-compatible UTC strings. Trace and span fields can carry W3C Trace
191
+ Context or OpenTelemetry identifiers, and helper functions can parse and emit
192
+ `traceparent` values. CloudEvents concepts influenced envelope naming, but this
193
+ package does not claim CloudEvents compliance.
194
+
195
+ ## Roadmap
196
+
197
+ Implemented in 0.1.0a2:
198
+
199
+ - RFC8785-backed canonicalization with an RFC8785 sample vector.
200
+ - Signed checkpoint policies.
201
+ - Stream rotation.
202
+ - Deterministic gzip exports.
203
+ - Richer privacy profiles.
204
+ - Lock-file guarded appends.
205
+ - Conservative schema migration helpers.
206
+
207
+ Implemented in 0.1.0a3:
208
+
209
+ - Neutral Forge-like agent step adapter.
210
+ - Neutral AgentPolicyPack-like policy decision adapter.
211
+ - Neutral ModelSwapBench-like benchmark context adapter.
212
+ - Neutral OpenOntologyLite-like ontology context adapter.
213
+ - Neutral PrivateAIStack metadata adapter.
214
+ - OpenTelemetry/W3C Trace Context helpers.
215
+
216
+ The 0.1.0a3 adapters intentionally use plain dictionaries and are not claimed as
217
+ externally tested against sibling packages.
218
+
219
+ Next candidates for 0.1.0a4:
220
+
221
+ - Broader export test coverage for JSON, JSONL, CSV, Markdown, and compressed outputs.
222
+ - Signed stream manifests.
223
+ - Stronger rotation manifests and rotation verification.
224
+ - More complete schema migration fixtures.
225
+ - Optional dependency-license report generation.
226
+ - Improved concurrent-writer stress tests.
227
+
228
+ 0.2 candidates:
229
+
230
+ - External checkpoint anchoring.
231
+ - Optional PostgreSQL storage.
232
+ - Retention policies.
233
+ - Audit package bundles.
234
+ - Provenance attestations.
235
+ - Organization-specific event profiles.
236
+ - SIEM exporters.
237
+
238
+ 1.0 considerations:
239
+
240
+ - Stable schema.
241
+ - Compatibility policy.
242
+ - Formal canonicalization profile.
243
+ - Migration policy.
244
+ - Interoperability test suite.
245
+ - Independent security review.
246
+
247
+ ## Contributing
248
+
249
+ Use the development commands in `docs/getting-started.md`. Keep claims
250
+ verifiable and do not commit secrets, private keys, local audit logs, databases,
251
+ or generated distribution artifacts.
252
+
253
+ ## License
254
+
255
+ MIT.
256
+
257
+ ## Author
258
+
259
+ sekacorn
@@ -0,0 +1,22 @@
1
+ # Python API
2
+
3
+ Primary imports:
4
+
5
+ ```python
6
+ from ai_audit_log import AuditEvent, AuditRecorder, EventBuilder, JsonlStore, Outcome, Source
7
+ from ai_audit_log.models import Actor
8
+ ```
9
+
10
+ Use `EventBuilder` to create validated privacy-filtered events, `AuditRecorder`
11
+ to append chained events, `JsonlStore` for JSONL streams, `SQLiteIndex` for
12
+ query indexing, `ChainVerifier` for integrity checks, and `Checkpoint` helpers
13
+ for stream summaries.
14
+
15
+ Additional alpha helpers:
16
+
17
+ - `ai_audit_log.rotation` for stream rotation policies.
18
+ - `ai_audit_log.compression` for deterministic gzip files.
19
+ - `ai_audit_log.migration` for conservative early-schema migration.
20
+ - `ai_audit_log.checkpoint_policy` for signed checkpoint policy checks.
21
+ - `ai_audit_log.otel` for W3C Trace Context correlation helpers.
22
+ - `ai_audit_log.ecosystem` for neutral dictionary adapters.
@@ -0,0 +1,26 @@
1
+ # CLI
2
+
3
+ Commands:
4
+
5
+ - `validate EVENT`: validate one event JSON file.
6
+ - `inspect EVENT`: print a compact JSON inspection.
7
+ - `append LOG --event EVENT`: append with chain integrity.
8
+ - `append LOG --event EVENT --lock`: append with a simple lock file.
9
+ - `verify LOG`: verify a chain.
10
+ - `query LOG`: filter by event type, status, stream, and limit.
11
+ - `summarize LOG`: summarize event types and outcomes.
12
+ - `checkpoint create LOG --output PATH`: create a checkpoint.
13
+ - `checkpoint verify CHECKPOINT --log LOG`: verify a checkpoint.
14
+ - `export LOG --format jsonl|json|csv|markdown --output PATH --compress`: export events, optionally with gzip.
15
+ - `redact LOG --profile PROFILE --output PATH`: write redacted JSONL.
16
+ - `compress PATH`: create a deterministic gzip copy.
17
+ - `rotate LOG`: rotate a stream to the next numbered path.
18
+ - `migrate EVENT --output PATH`: migrate an early alpha event document.
19
+ - `schema list`: list schemas.
20
+ - `schema export --output DIR`: write JSON Schema files.
21
+ - `key generate`: create an Ed25519 development key pair.
22
+ - `key generate --force`: overwrite existing key files.
23
+ - `sign CHECKPOINT`: sign a checkpoint in place.
24
+ - `signature verify CHECKPOINT`: verify checkpoint signatures.
25
+
26
+ Do not commit private keys generated by `key generate`.
@@ -0,0 +1,17 @@
1
+ # Event Envelope
2
+
3
+ Required fields are `schema_version`, `event_id`, `event_type`, `event_time`,
4
+ `recorded_time`, `source`, `actor`, `outcome`, and `data`. Chained events also
5
+ include `integrity.stream_id`, `integrity.sequence`,
6
+ `integrity.previous_event_digest`, and `integrity.event_digest`.
7
+
8
+ Event IDs use UUID strings. Python 3.11 lacks a standard UUIDv7 generator, so
9
+ 0.1.0a1 uses UUIDv4 for generated IDs and documents that generated IDs are
10
+ unique but not time-sortable. Externally supplied UUIDs are preserved.
11
+
12
+ Timestamps must be timezone-aware and are serialized as UTC RFC
13
+ 3339-compatible strings with a `Z` suffix. Timestamps are not an ordering or
14
+ integrity mechanism.
15
+
16
+ Sequence numbers begin at `1`, increment by one within a stream, are included in
17
+ event digests, and are checked during chain verification.