omega-audit 0.1.0__tar.gz

omega_audit-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/

omega_audit-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024-2026 Jesse Mahoney
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

omega_audit-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: omega-audit
+Version: 0.1.0
+Summary: Tamper-evident audit + provenance for AI agents — an offline, zero-dependency, hash-chained append-only ledger. Wrap your agent's tool calls, then prove what it did: any edit, reorder, insertion, or deletion fails verification.
+Project-URL: Homepage, https://omegaengine.ai
+Project-URL: Documentation, https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-audit-py#readme
+Project-URL: Repository, https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-audit-py
+Project-URL: Issues, https://github.com/TheArkhitect/Omegaengine/issues
+Author-email: OmegaEngine <team@omegaengine.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,append-only,audit-log,compliance,eu-ai-act,hash-chain,omegaengine,provenance,sha256,tamper-evident
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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 :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# omega-audit
+
+**Tamper-evident audit + provenance for AI agents — prove what your agent did, hash-chained, verifiable, auditor-ready.**
+
+Wrap your agent's tool calls. Every call is appended to a local, append-only, SHA-256 hash-chained ledger. Later, anyone can recompute the chain and detect *any* edit, reorder, insertion, or deletion — offline, in one command, with no signup and no trust in us.
+
+- **Zero runtime dependencies.** Python's standard library only (`hashlib`, `json`, `base64`). No SDK, no account, no network.
+- **Offline and local.** The ledger is a plain JSONL file on your disk. You own it.
+- **Framework-agnostic.** Wrap any callable — sync or async — plain tools, OpenAI/LangChain/LlamaIndex tool defs, MCP handlers.
+- **Independently verifiable.** `omega-audit verify` recomputes the whole chain. Break one byte and it fails.
+- **Byte-compatible with the TypeScript twin** [`@omegaengine/audit`](https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-audit): a ledger written in Python verifies under the TS CLI and vice versa — same bytes, same hashes.
+- **Apache-2.0.**
+
+---
+
+## Why now
+
+The **EU AI Act's record-keeping obligation (Article 12) begins to apply on August 2, 2026** for high-risk AI systems: providers must ensure their systems automatically record events (logs) over their lifetime, to a degree appropriate to the system's purpose. A policy document that says "we log agent actions" is not evidence. **Evidence is a log you can hand an auditor that provably has not been altered.**
+
+Append-only, cryptographically hash-chained logs are the well-established way to make an audit trail tamper-evident: each record commits to the one before it, so the chain itself proves nothing was quietly changed after the fact. That's the same construction behind Git commit history and RFC 6962 Certificate Transparency. This package gives you that construction for your agent's actions, in about twenty minutes.
+
+> This is honest scope: `omega-audit` produces **tamper-evident** local logs — you can *detect* tampering by recomputing the chain. It is not, by itself, a certification, a signature from us, or proof to a third party who doesn't have your file. For cross-organization, independently-anchored proof, see [Anchoring to the transparency log](#anchor-to-the-transparency-log-optional) below.
+
+---
+
+## 20-minute quickstart
+
+### 1. Install
+
+```bash
+pip install omega-audit
+```
+
+### 2. Wrap a tool
+
+```python
+from omega_audit import Ledger, wrap_tool
+
+# One local, append-only ledger file. Offline — no signup, no network.
+ledger = Ledger("ledger.jsonl")
+
+# Your existing tool — any callable, sync or async.
+def send_email(to: str, subject: str):
+    # ... your real implementation ...
+    return {"delivered": True}
+
+# Wrap it. Same signature, same return value — it just records every call.
+tracked_send_email = wrap_tool(ledger, "send_email", send_email)
+
+tracked_send_email("auditor@example.com", "Q3 evidence")
+```
+
+Each call appends one record: `{tool, args, ok, result | error, duration_ms}`. Errors are recorded too (with `ok=False` and the message) and then re-raised unchanged, so wrapping never swallows a failure.
+
+Async tools work the same way — if the wrapped function is a coroutine, the wrapper is too:
+
+```python
+import asyncio
+from omega_audit import Ledger, wrap_tool
+
+ledger = Ledger("ledger.jsonl")
+
+async def fetch_row(row_id: str):
+    # ... await your real async implementation ...
+    return {"id": row_id}
+
+tracked = wrap_tool(ledger, "fetch_row", fetch_row)
+asyncio.run(tracked("abc"))   # the record is written when the awaited call settles
+```
+
+This composes with agent frameworks: an OpenAI or LangChain tool is just a callable with a schema, so wrap its implementation and register the wrapped version. Nothing about your agent loop changes.
+
+### 3. Look at the ledger
+
+`ledger.jsonl` is one JSON object per line — readable, greppable, diffable:
+
+```json
+{"seq":0,"ts":"2026-08-02T09:00:00.000Z","action":{"tool":"send_email","args":["auditor@example.com","Q3 evidence"],"ok":true,"result":{"delivered":true},"durationMs":501},"prevHash":"0000000000000000000000000000000000000000000000000000000000000000","hash":"44dab7b4…"}
+```
+
+Every record's `hash` is `sha256(canonical_json({seq, ts, action, prevHash}))`, and its `prevHash` is the previous record's `hash` (the first record links to 64 zeros). That chain is what makes tampering detectable. The field is stored on disk as `prevHash` (camelCase) so the bytes are identical to the TypeScript twin.
+
+### 4. Verify it
+
+```bash
+omega-audit verify ledger.jsonl
+```
+
+```
+✓ 3 records — chain intact & tamper-evident
+```
+
+Exit code `0` when intact, `1` when tampered. Drop it in CI to fail a build if an agent's audit trail was touched.
+
+You can also verify in code:
+
+```python
+from omega_audit import verify
+
+result = verify("ledger.jsonl")
+# VerifyResult(valid=True, records=3, broken_at=None, reason=None)
+# or VerifyResult(valid=False, records=3, broken_at=2, reason="record 2 was edited — …")
+```
+
+---
+
+## See it break: the tamper demo
+
+One command builds a small ledger, tampers a record, and shows verification catch it:
+
+```bash
+omega-audit demo
+```
+
+```
+omega-audit demo — tamper-evident agent audit in one command
+
+1. An agent runs three tool calls. Each one is appended to a hash-chained ledger:
+
+   #0  search_web  hash=ce4ca688b665…  prev=000000000000…
+   #1  read_file  hash=5c7f4ae5891f…  prev=ce4ca688b665…
+   #2  send_email  hash=a0c640028849…  prev=5c7f4ae5891f…
+
+2. Verify the untouched ledger:
+
+   $ omega-audit verify ledger.jsonl
+   ✓ 3 records — chain intact & tamper-evident
+
+3. Now someone quietly edits record #2 to hide who the email went to:
+
+   before:  send_email → auditor@example.com
+   after:   send_email → attacker@evil.example   (hash left unchanged to hide the edit)
+
+4. Verify again — the chain no longer recomputes:
+
+   $ omega-audit verify ledger.jsonl
+   ✗ TAMPER DETECTED at record 2: record 2 was edited — its stored hash a0c64002…30cc ≠ the recomputed hash 6e1be9ab…e0ef
+
+That ✗ is the whole point: the record was changed, and verification proved it.
+Nothing here touched the network. You can run the same check on your own ledger.
+```
+
+The `demo` command exits `1` — its whole job is to prove that a tampered ledger fails verification. (The hashes vary run to run because each record's timestamp is real; the chain is self-consistent every time.)
+
+---
+
+## Enforce vs. prove
+
+These are two different jobs, and you want both:
+
+- **A policy layer *enforces*** — it decides, at run time, whether an action is allowed and blocks the ones that aren't.
+- **`omega-audit` *proves*** — it produces the independent, tamper-evident evidence trail of what actually happened, which you can verify after the fact.
+
+Enforcement without evidence is a claim. Evidence without enforcement is a bystander. Run your guardrails to stop bad actions; run `omega-audit` to prove — to yourself, to an auditor, to a customer — exactly what your agent did and that the record wasn't altered.
+
+---
+
+## Anchor to the transparency log (optional)
+
+Your local ledger is tamper-evident to *anyone who has the file*. To make it verifiable *across organizations* — so a customer or auditor who does **not** have your machine can still confirm the record — you anchor the ledger's root to a public, append-only transparency log.
+
+The record hashing here is byte-compatible with the OmegaEngine platform's canonical JSON + SHA-256 **and with the TypeScript twin** — a ledger written by this Python package verifies under `@omegaengine/audit` and vice versa, so it is already in the shape the hosted log expects. [OmegaEngine](https://omegaengine.ai) offers, as a hosted backend:
+
+- **Anchoring** your ledger root into a public RFC 6962 transparency log for cross-org, independently-checkable proof of inclusion.
+- **Long-retention storage** to support multi-year record-keeping regimes (for example SEC Rule 17a-4 or HIPAA retention).
+- **Auditor exports** — signed, verifiable bundles an auditor can check with the open-source [`@omegaengine/verify`](https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-verify) tool, no OmegaEngine account required.
+
+The local package is fully useful on its own and stays free and open source. The hosted log is the optional upgrade when "verifiable on my disk" needs to become "verifiable by someone else."
+
+---
+
+## API
+
+```python
+Ledger(path: str)
+  ledger.append(action) -> dict     # append one record; returns it
+  ledger.size() -> int
+  ledger.tip_hash() -> str          # hash of the last record (chain tip)
+
+wrap_tool(ledger, name, fn) -> fn   # wrap a named tool (sync or async); records every call
+capture(ledger, fn) -> fn           # like wrap_tool, using fn.__name__
+
+verify(path: str) -> VerifyResult
+  # VerifyResult(valid, records, broken_at, reason)
+
+read_ledger(path) -> list[dict]     # parse JSONL into records (no chain check)
+verify_entries(entries) -> VerifyResult   # verify already-parsed records
+canonical_json(value) -> str        # the deterministic serializer used for hashing
+sha256_hex(s) -> str
+```
+
+A ledger entry is a dict `{seq, ts, action, prevHash, hash}`.
+
+---
+
+## Design partners
+
+We're looking for teams putting agents in front of real users or real money who need to *prove* what those agents did. If you're wiring agent actions into an audit or compliance story — EU AI Act, financial record-keeping, healthcare — we'd like to build with you. Open an issue on [github.com/TheArkhitect/Omegaengine](https://github.com/TheArkhitect/Omegaengine/discussions) or reach out via [omegaengine.ai](https://omegaengine.ai).
+
+---
+
+## License
+
+Apache-2.0. See the repository root for the full text.

omega_audit-0.1.0/README.md

@@ -0,0 +1,204 @@
+# omega-audit
+
+**Tamper-evident audit + provenance for AI agents — prove what your agent did, hash-chained, verifiable, auditor-ready.**
+
+Wrap your agent's tool calls. Every call is appended to a local, append-only, SHA-256 hash-chained ledger. Later, anyone can recompute the chain and detect *any* edit, reorder, insertion, or deletion — offline, in one command, with no signup and no trust in us.
+
+- **Zero runtime dependencies.** Python's standard library only (`hashlib`, `json`, `base64`). No SDK, no account, no network.
+- **Offline and local.** The ledger is a plain JSONL file on your disk. You own it.
+- **Framework-agnostic.** Wrap any callable — sync or async — plain tools, OpenAI/LangChain/LlamaIndex tool defs, MCP handlers.
+- **Independently verifiable.** `omega-audit verify` recomputes the whole chain. Break one byte and it fails.
+- **Byte-compatible with the TypeScript twin** [`@omegaengine/audit`](https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-audit): a ledger written in Python verifies under the TS CLI and vice versa — same bytes, same hashes.
+- **Apache-2.0.**
+
+---
+
+## Why now
+
+The **EU AI Act's record-keeping obligation (Article 12) begins to apply on August 2, 2026** for high-risk AI systems: providers must ensure their systems automatically record events (logs) over their lifetime, to a degree appropriate to the system's purpose. A policy document that says "we log agent actions" is not evidence. **Evidence is a log you can hand an auditor that provably has not been altered.**
+
+Append-only, cryptographically hash-chained logs are the well-established way to make an audit trail tamper-evident: each record commits to the one before it, so the chain itself proves nothing was quietly changed after the fact. That's the same construction behind Git commit history and RFC 6962 Certificate Transparency. This package gives you that construction for your agent's actions, in about twenty minutes.
+
+> This is honest scope: `omega-audit` produces **tamper-evident** local logs — you can *detect* tampering by recomputing the chain. It is not, by itself, a certification, a signature from us, or proof to a third party who doesn't have your file. For cross-organization, independently-anchored proof, see [Anchoring to the transparency log](#anchor-to-the-transparency-log-optional) below.
+
+---
+
+## 20-minute quickstart
+
+### 1. Install
+
+```bash
+pip install omega-audit
+```
+
+### 2. Wrap a tool
+
+```python
+from omega_audit import Ledger, wrap_tool
+
+# One local, append-only ledger file. Offline — no signup, no network.
+ledger = Ledger("ledger.jsonl")
+
+# Your existing tool — any callable, sync or async.
+def send_email(to: str, subject: str):
+    # ... your real implementation ...
+    return {"delivered": True}
+
+# Wrap it. Same signature, same return value — it just records every call.
+tracked_send_email = wrap_tool(ledger, "send_email", send_email)
+
+tracked_send_email("auditor@example.com", "Q3 evidence")
+```
+
+Each call appends one record: `{tool, args, ok, result | error, duration_ms}`. Errors are recorded too (with `ok=False` and the message) and then re-raised unchanged, so wrapping never swallows a failure.
+
+Async tools work the same way — if the wrapped function is a coroutine, the wrapper is too:
+
+```python
+import asyncio
+from omega_audit import Ledger, wrap_tool
+
+ledger = Ledger("ledger.jsonl")
+
+async def fetch_row(row_id: str):
+    # ... await your real async implementation ...
+    return {"id": row_id}
+
+tracked = wrap_tool(ledger, "fetch_row", fetch_row)
+asyncio.run(tracked("abc"))   # the record is written when the awaited call settles
+```
+
+This composes with agent frameworks: an OpenAI or LangChain tool is just a callable with a schema, so wrap its implementation and register the wrapped version. Nothing about your agent loop changes.
+
+### 3. Look at the ledger
+
+`ledger.jsonl` is one JSON object per line — readable, greppable, diffable:
+
+```json
+{"seq":0,"ts":"2026-08-02T09:00:00.000Z","action":{"tool":"send_email","args":["auditor@example.com","Q3 evidence"],"ok":true,"result":{"delivered":true},"durationMs":501},"prevHash":"0000000000000000000000000000000000000000000000000000000000000000","hash":"44dab7b4…"}
+```
+
+Every record's `hash` is `sha256(canonical_json({seq, ts, action, prevHash}))`, and its `prevHash` is the previous record's `hash` (the first record links to 64 zeros). That chain is what makes tampering detectable. The field is stored on disk as `prevHash` (camelCase) so the bytes are identical to the TypeScript twin.
+
+### 4. Verify it
+
+```bash
+omega-audit verify ledger.jsonl
+```
+
+```
+✓ 3 records — chain intact & tamper-evident
+```
+
+Exit code `0` when intact, `1` when tampered. Drop it in CI to fail a build if an agent's audit trail was touched.
+
+You can also verify in code:
+
+```python
+from omega_audit import verify
+
+result = verify("ledger.jsonl")
+# VerifyResult(valid=True, records=3, broken_at=None, reason=None)
+# or VerifyResult(valid=False, records=3, broken_at=2, reason="record 2 was edited — …")
+```
+
+---
+
+## See it break: the tamper demo
+
+One command builds a small ledger, tampers a record, and shows verification catch it:
+
+```bash
+omega-audit demo
+```
+
+```
+omega-audit demo — tamper-evident agent audit in one command
+
+1. An agent runs three tool calls. Each one is appended to a hash-chained ledger:
+
+   #0  search_web  hash=ce4ca688b665…  prev=000000000000…
+   #1  read_file  hash=5c7f4ae5891f…  prev=ce4ca688b665…
+   #2  send_email  hash=a0c640028849…  prev=5c7f4ae5891f…
+
+2. Verify the untouched ledger:
+
+   $ omega-audit verify ledger.jsonl
+   ✓ 3 records — chain intact & tamper-evident
+
+3. Now someone quietly edits record #2 to hide who the email went to:
+
+   before:  send_email → auditor@example.com
+   after:   send_email → attacker@evil.example   (hash left unchanged to hide the edit)
+
+4. Verify again — the chain no longer recomputes:
+
+   $ omega-audit verify ledger.jsonl
+   ✗ TAMPER DETECTED at record 2: record 2 was edited — its stored hash a0c64002…30cc ≠ the recomputed hash 6e1be9ab…e0ef
+
+That ✗ is the whole point: the record was changed, and verification proved it.
+Nothing here touched the network. You can run the same check on your own ledger.
+```
+
+The `demo` command exits `1` — its whole job is to prove that a tampered ledger fails verification. (The hashes vary run to run because each record's timestamp is real; the chain is self-consistent every time.)
+
+---
+
+## Enforce vs. prove
+
+These are two different jobs, and you want both:
+
+- **A policy layer *enforces*** — it decides, at run time, whether an action is allowed and blocks the ones that aren't.
+- **`omega-audit` *proves*** — it produces the independent, tamper-evident evidence trail of what actually happened, which you can verify after the fact.
+
+Enforcement without evidence is a claim. Evidence without enforcement is a bystander. Run your guardrails to stop bad actions; run `omega-audit` to prove — to yourself, to an auditor, to a customer — exactly what your agent did and that the record wasn't altered.
+
+---
+
+## Anchor to the transparency log (optional)
+
+Your local ledger is tamper-evident to *anyone who has the file*. To make it verifiable *across organizations* — so a customer or auditor who does **not** have your machine can still confirm the record — you anchor the ledger's root to a public, append-only transparency log.
+
+The record hashing here is byte-compatible with the OmegaEngine platform's canonical JSON + SHA-256 **and with the TypeScript twin** — a ledger written by this Python package verifies under `@omegaengine/audit` and vice versa, so it is already in the shape the hosted log expects. [OmegaEngine](https://omegaengine.ai) offers, as a hosted backend:
+
+- **Anchoring** your ledger root into a public RFC 6962 transparency log for cross-org, independently-checkable proof of inclusion.
+- **Long-retention storage** to support multi-year record-keeping regimes (for example SEC Rule 17a-4 or HIPAA retention).
+- **Auditor exports** — signed, verifiable bundles an auditor can check with the open-source [`@omegaengine/verify`](https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-verify) tool, no OmegaEngine account required.
+
+The local package is fully useful on its own and stays free and open source. The hosted log is the optional upgrade when "verifiable on my disk" needs to become "verifiable by someone else."
+
+---
+
+## API
+
+```python
+Ledger(path: str)
+  ledger.append(action) -> dict     # append one record; returns it
+  ledger.size() -> int
+  ledger.tip_hash() -> str          # hash of the last record (chain tip)
+
+wrap_tool(ledger, name, fn) -> fn   # wrap a named tool (sync or async); records every call
+capture(ledger, fn) -> fn           # like wrap_tool, using fn.__name__
+
+verify(path: str) -> VerifyResult
+  # VerifyResult(valid, records, broken_at, reason)
+
+read_ledger(path) -> list[dict]     # parse JSONL into records (no chain check)
+verify_entries(entries) -> VerifyResult   # verify already-parsed records
+canonical_json(value) -> str        # the deterministic serializer used for hashing
+sha256_hex(s) -> str
+```
+
+A ledger entry is a dict `{seq, ts, action, prevHash, hash}`.
+
+---
+
+## Design partners
+
+We're looking for teams putting agents in front of real users or real money who need to *prove* what those agents did. If you're wiring agent actions into an audit or compliance story — EU AI Act, financial record-keeping, healthcare — we'd like to build with you. Open an issue on [github.com/TheArkhitect/Omegaengine](https://github.com/TheArkhitect/Omegaengine/discussions) or reach out via [omegaengine.ai](https://omegaengine.ai).
+
+---
+
+## License
+
+Apache-2.0. See the repository root for the full text.

omega_audit-0.1.0/omega_audit/__init__.py

@@ -0,0 +1,56 @@
+"""omega-audit — tamper-evident audit + provenance for AI agents (Python twin).
+
+A local, offline, append-only, hash-chained ledger: wrap your agent's tool
+calls, then PROVE what it did. Any edit, reorder, insertion, or deletion of a
+record breaks the chain and fails verification — you confirm it yourself, with
+no network, no signup, no trust in OmegaEngine.
+
+Zero runtime dependencies: only Python's stdlib (``hashlib``, ``json``, ``base64``,
+``datetime``, ``time``).
+
+The record hashing is BYTE-IDENTICAL to the OmegaEngine platform's canonical
+JSON + SHA-256 and to the TypeScript twin ``@omegaengine/audit``. A ledger you
+capture locally in Python verifies against a TS one and can be anchored,
+unchanged, to the hosted transparency log for cross-org verifiability.
+
+Public API (mirrors the TS twin 1:1, Pythonic names):
+
+    Ledger(path)               .append(action) -> dict, .size(), .tip_hash()
+    wrap_tool(ledger, name, fn)  wrap a named tool (sync or async)
+    capture(ledger, fn)          like wrap_tool, using fn.__name__
+    verify(path) -> VerifyResult
+    verify_entries(entries) -> VerifyResult
+    read_ledger(path) -> list[dict]
+    canonical_json(value) -> str
+    sha256_hex(s) -> str
+    GENESIS_PREV_HASH
+"""
+
+from __future__ import annotations
+
+from .canonical import (
+    GENESIS_PREV_HASH,
+    canonical_json,
+    hash_entry,
+    sha256_hex,
+)
+from .ledger import Ledger, read_ledger
+from .verify import VerifyResult, verify, verify_entries
+from .wrap import capture, wrap_tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Ledger",
+    "read_ledger",
+    "verify",
+    "verify_entries",
+    "VerifyResult",
+    "wrap_tool",
+    "capture",
+    "canonical_json",
+    "sha256_hex",
+    "hash_entry",
+    "GENESIS_PREV_HASH",
+    "__version__",
+]

omega_audit-0.1.0/omega_audit/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m omega_audit`` — same entry point as the ``omega-audit`` console script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

omega_audit-0.1.0/omega_audit/canonical.py

@@ -0,0 +1,137 @@
+"""Canonical JSON + SHA-256 — byte-identical to the TypeScript twin.
+
+This is the load-bearing compatibility layer. The record ``hash`` is
+``sha256(canonical_json({seq, ts, action, prev_hash}))``, and it MUST produce
+the exact same bytes as:
+
+* the OmegaEngine platform (``lib/crypto/canonicalJson.ts``),
+* ``@omegaengine/verify``,
+* the TypeScript twin ``@omegaengine/audit`` (``packages/omega-audit/src/index.ts``).
+
+If it does not, a Python-captured ledger will not verify against a TS one and
+cannot be anchored to the hosted transparency log — which is the whole point of
+the cross-language design.
+
+Canonicalization rules (mirroring the TS ``canonicalJson``):
+
+* objects: keys sorted lexicographically, recursively;
+* arrays: order preserved;
+* ``None``  -> ``null`` (kept);
+* ``undefined`` has no Python analogue — object keys whose value normalizes to
+  "drop" are omitted (see below); inside arrays a dropped element becomes null,
+  matching ``JSON.stringify``;
+* bool: kept (``True`` -> ``true``); note bools are checked BEFORE ints because
+  ``isinstance(True, int)`` is ``True`` in Python;
+* numbers: non-finite (NaN/inf) -> ``null`` (matches ``JSON.stringify``);
+* bytes / bytearray -> base64 (matches Buffer/Uint8Array -> base64);
+* strings kept verbatim (non-ASCII NOT escaped, matching ``ensure_ascii=False``).
+
+Zero runtime dependencies: only ``hashlib``, ``json``, ``base64`` from stdlib.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import math
+from typing import Any
+
+# The genesis link: 64 hex zeros (the "prev_hash" of the very first record).
+GENESIS_PREV_HASH = "0" * 64
+
+# Sentinel meaning "this value has no JSON representation and should be dropped
+# from an object" — the Python analogue of JavaScript's `undefined`. It is never
+# emitted; in arrays it is replaced by null, exactly like `JSON.stringify`.
+_DROP = object()
+
+
+def _normalize(value: Any, seen: set[int]) -> Any:
+    """Recursively normalize a value into JSON-canonical primitives.
+
+    Returns the sentinel ``_DROP`` for values that ``JSON.stringify`` would omit
+    from an object (functions/undefined have no Python equivalent, so the only
+    droppable case here is a plain, unserializable object — we raise on those
+    instead to fail loud rather than silently lose data).
+    """
+    if value is None:
+        return None
+    # bool BEFORE int: isinstance(True, int) is True in Python.
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        # JSON.stringify turns NaN/Infinity into null; match that.
+        return value if math.isfinite(value) else None
+    if isinstance(value, (bytes, bytearray)):
+        # Buffer/Uint8Array -> base64 in the TS twin.
+        return base64.b64encode(bytes(value)).decode("ascii")
+    if isinstance(value, (list, tuple)):
+        out = []
+        for item in value:
+            n = _normalize(item, seen)
+            # In arrays, JSON.stringify turns undefined/dropped into null.
+            out.append(None if n is _DROP else n)
+        return out
+    if isinstance(value, dict):
+        obj_id = id(value)
+        if obj_id in seen:
+            raise ValueError("[canonical_json] cycle detected")
+        seen.add(obj_id)
+        out_obj: dict[str, Any] = {}
+        # Sort keys lexicographically. Keys must be strings for JSON; coerce
+        # non-str keys via str() the way json.dumps(sort_keys=True) would reject,
+        # so we normalize to str first to keep sorting well-defined.
+        for k in sorted(value.keys(), key=lambda x: str(x)):
+            n = _normalize(value[k], seen)
+            if n is _DROP:
+                continue
+            out_obj[str(k)] = n
+        seen.discard(obj_id)
+        return out_obj
+    # Anything else (a custom object, a set, etc.) has no defined canonical form.
+    # Fail loud rather than emit bytes that would not match the TS twin.
+    raise TypeError(
+        f"[canonical_json] value of type {type(value).__name__!r} is not JSON-canonicalizable"
+    )
+
+
+def canonical_json(value: Any) -> str:
+    """Deterministically serialize ``value`` to a canonical JSON string.
+
+    Byte-identical to the TS ``canonicalJson``. Equivalent to
+    ``json.dumps(normalized, sort_keys=True, separators=(",", ":"),
+    ensure_ascii=False)`` where ``normalized`` has already had object keys
+    recursively sorted, non-finite numbers folded to null, and unserializable
+    values dropped/base64-encoded per the rules above.
+
+    We still pass ``sort_keys=True`` to ``json.dumps`` as belt-and-suspenders,
+    but the recursive normalization above is what guarantees the byte match.
+    """
+    norm = _normalize(value, set())
+    return json.dumps(
+        norm,
+        sort_keys=True,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+
+
+def sha256_hex(s: str) -> str:
+    """SHA-256 hex digest of a string (UTF-8) — the platform's record primitive."""
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def hash_entry(seq: int, ts: str, action: Any, prev_hash: str) -> str:
+    """Compute an entry's canonical hash from its content (everything but ``hash``).
+
+    ``hash = sha256(canonical_json({seq, ts, action, prev_hash}))``. The key
+    names in the hashed object use the platform's camelCase (``prevHash``) so the
+    bytes match the TS twin exactly — this differs from the Pythonic
+    ``prev_hash`` field name used on the returned dict.
+    """
+    content = {"seq": seq, "ts": ts, "action": action, "prevHash": prev_hash}
+    return sha256_hex(canonical_json(content))

omega_audit-0.1.0/omega_audit/cli.py

@@ -0,0 +1,104 @@
+"""omega-audit — tamper-evident audit for AI agents (CLI).
+
+    omega-audit verify <ledger.jsonl>   check a ledger's chain (exit 0 intact, 1 tampered)
+    omega-audit demo                     build a 3-record ledger, tamper it, show verify FAIL
+
+Pure, offline, zero-dependency (stdlib only). Exit codes:
+    0 = chain intact   1 = tamper detected   2 = usage error.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+
+from .ledger import Ledger, read_ledger
+from .verify import verify
+
+
+def _usage() -> int:
+    sys.stderr.write("usage:\n")
+    sys.stderr.write("  omega-audit verify <ledger.jsonl>   verify a ledger's hash-chain\n")
+    sys.stderr.write("  omega-audit demo                     see a tampered record fail verification\n")
+    return 2
+
+
+def _print_verify(path: str) -> int:
+    r = verify(path)
+    if r.valid:
+        print(f"✓ {r.records} records — chain intact & tamper-evident")
+        return 0
+    if (r.reason or "").startswith("no such file"):
+        # Missing file ≠ tamper — but it must still fail closed (exit 1).
+        print(f"✗ CANNOT VERIFY: {r.reason}")
+        return 1
+    print(f"✗ TAMPER DETECTED at record {r.broken_at}: {r.reason}")
+    return 1
+
+
+def _run_demo() -> int:
+    print("omega-audit demo — tamper-evident agent audit in one command\n")
+
+    tmp_dir = tempfile.mkdtemp(prefix="omega-audit-demo-")
+    path = os.path.join(tmp_dir, "ledger.jsonl")
+    ledger = Ledger(path)
+
+    # 1) Capture three sample agent actions into a hash-chained ledger.
+    print("1. An agent runs three tool calls. Each one is appended to a hash-chained ledger:\n")
+    ledger.append({"tool": "search_web", "args": {"query": "EU AI Act Article 12"}, "ok": True, "durationMs": 214})
+    ledger.append({"tool": "read_file", "args": {"path": "/reports/q3.md"}, "ok": True, "durationMs": 8})
+    ledger.append({"tool": "send_email", "args": {"to": "auditor@example.com", "subject": "Q3 evidence"}, "ok": True, "durationMs": 501})
+
+    for e in read_ledger(path):
+        tool = e["action"].get("tool") if isinstance(e["action"], dict) else None
+        print(f"   #{e['seq']}  {tool}  hash={e['hash'][:12]}…  prev={e['prevHash'][:12]}…")
+
+    # 2) Verify the untouched ledger — it passes.
+    print("\n2. Verify the untouched ledger:\n")
+    print("   $ omega-audit verify ledger.jsonl")
+    sys.stdout.write("   ")
+    _print_verify(path)
+
+    # 3) Tamper with one record — change what the agent claims it did.
+    print("\n3. Now someone quietly edits record #2 to hide who the email went to:\n")
+    with open(path, "r", encoding="utf-8") as fh:
+        lines = fh.read().strip().split("\n")
+    tampered = json.loads(lines[2])
+    before = tampered["action"]["args"].get("to")
+    print(f"   before:  send_email → {before}")
+    tampered["action"]["args"]["to"] = "attacker@evil.example"  # edit payload, leave the hash
+    print(f"   after:   send_email → {tampered['action']['args']['to']}   (hash left unchanged to hide the edit)")
+    lines[2] = json.dumps(tampered, ensure_ascii=False, separators=(",", ":"))
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines) + "\n")
+
+    # 4) Verify again — the recomputed hash no longer matches. Tamper is caught.
+    print("\n4. Verify again — the chain no longer recomputes:\n")
+    print("   $ omega-audit verify ledger.jsonl")
+    sys.stdout.write("   ")
+    code = _print_verify(path)
+
+    print("\nThat ✗ is the whole point: the record was changed, and verification proved it.")
+    print("Nothing here touched the network. You can run the same check on your own ledger.")
+    return code  # 1 when the tamper was caught — that is the expected demo result
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    cmd = args[0] if args else None
+
+    if cmd == "verify":
+        if len(args) < 2 or not args[1]:
+            return _usage()
+        return _print_verify(args[1])
+    if cmd == "demo":
+        # `demo` exits 1: its job is to prove a tampered ledger FAILS verification,
+        # and the resulting exit-1 is the signal a CI check or a reader can rely on.
+        return _run_demo()
+    return _usage()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

omega_audit-0.1.0/omega_audit/ledger.py

@@ -0,0 +1,109 @@
+"""The append-only, hash-chained ledger.
+
+A ledger is a plain JSONL file: one JSON object per line. Each line is an entry
+
+    {"seq", "ts", "action", "prevHash", "hash"}
+
+written with the SAME field names the TypeScript twin writes (note ``prevHash``
+in camelCase on disk — this is deliberate: it makes a Python-written ledger and
+a TS-written ledger the same bytes, so they cross-verify and can be anchored to
+the same transparency log). The genesis entry's ``prevHash`` is 64 zeros.
+
+Offline: no network, no signup. Each ``append`` reads the tail hash, links the
+new record to it, hashes the record, and writes one line.
+
+Zero runtime dependencies: only ``json``/``time`` from stdlib (plus ``canonical``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+from .canonical import GENESIS_PREV_HASH, hash_entry
+
+
+def _iso_now() -> str:
+    """UTC timestamp in the same shape the TS twin uses: ``…T…Z`` with millis.
+
+    ``new Date().toISOString()`` yields e.g. ``2026-08-02T09:00:00.000Z``. We
+    match that format (milliseconds, ``Z`` suffix) so timestamps look identical
+    across the two implementations.
+    """
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+def read_ledger(path: str) -> List[Dict[str, Any]]:
+    """Read a JSONL ledger file into a list of entry dicts.
+
+    Ignores blank lines; raises ``ValueError`` on a line that is not valid JSON
+    (a structurally corrupt file). Does NOT check the chain — use ``verify``.
+    Each returned dict has the on-disk keys: ``seq, ts, action, prevHash, hash``.
+    """
+    if not os.path.exists(path):
+        return []
+    out: List[Dict[str, Any]] = []
+    with open(path, "r", encoding="utf-8") as fh:
+        for i, raw in enumerate(fh.read().split("\n")):
+            line = raw.strip()
+            if line == "":
+                continue
+            try:
+                parsed = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"[read_ledger] line {i + 1} is not valid JSON") from exc
+            out.append(parsed)
+    return out
+
+
+class Ledger:
+    """An append-only, hash-chained ledger persisted as JSONL at ``path``.
+
+    Mirrors the TS ``Ledger`` interface: ``append(action) -> dict``, ``size()``,
+    ``tip_hash()``.
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+    def _entries(self) -> List[Dict[str, Any]]:
+        return read_ledger(self.path)
+
+    def size(self) -> int:
+        """Number of records currently in the ledger file."""
+        return len(self._entries())
+
+    def tip_hash(self) -> str:
+        """Hash of the last record (or ``GENESIS_PREV_HASH`` if empty) — the chain tip."""
+        entries = self._entries()
+        return GENESIS_PREV_HASH if not entries else entries[-1]["hash"]
+
+    def append(self, action: Any) -> Dict[str, Any]:
+        """Append an ``action``.
+
+        Reads the current tail hash, builds the next linked+hashed record, and
+        writes one JSON line. Returns the persisted entry dict, keyed with the
+        on-disk field names ``{seq, ts, action, prevHash, hash}`` (so it matches
+        the TS twin's returned entry byte-for-byte when re-serialized).
+        """
+        entries = self._entries()
+        seq = len(entries)
+        prev_hash = GENESIS_PREV_HASH if not entries else entries[-1]["hash"]
+        ts = _iso_now()
+        entry_hash = hash_entry(seq, ts, action, prev_hash)
+        entry = {
+            "seq": seq,
+            "ts": ts,
+            "action": action,
+            "prevHash": prev_hash,
+            "hash": entry_hash,
+        }
+        # One JSON line, no whitespace, non-ASCII preserved — same shape the TS
+        # twin writes via JSON.stringify.
+        line = json.dumps(entry, ensure_ascii=False, separators=(",", ":"))
+        with open(self.path, "a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+        return entry

omega_audit-0.1.0/omega_audit/verify.py

@@ -0,0 +1,97 @@
+"""Chain verification — recompute the whole chain and report any tampering.
+
+Detects ANY tampering — an edit to any field, a reordering, an inserted record,
+or a deleted record — because each record's ``hash`` covers its content and its
+``prevHash`` must equal the previous record's ``hash``. Pure and offline. This
+is the same logic as the TS twin's ``verify`` / ``verifyEntries``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .canonical import GENESIS_PREV_HASH, hash_entry
+from .ledger import read_ledger
+
+
+@dataclass
+class VerifyResult:
+    """Outcome of verifying a ledger.
+
+    ``broken_at`` is the zero-based index of the first record that fails the
+    chain (``None`` when valid). ``reason`` is a human-readable explanation,
+    present iff ``not valid``.
+    """
+
+    valid: bool
+    records: int
+    broken_at: Optional[int] = None
+    reason: Optional[str] = None
+
+
+def _short(h: Any) -> str:
+    if isinstance(h, str) and len(h) > 12:
+        return f"{h[:8]}…{h[-4:]}"
+    return str(h)
+
+
+def verify_entries(entries: List[Dict[str, Any]]) -> VerifyResult:
+    """Verify already-parsed entry dicts (same logic as ``verify`` without I/O)."""
+    expected_prev = GENESIS_PREV_HASH
+    for i, e in enumerate(entries):
+        if not isinstance(e, dict):
+            return VerifyResult(False, len(entries), i, f"record {i} is not an object")
+
+        if e.get("seq") != i:
+            return VerifyResult(
+                False,
+                len(entries),
+                i,
+                f"record {i} has seq {e.get('seq')} — expected {i} "
+                "(a record was reordered, inserted, or deleted)",
+            )
+
+        prev = e.get("prevHash")
+        if prev != expected_prev:
+            if i == 0:
+                reason = (
+                    f"record 0 must link to the genesis hash "
+                    f"({GENESIS_PREV_HASH[:8]}…) but links to {_short(prev)}"
+                )
+            else:
+                reason = (
+                    f"record {i} does not link to record {i - 1} "
+                    f"(prevHash {_short(prev)} ≠ {_short(expected_prev)}) "
+                    "— a record was altered, inserted, or deleted"
+                )
+            return VerifyResult(False, len(entries), i, reason)
+
+        recomputed = hash_entry(e.get("seq"), e.get("ts"), e.get("action"), e.get("prevHash"))
+        if recomputed != e.get("hash"):
+            return VerifyResult(
+                False,
+                len(entries),
+                i,
+                f"record {i} was edited — its stored hash {_short(e.get('hash'))} "
+                f"≠ the recomputed hash {_short(recomputed)}",
+            )
+
+        expected_prev = e["hash"]
+
+    return VerifyResult(True, len(entries))
+
+
+def verify(path: str) -> VerifyResult:
+    """Recompute the entire chain from a JSONL ledger file and report integrity."""
+    # Fail closed: read_ledger treats a missing file as an empty ledger (right for
+    # the append path), but for verification "file not found" must never report
+    # "chain intact" — an auditor with a typo'd path would get a green check.
+    if not os.path.exists(path):
+        return VerifyResult(False, 0, 0, f"no such file: {path}")
+    try:
+        entries = read_ledger(path)
+    except Exception as exc:  # a structurally corrupt file is itself a failure
+        return VerifyResult(False, 0, 0, str(exc))
+    return verify_entries(entries)

omega_audit-0.1.0/omega_audit/wrap.py

@@ -0,0 +1,114 @@
+"""Wrapping tool calls — record every invocation to the ledger.
+
+``wrap_tool(ledger, name, fn)`` returns a wrapper that appends a
+``{"tool", "args", "ok", "result"|"error", "duration_ms"}`` record for every
+call, then returns or raises EXACTLY as the original did.
+
+Python agents are frequently async, so both sync and async callables are
+supported: if ``fn`` is a coroutine function the wrapper is itself a coroutine
+function (so ``await wrapped(...)`` works and the record is written when the
+awaited call settles); otherwise the wrapper is an ordinary function.
+
+The recorded ``args`` mirror the TS twin: positional arguments as a list. When
+keyword arguments are also passed, they are recorded under a ``kwargs`` key so
+nothing about the call is lost.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+from typing import Any, Callable
+
+from .ledger import Ledger
+
+
+def _record_args(args: tuple, kwargs: dict) -> Any:
+    """Shape call arguments for the ledger.
+
+    Positional-only calls record ``args`` as a plain list (identical to the TS
+    twin, where a tool is called positionally). If keyword arguments are present
+    we record ``{"args": [...], "kwargs": {...}}`` so the record stays complete.
+    """
+    if kwargs:
+        return {"args": list(args), "kwargs": dict(kwargs)}
+    return list(args)
+
+
+def wrap_tool(ledger: Ledger, name: str, fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap a named tool so every call is appended to ``ledger``.
+
+    Works for sync and async ``fn``. Returns/raises unchanged; on a raised
+    exception the record is written with ``ok=False`` and the error message, and
+    the exception is re-raised (never swallowed).
+    """
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def async_wrapped(*args: Any, **kwargs: Any) -> Any:
+            start = time.monotonic()
+            try:
+                result = await fn(*args, **kwargs)
+                ledger.append(
+                    {
+                        "tool": name,
+                        "args": _record_args(args, kwargs),
+                        "ok": True,
+                        "result": result,
+                        "duration_ms": int((time.monotonic() - start) * 1000),
+                    }
+                )
+                return result
+            except Exception as err:  # noqa: BLE001 — record then re-raise unchanged
+                ledger.append(
+                    {
+                        "tool": name,
+                        "args": _record_args(args, kwargs),
+                        "ok": False,
+                        "error": str(err),
+                        "duration_ms": int((time.monotonic() - start) * 1000),
+                    }
+                )
+                raise
+
+        return async_wrapped
+
+    @functools.wraps(fn)
+    def sync_wrapped(*args: Any, **kwargs: Any) -> Any:
+        start = time.monotonic()
+        try:
+            result = fn(*args, **kwargs)
+            ledger.append(
+                {
+                    "tool": name,
+                    "args": _record_args(args, kwargs),
+                    "ok": True,
+                    "result": result,
+                    "duration_ms": int((time.monotonic() - start) * 1000),
+                }
+            )
+            return result
+        except Exception as err:  # noqa: BLE001 — record then re-raise unchanged
+            ledger.append(
+                {
+                    "tool": name,
+                    "args": _record_args(args, kwargs),
+                    "ok": False,
+                    "error": str(err),
+                    "duration_ms": int((time.monotonic() - start) * 1000),
+                }
+            )
+            raise
+
+    return sync_wrapped
+
+
+def capture(ledger: Ledger, fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Convenience alias: wrap a tool under its own ``__name__``.
+
+    Equivalent to ``wrap_tool(ledger, fn.__name__, fn)``. Handy for wrapping
+    named functions inline.
+    """
+    name = getattr(fn, "__name__", "") or "anonymous"
+    return wrap_tool(ledger, name, fn)

omega_audit-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "omega-audit"
+version = "0.1.0"
+description = "Tamper-evident audit + provenance for AI agents — an offline, zero-dependency, hash-chained append-only ledger. Wrap your agent's tool calls, then prove what it did: any edit, reorder, insertion, or deletion fails verification."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [
+    { name = "OmegaEngine", email = "team@omegaengine.ai" }
+]
+keywords = [
+    "ai-agents",
+    "audit-log",
+    "tamper-evident",
+    "hash-chain",
+    "provenance",
+    "append-only",
+    "eu-ai-act",
+    "compliance",
+    "sha256",
+    "omegaengine",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+]
+
+# Zero runtime dependencies — stdlib only (hashlib / json / base64 / datetime).
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.scripts]
+omega-audit = "omega_audit.cli:main"
+
+[project.urls]
+Homepage = "https://omegaengine.ai"
+Documentation = "https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-audit-py#readme"
+Repository = "https://github.com/TheArkhitect/Omegaengine/tree/main/packages/omega-audit-py"
+Issues = "https://github.com/TheArkhitect/Omegaengine/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/omega_audit",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["omega_audit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]