once-guard
Stop your AI agent from charging, booking or sending twice.
once-guard is the Python core of agent-once. It gives every side-effecting function your agent calls a stable identity, records it in a local SQLite ledger before it runs, and on a repeat either returns the recorded result, checks what really happened, or stops and asks. The promise: at most once by default, exactly once wherever a reconciler can confirm the outcome.
pip install once-guard
The distribution is named once-guard because agent-once on PyPI is an unrelated project; the import name is agent_once. Python 3.10 or later, no runtime dependencies.
import os
import uuid
from agent_once import Guard, JsonlEvidence, SqliteLedgerStore, SystemClock, default_ledger_path
clock = SystemClock()
store = SqliteLedgerStore.open(default_ledger_path(os.environ, os.path.expanduser("~")), clock)
guard = Guard(store, clock, str(uuid.uuid4()), JsonlEvidence("agent-once-events.jsonl"))
@guard.tool(policy="block-on-doubt", tool_class="money", session_key="order-run-42")
def place_order(item: str, qty: int) -> dict[str, object]:
return {"order": "ORD-1", "item": item, "qty": qty}
place_order("Blue mug", 1)
A repeat of a call whose outcome is unknown raises ActionInDoubt instead of running again. Reconcilers, guard.run and guard.arun with idempotency keys, and the pytest fixtures (once_guard, once_clock, agent_once_chaos_targets) are described in the Python guide.
The ledger format is shared with the npm package agent-once, which provides the MCP proxy for Claude Code, Claude Desktop, Cursor and any other MCP client. Both can use the same ledger file (format spec).
No telemetry. Licence: Apache 2.0.
Metadata
Release files for once-guard 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| once_guard-0.1.0.tar.gz | 26.1 kB | Without provenance | Details for once_guard-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| once_guard-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for once_guard-0.1.0-py3-none-any.whl |
Total release size: 59.8 kB
Release files / once_guard-0.1.0.tar.gz
| Download URL | once_guard-0.1.0.tar.gz |
|---|---|
| Size | 26.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f1a7553a7541b88b1271e6da15888006eebcadde9c8ac503f621049787e57ebd
|
|
BLAKE2b-256 checksum How to use checksums |
bc92f9a3176a11a86837a4dbe204562de525e7691ac0d85b6a6bcf789f8d8e71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / once_guard-0.1.0-py3-none-any.whl
| Download URL | once_guard-0.1.0-py3-none-any.whl |
|---|---|
| Size | 33.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
656b743b5f970e249f1ee913b998d33c24b0667ee4568e704cd73ac6394ee4a9
|
|
BLAKE2b-256 checksum How to use checksums |
061d7fbc413583724ba476e1fbf4576595ed6c77669e1dfb3a12c21082c983d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for once-guard 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.