toolwrit 0.2.0__tar.gz

toolwrit-0.2.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: toolwrit
+Version: 0.2.0
+Summary: A written authority for AI agents. Allowlist the tools, cap the budget, prove what happened.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/emektor/toolwrit
+Project-URL: Repository, https://github.com/emektor/toolwrit
+Project-URL: Issues, https://github.com/emektor/toolwrit/issues
+Keywords: ai,agent,guardrails,mcp,tool-calling,policy,audit,llm,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# toolwrit
+
+A written authority for AI agents. Allowlist the tools, cap the budget, prove
+what happened.
+
+This is the Python port of
+[Toolwrit](https://github.com/emektor/toolwrit). **The full documentation lives
+in the main project's docs** — the policy language, the threat model and the
+design rationale are the same here, clause for clause:
+
+- [the overview](https://github.com/emektor/toolwrit#readme) — run plans, the
+  bytes ceiling, receipts and anchoring.
+- [`policy-reference.md`](https://github.com/emektor/toolwrit/blob/main/js/docs/policy-reference.md) — every
+  policy field with a worked example.
+- [`threat-model.md`](https://github.com/emektor/toolwrit/blob/main/js/docs/threat-model.md) — what is and is
+  not defended against.
+- [`python.md`](https://github.com/emektor/toolwrit/blob/main/js/docs/python.md) — the Python-specific
+  reference: the full API table, the sync/async split, and everything below in
+  more detail.
+
+What follows is only what a Python user needs on top of that.
+
+```bash
+pip install toolwrit
+```
+
+Until the first release is published:
+`pip install "git+https://github.com/emektor/toolwrit.git#subdirectory=python"`
+
+```python
+from toolwrit import Toolwrit, ToolwritDenied, load_policy_file
+
+toolwrit = Toolwrit(load_policy_file("policy.yaml"), audit_file="audit.jsonl")
+
+try:
+    contents = toolwrit.guard("fs.read", {"path": "/tmp/notes"}, lambda: read_file())
+except ToolwritDenied as denied:
+    print(denied.decision.reason, denied.audit_hash)
+
+toolwrit.meter(1200, 350)          # input tokens, output tokens
+print(toolwrit.usage())            # BudgetUsage(calls=…, tokens=…, usd=…, bytes=…, started_at=…)
+print(toolwrit.head())             # the head of this run's audit chain
+```
+
+```bash
+toolwrit check   --policy policy.yaml --tool fs.read --args '{"path":"/tmp/x"}'
+toolwrit explain --policy policy.yaml
+toolwrit verify  audit.jsonl
+```
+
+## Run plans
+
+A `plan:` block declares the envelope a run is approved for, and it works here
+exactly as it does in TypeScript.
+
+```yaml
+budget:
+  calls: 200
+  usd: 5.00
+  bytes: 20000000
+  seconds: 3600
+
+plan:
+  purpose: nightly CRM export for the EU region
+  approvedBy: ergin
+  warnAt: [0.8, 0.95]     # the default
+```
+
+The argument for declaring an envelope rather than setting a global threshold:
+a global threshold has to guess at every job at once, so it is either too loose
+to catch anything or too tight to leave switched on — and an alert people mute
+is the same as no alert. A declared envelope does not guess. Approve once at
+the start, hear nothing until a threshold.
+
+```python
+toolwrit = Toolwrit(
+    load_policy_file("export.yaml"),
+    run="nightly-2026-09-12",
+    audit_file="audit.jsonl",
+    on_warn=lambda w: print("on_warn ->", w.message),
+)
+```
+
+```
+on_warn -> run "nightly-2026-09-12" (nightly CRM export for the EU region) has used 16,000,000/20,000,000 bytes — 80% of the approved envelope
+```
+
+Two properties worth knowing:
+
+- **The plan is entry 1 of the audit chain**, written by the constructor before
+  anything can be guarded. What was *authorised* is in the tamper-evident record
+  alongside what happened.
+- **Each threshold fires at most once per dimension**, across `calls`, `tokens`,
+  `usd`, `bytes` and `seconds`, and every warning is recorded in the chain as a
+  `toolwrit:warning` entry as well as delivered to `on_warn`. Keep `on_warn`
+  non-blocking; it runs inline with metering.
+
+A `plan` requires a `budget` to measure against, `purpose` must be non-empty,
+and `warnAt` entries must be greater than 0 and at most 1. All three are load
+errors, with the same messages as the TypeScript implementation.
+
+## The bytes ceiling
+
+`budget.bytes` caps the total size of what tools **return** over a run. Bulk
+exfiltration is rarely a forbidden action — it is a permitted action repeated
+until something is drained, so every individual call passes the allowlist and
+only the running total gives it away. Unlike `usd` and `tokens`, this dimension
+needs no cooperation from your integration: `guard` and `guard_async` feed it.
+
+```
+call 5: ok, bytes now 20000000
+call 6: toolwrit: crm.search denied — data budget exhausted: 20000000/20000000 bytes returned by tools
+```
+
+**The limitation, stated up front.** A result's size is not knowable before the
+tool runs, so the measurement happens afterwards: the call that blows the
+ceiling **completes**, and the **next** one is refused. A bytes ceiling bounds a
+run at the limit *plus one call*, never exactly the limit. If one call can
+return everything, cap the response at the tool.
+
+Sizes: `None` → 0; `str` → its UTF-8 byte length; `bytes`/`bytearray`/
+`memoryview` → their length; anything else → the UTF-8 byte length of its
+canonical JSON, which equals what TypeScript gets from `JSON.stringify`. A
+result that cannot be serialised falls back to `str(result)` and is therefore
+**under-counted** — documented rather than hidden, because under-counting a
+volume ceiling fails open.
+
+## Receipts and anchoring: use the TypeScript CLI
+
+Run receipts (`summarize`, `verifyAgainstReceipt`) and the `toolwrit receipt`,
+`toolwrit anchor` and `toolwrit verify --against` subcommands are **not ported**.
+Because the chains are compatible, that is not a blocker — point the TypeScript
+CLI at a Python-written log:
+
+```bash
+toolwrit receipt audit.jsonl                        # written by toolwrit for Python
+toolwrit anchor  audit.jsonl --to anchors.jsonl
+toolwrit verify  audit.jsonl --against anchors.jsonl
+```
+
+This matters more than it sounds. Verifying a chain in isolation **cannot**
+detect that its tail was cut off: a prefix of a valid chain is itself a valid
+chain and verifies clean, so an agent that deletes its last twenty entries hands
+you a log that passes. Comparing against a receipt anchored at the time closes
+that hole — and only if the anchor lives where the agent cannot rewrite it,
+which Toolwrit cannot enforce.
+
+The Python `toolwrit verify` **refuses** `--against` rather than ignoring it:
+
+```
+$ toolwrit verify truncated.jsonl --against anchors.jsonl
+toolwrit: `verify --against <anchor>` is not implemented in the Python CLI; ...
+$ echo $?
+1
+```
+
+Accepting the flag and dropping it would print `ok` and exit 0 on precisely the
+truncated log the flag exists to catch — a fail-open in the one command whose
+job is detecting tampering. Every subcommand rejects flags it does not
+implement for the same reason. Use the TypeScript CLI for anchoring; it reads
+chains written here.
+
+## Chain compatibility
+
+An audit chain written here verifies under the TypeScript `toolwrit verify`, and
+one written there verifies here — same canonical string, same SHA-256, same
+head hash. `tests/test_interop.py` proves it in both directions, and goes
+further than "both say ok": it builds the same chain with both implementations
+and asserts the entry hashes are equal, which no pair of mutually incompatible
+serialisers could manage.
+
+Getting there is mostly about numbers. JavaScript has one numeric type and
+prints it with `Number::toString` — `1.0` is `"1"`, `1e21` is `"1e+21"`, `1e16`
+is `"10000000000000000"` — where Python's `repr` keeps the `.0` and switches to
+exponent notation at a different magnitude. `toolwrit._js` implements the
+ECMAScript algorithm directly; `test_audit.py` pins the values one by one.
+
+## Differences from the TypeScript version
+
+Behaviour is otherwise identical. These are the exceptions, and none of them
+loosens a policy.
+
+**`None` is `null`, not `undefined`.** JavaScript has two empty values and
+`JSON.stringify` treats them differently: `null` is serialised, `undefined` is
+dropped. Python has one. Since `decision.rule` is legitimately `null` on every
+default-deny and the TypeScript chain commits to it, `canonicalize` **keeps**
+`None` as `null` — dropping it would break the chain outright. The "drop me"
+meaning is carried by an explicit `toolwrit._js.UNDEFINED` sentinel instead.
+
+The visible consequence is in constraints: an argument key present but set to
+`None` counts as **absent**, so it fails a non-`optional` constraint with a
+`required` violation. TypeScript would call `{"path": null}` a present null and
+report a `type` violation instead. Both refuse the call; only the violation
+name differs.
+
+**`guard` is split in two.** Python cannot await from a synchronous frame, so
+`guard(tool, args, execute)` serves ordinary functions and
+`await guard_async(tool, args, execute)` awaits whatever it is given — an async
+tool, an async `on_ask` handler, or plain functions unchanged. Passing an async
+`on_ask` to the synchronous `guard` raises `TypeError` rather than guessing.
+
+**`toolwrit run` is not ported.** The MCP stdio proxy and the Anthropic/OpenAI SDK
+adapters stay in the TypeScript package; `toolwrit run` here exits 1 and says so.
+`check`, `explain` and `verify` behave identically, exit codes included.
+
+**Run receipts and anchoring are not ported.** There is no `summarize` or
+`verify_against_receipt`, and no `receipt`, `anchor` or working `verify
+--against` in this CLI. Use the TypeScript CLI over the Python-written log; see
+the section above.
+
+**Regexes are Python regexes.** A `matches:` pattern is compiled with `re`, not
+V8's `RegExp`. The common syntax is shared, but the dialects diverge on named
+groups (`(?P<x>)` vs `(?<x>)`), lookbehind and the Unicode semantics of `\d`
+and `\w`. A policy shared between the two implementations should stay inside
+the common subset.
+
+**URLs are parsed with `urllib.parse`,** with an explicit absolute-URL gate
+(scheme required, declared authority must exist) standing in for the throw that
+WHATWG `new URL()` performs. The tested behaviour matches, including the
+`https://example.com@evil.com/` case. Two untested corners differ: an IPv6 host
+comes back as `::1` rather than `[::1]`, and an internationalised domain is not
+converted to punycode, so an IDN `urlHosts` entry must be written in the same
+form the argument uses.
+
+**YAML is YAML 1.1.** PyYAML implements 1.1, the TypeScript `yaml` package
+implements 1.2. The difference a policy author can hit is bare `yes`/`no`/
+`on`/`off`, which PyYAML reads as booleans and the TypeScript reads as strings.
+Quote them. JSON parses identically under both.
+
+**The JSONL byte layout differs cosmetically.** Within a violation object this
+port writes `path` last where the TypeScript writes it second. The canonical
+form sorts keys, so the hashes are unaffected and each implementation verifies
+the other's file; only a byte-for-byte `diff` of the two logs shows it.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+python -m pytest
+```
+
+The cross-language tests need `node` and a built copy of the TypeScript
+implementation; they look for it at `../js` or at `$TOOLWRIT_TS_ROOT`, and skip
+when it is absent.
+
+## Licence
+
+Apache-2.0.

toolwrit-0.2.0/README.md

@@ -0,0 +1,248 @@
+# toolwrit
+
+A written authority for AI agents. Allowlist the tools, cap the budget, prove
+what happened.
+
+This is the Python port of
+[Toolwrit](https://github.com/emektor/toolwrit). **The full documentation lives
+in the main project's docs** — the policy language, the threat model and the
+design rationale are the same here, clause for clause:
+
+- [the overview](https://github.com/emektor/toolwrit#readme) — run plans, the
+  bytes ceiling, receipts and anchoring.
+- [`policy-reference.md`](https://github.com/emektor/toolwrit/blob/main/js/docs/policy-reference.md) — every
+  policy field with a worked example.
+- [`threat-model.md`](https://github.com/emektor/toolwrit/blob/main/js/docs/threat-model.md) — what is and is
+  not defended against.
+- [`python.md`](https://github.com/emektor/toolwrit/blob/main/js/docs/python.md) — the Python-specific
+  reference: the full API table, the sync/async split, and everything below in
+  more detail.
+
+What follows is only what a Python user needs on top of that.
+
+```bash
+pip install toolwrit
+```
+
+Until the first release is published:
+`pip install "git+https://github.com/emektor/toolwrit.git#subdirectory=python"`
+
+```python
+from toolwrit import Toolwrit, ToolwritDenied, load_policy_file
+
+toolwrit = Toolwrit(load_policy_file("policy.yaml"), audit_file="audit.jsonl")
+
+try:
+    contents = toolwrit.guard("fs.read", {"path": "/tmp/notes"}, lambda: read_file())
+except ToolwritDenied as denied:
+    print(denied.decision.reason, denied.audit_hash)
+
+toolwrit.meter(1200, 350)          # input tokens, output tokens
+print(toolwrit.usage())            # BudgetUsage(calls=…, tokens=…, usd=…, bytes=…, started_at=…)
+print(toolwrit.head())             # the head of this run's audit chain
+```
+
+```bash
+toolwrit check   --policy policy.yaml --tool fs.read --args '{"path":"/tmp/x"}'
+toolwrit explain --policy policy.yaml
+toolwrit verify  audit.jsonl
+```
+
+## Run plans
+
+A `plan:` block declares the envelope a run is approved for, and it works here
+exactly as it does in TypeScript.
+
+```yaml
+budget:
+  calls: 200
+  usd: 5.00
+  bytes: 20000000
+  seconds: 3600
+
+plan:
+  purpose: nightly CRM export for the EU region
+  approvedBy: ergin
+  warnAt: [0.8, 0.95]     # the default
+```
+
+The argument for declaring an envelope rather than setting a global threshold:
+a global threshold has to guess at every job at once, so it is either too loose
+to catch anything or too tight to leave switched on — and an alert people mute
+is the same as no alert. A declared envelope does not guess. Approve once at
+the start, hear nothing until a threshold.
+
+```python
+toolwrit = Toolwrit(
+    load_policy_file("export.yaml"),
+    run="nightly-2026-09-12",
+    audit_file="audit.jsonl",
+    on_warn=lambda w: print("on_warn ->", w.message),
+)
+```
+
+```
+on_warn -> run "nightly-2026-09-12" (nightly CRM export for the EU region) has used 16,000,000/20,000,000 bytes — 80% of the approved envelope
+```
+
+Two properties worth knowing:
+
+- **The plan is entry 1 of the audit chain**, written by the constructor before
+  anything can be guarded. What was *authorised* is in the tamper-evident record
+  alongside what happened.
+- **Each threshold fires at most once per dimension**, across `calls`, `tokens`,
+  `usd`, `bytes` and `seconds`, and every warning is recorded in the chain as a
+  `toolwrit:warning` entry as well as delivered to `on_warn`. Keep `on_warn`
+  non-blocking; it runs inline with metering.
+
+A `plan` requires a `budget` to measure against, `purpose` must be non-empty,
+and `warnAt` entries must be greater than 0 and at most 1. All three are load
+errors, with the same messages as the TypeScript implementation.
+
+## The bytes ceiling
+
+`budget.bytes` caps the total size of what tools **return** over a run. Bulk
+exfiltration is rarely a forbidden action — it is a permitted action repeated
+until something is drained, so every individual call passes the allowlist and
+only the running total gives it away. Unlike `usd` and `tokens`, this dimension
+needs no cooperation from your integration: `guard` and `guard_async` feed it.
+
+```
+call 5: ok, bytes now 20000000
+call 6: toolwrit: crm.search denied — data budget exhausted: 20000000/20000000 bytes returned by tools
+```
+
+**The limitation, stated up front.** A result's size is not knowable before the
+tool runs, so the measurement happens afterwards: the call that blows the
+ceiling **completes**, and the **next** one is refused. A bytes ceiling bounds a
+run at the limit *plus one call*, never exactly the limit. If one call can
+return everything, cap the response at the tool.
+
+Sizes: `None` → 0; `str` → its UTF-8 byte length; `bytes`/`bytearray`/
+`memoryview` → their length; anything else → the UTF-8 byte length of its
+canonical JSON, which equals what TypeScript gets from `JSON.stringify`. A
+result that cannot be serialised falls back to `str(result)` and is therefore
+**under-counted** — documented rather than hidden, because under-counting a
+volume ceiling fails open.
+
+## Receipts and anchoring: use the TypeScript CLI
+
+Run receipts (`summarize`, `verifyAgainstReceipt`) and the `toolwrit receipt`,
+`toolwrit anchor` and `toolwrit verify --against` subcommands are **not ported**.
+Because the chains are compatible, that is not a blocker — point the TypeScript
+CLI at a Python-written log:
+
+```bash
+toolwrit receipt audit.jsonl                        # written by toolwrit for Python
+toolwrit anchor  audit.jsonl --to anchors.jsonl
+toolwrit verify  audit.jsonl --against anchors.jsonl
+```
+
+This matters more than it sounds. Verifying a chain in isolation **cannot**
+detect that its tail was cut off: a prefix of a valid chain is itself a valid
+chain and verifies clean, so an agent that deletes its last twenty entries hands
+you a log that passes. Comparing against a receipt anchored at the time closes
+that hole — and only if the anchor lives where the agent cannot rewrite it,
+which Toolwrit cannot enforce.
+
+The Python `toolwrit verify` **refuses** `--against` rather than ignoring it:
+
+```
+$ toolwrit verify truncated.jsonl --against anchors.jsonl
+toolwrit: `verify --against <anchor>` is not implemented in the Python CLI; ...
+$ echo $?
+1
+```
+
+Accepting the flag and dropping it would print `ok` and exit 0 on precisely the
+truncated log the flag exists to catch — a fail-open in the one command whose
+job is detecting tampering. Every subcommand rejects flags it does not
+implement for the same reason. Use the TypeScript CLI for anchoring; it reads
+chains written here.
+
+## Chain compatibility
+
+An audit chain written here verifies under the TypeScript `toolwrit verify`, and
+one written there verifies here — same canonical string, same SHA-256, same
+head hash. `tests/test_interop.py` proves it in both directions, and goes
+further than "both say ok": it builds the same chain with both implementations
+and asserts the entry hashes are equal, which no pair of mutually incompatible
+serialisers could manage.
+
+Getting there is mostly about numbers. JavaScript has one numeric type and
+prints it with `Number::toString` — `1.0` is `"1"`, `1e21` is `"1e+21"`, `1e16`
+is `"10000000000000000"` — where Python's `repr` keeps the `.0` and switches to
+exponent notation at a different magnitude. `toolwrit._js` implements the
+ECMAScript algorithm directly; `test_audit.py` pins the values one by one.
+
+## Differences from the TypeScript version
+
+Behaviour is otherwise identical. These are the exceptions, and none of them
+loosens a policy.
+
+**`None` is `null`, not `undefined`.** JavaScript has two empty values and
+`JSON.stringify` treats them differently: `null` is serialised, `undefined` is
+dropped. Python has one. Since `decision.rule` is legitimately `null` on every
+default-deny and the TypeScript chain commits to it, `canonicalize` **keeps**
+`None` as `null` — dropping it would break the chain outright. The "drop me"
+meaning is carried by an explicit `toolwrit._js.UNDEFINED` sentinel instead.
+
+The visible consequence is in constraints: an argument key present but set to
+`None` counts as **absent**, so it fails a non-`optional` constraint with a
+`required` violation. TypeScript would call `{"path": null}` a present null and
+report a `type` violation instead. Both refuse the call; only the violation
+name differs.
+
+**`guard` is split in two.** Python cannot await from a synchronous frame, so
+`guard(tool, args, execute)` serves ordinary functions and
+`await guard_async(tool, args, execute)` awaits whatever it is given — an async
+tool, an async `on_ask` handler, or plain functions unchanged. Passing an async
+`on_ask` to the synchronous `guard` raises `TypeError` rather than guessing.
+
+**`toolwrit run` is not ported.** The MCP stdio proxy and the Anthropic/OpenAI SDK
+adapters stay in the TypeScript package; `toolwrit run` here exits 1 and says so.
+`check`, `explain` and `verify` behave identically, exit codes included.
+
+**Run receipts and anchoring are not ported.** There is no `summarize` or
+`verify_against_receipt`, and no `receipt`, `anchor` or working `verify
+--against` in this CLI. Use the TypeScript CLI over the Python-written log; see
+the section above.
+
+**Regexes are Python regexes.** A `matches:` pattern is compiled with `re`, not
+V8's `RegExp`. The common syntax is shared, but the dialects diverge on named
+groups (`(?P<x>)` vs `(?<x>)`), lookbehind and the Unicode semantics of `\d`
+and `\w`. A policy shared between the two implementations should stay inside
+the common subset.
+
+**URLs are parsed with `urllib.parse`,** with an explicit absolute-URL gate
+(scheme required, declared authority must exist) standing in for the throw that
+WHATWG `new URL()` performs. The tested behaviour matches, including the
+`https://example.com@evil.com/` case. Two untested corners differ: an IPv6 host
+comes back as `::1` rather than `[::1]`, and an internationalised domain is not
+converted to punycode, so an IDN `urlHosts` entry must be written in the same
+form the argument uses.
+
+**YAML is YAML 1.1.** PyYAML implements 1.1, the TypeScript `yaml` package
+implements 1.2. The difference a policy author can hit is bare `yes`/`no`/
+`on`/`off`, which PyYAML reads as booleans and the TypeScript reads as strings.
+Quote them. JSON parses identically under both.
+
+**The JSONL byte layout differs cosmetically.** Within a violation object this
+port writes `path` last where the TypeScript writes it second. The canonical
+form sorts keys, so the hashes are unaffected and each implementation verifies
+the other's file; only a byte-for-byte `diff` of the two logs shows it.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+python -m pytest
+```
+
+The cross-language tests need `node` and a built copy of the TypeScript
+implementation; they look for it at `../js` or at `$TOOLWRIT_TS_ROOT`, and skip
+when it is absent.
+
+## Licence
+
+Apache-2.0.

toolwrit-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toolwrit"
+version = "0.2.0"
+description = "A written authority for AI agents. Allowlist the tools, cap the budget, prove what happened."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+keywords = [
+    "ai", "agent", "guardrails", "mcp", "tool-calling",
+    "policy", "audit", "llm", "security",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = ["pyyaml>=6"]
+
+[project.urls]
+Homepage = "https://github.com/emektor/toolwrit"
+Repository = "https://github.com/emektor/toolwrit"
+Issues = "https://github.com/emektor/toolwrit/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+toolwrit = "toolwrit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

toolwrit-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toolwrit-0.2.0/src/toolwrit/__init__.py

@@ -0,0 +1,95 @@
+"""
+Toolwrit — a written authority for AI agents.
+
+Allowlist the tools, cap the budget, prove what happened.
+
+A Python port of the TypeScript reference implementation. The audit chains the
+two produce are byte-compatible: a log written here verifies under
+``toolwrit verify`` from the npm package, and vice versa.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .audit.chain import (
+    GENESIS,
+    AuditEntry,
+    AuditLog,
+    AuditLogOptions,
+    canonicalize,
+    entry_from_dict,
+    entry_to_dict,
+    hash_entry,
+)
+from .audit.verify import VerifyFailure, VerifyResult, verify_chain, verify_file
+from .budget.ledger import Ledger, TokenPrice
+from .toolwrit import ApprovalHandler, Toolwrit, ToolwritDenied
+from .policy.engine import evaluate
+from .policy.load import PolicyError, load_policy_file, parse_policy, validate_policy
+from .policy.match import MISSING, matches_any_glob, matches_glob, resolve_path
+from .types import (
+    ArgConstraint,
+    BudgetLimits,
+    BudgetUsage,
+    BudgetWarning,
+    Decision,
+    Effect,
+    EvalContext,
+    HistoryEntry,
+    Policy,
+    PolicyRule,
+    RateLimit,
+    RunPlan,
+    ToolCall,
+    Violation,
+)
+
+__all__ = [
+    "__version__",
+    # runtime
+    "Toolwrit",
+    "ToolwritDenied",
+    "ApprovalHandler",
+    # policy
+    "evaluate",
+    "load_policy_file",
+    "parse_policy",
+    "validate_policy",
+    "PolicyError",
+    "matches_glob",
+    "matches_any_glob",
+    "resolve_path",
+    "MISSING",
+    # budget
+    "Ledger",
+    "TokenPrice",
+    # audit
+    "AuditLog",
+    "AuditLogOptions",
+    "AuditEntry",
+    "canonicalize",
+    "hash_entry",
+    "entry_to_dict",
+    "entry_from_dict",
+    "GENESIS",
+    "verify_chain",
+    "verify_file",
+    "VerifyResult",
+    "VerifyFailure",
+    # types
+    "ArgConstraint",
+    "BudgetLimits",
+    "BudgetUsage",
+    "BudgetWarning",
+    "Decision",
+    "Effect",
+    "EvalContext",
+    "HistoryEntry",
+    "Policy",
+    "PolicyRule",
+    "RateLimit",
+    "RunPlan",
+    "ToolCall",
+    "Violation",
+]