signafaide
Signed, chained records of what your AI agents decided. Each record is signed with the agent's own key and chained on your machine; once you opt in, a witness (the signafAIde service, or one you host) co-signs and publicly timestamps it, so neither side can forge or edit a record alone.
- Nothing is sent until a person runs
signafaide initor setsSIGNAFAIDE_API_KEY. After that each record sends its content hash with its tool name, agent name and time (and its chain links), never its inputs or outputs unless you turn on stored content. Tool and agent names are sent as you write them, so don't put personal data in them. Each content hash is salted with 16 random bytes that stay on your machine with the content, so the hash alone cannot be used to guess the content, even when it has only a few possible values. - The sandbox
initcreates needs no account, email or card. - To keep the evidence in your environment, self-host the witness and set
SIGNAFAIDE_URL(self-host). - Apache-2.0, with a public protocol spec and an independent verifier.
uv add signafaide # a uv project
poetry add signafaide # a Poetry project
python3 -m venv .venv && .venv/bin/python -m pip install signafaide # otherwise, then add it to requirements.txt
Not a bare pip install: most systems' Python refuses it outside a virtual environment (PEP 668, "externally-managed-environment").
import signafaide
@signafaide.record
def approve_payout(claim_id: str, amount: float): ...
signafaide verify # or .venv/bin/signafaide verify, uv run signafaide verify
That's it. With no API key, records are signed, chained and kept in .signafaide/, and nothing is sent. signafaide verify checks every signature, chain link and content hash and ends with a result line that says how many of the 12 checks ran, for example PASS: 4 of 12 checks passed, 8 not checked (nothing co-signed yet). A check that was not run is never counted as passed. It also says what still needs the witness:
co-signature, public timestamp: not yet. Run `signafaide init` to send hashes, or self-host (SIGNAFAIDE_URL)
Sending hashes to a witness
Co-signature and the public timestamp need a witness. A person opts in once:
signafaide initcreates a free sandbox (no account, email or card), savesSIGNAFAIDE_API_KEYto.env, adds.envto.gitignoreand prints a link to claim it; or- set
SIGNAFAIDE_API_KEY(a live key from the console), withSIGNAFAIDE_URLfor a self-hosted witness.SIGNAFAIDE_URLalone sends nothing.
Records written before the opt-in ship afterwards with their original times. The service accepts records up to 7 days old (an agent key's valid_from is at most 7 days before its registration); a local chain that starts earlier stays local, still verifies, and signafaide flush reports it as too_old. signafaide.init() in code only configures: it never creates a sandbox.
What a call records
- A
decisionrecord before the function runs: the tool name, plus{"input": {<argument>: <value>}, "meta": {...}}. - The function runs.
- An
outcomerecord after it:{"output": ...}, or{"error": {"type", "message"}}. The error is raised again unchanged.
Records are signed and chained locally in .signafaide/ (synchronously, in a couple of milliseconds), then, once you opted in, shipped in the background. Sync and async functions both work.
@signafaide.record(agent="claims-bot", name="approve_payout", meta={"model": "gpt-x"})
def approve(claim_id: str, amount: float): ...
signafaide.note("policy_loaded", {"version": 3}) # anything that is not a tool call
Give each agent an explicit name, for example @signafaide.record(agent="claims-bot"); without one it is the project folder's name. It must match ^[a-z0-9][a-z0-9._-]{0,63}$. In production, one agent name is one chain written by one running instance.
Frameworks
tools = signafaide.wrap_tools({"lookup_order": lookup_order, "refund": refund}) # dict: key = name
tools = signafaide.wrap_tools([lookup_order, refund]) # list
wrap_tools (and wrap_tool for one) also takes:
- LangChain tools (
@toolor anyBaseTool). The copy records eachinvoke/ainvoke, including tool calls, and still converts forbind_tools. The outcome holds the tool's own return value, not theToolMessageLangChain wraps it in. - OpenAI Agents SDK
FunctionTools (@function_tool). The copy recordson_invoke_tool.
from agents import Agent, function_tool
@function_tool
def lookup_order(order_id: str) -> str: ...
agent = Agent(name="support", tools=signafaide.wrap_tools([lookup_order]))
Neither framework is a dependency: wrap_tools recognises the objects by their shape.
Strict mode: no receipt, no action
@signafaide.record(strict=True)
def wire_funds(account: str, amount: float): ...
The decision is shipped first, and the function runs only after the service has returned its receipt. If the service can't be reached or refuses the record, or there is no API key (no_key), signafaide.NotRecorded is raised and the function does not run. Agent frameworks often turn a tool's error into a failed tool call and print nothing, so the first time a strict tool is refused in a process the SDK writes one warning line to stderr with the tool's name and the fix.
Hash-only
By default the service receives only the envelope: the name, the time, the chain links and content_hash. The hash is sha256(salt || JCS(content)) with a random 16-byte salt per record, kept next to the content in the local chain, so the service cannot confirm a guess of the content from the hash. When you store content with the service, the salt goes with it, so anyone holding the pack can check the content against the hash. Your inputs and outputs stay in .signafaide/chain/<project>/<env>/<agent>.jsonl (.signafaide/chain/_pending/nokey/<agent>.jsonl before the opt-in), which is your evidence store. To send the content too (encrypted at rest; live records need the Team plan):
signafaide.init(store_content=True) # everything
@signafaide.record(store_content=True) # one tool
Offline
Nothing waits on the network unless you use strict mode: writing a record never makes a request, and a wrong key or an unreachable witness is a warning, never an exception in your tool. A malformed SIGNAFAIDE_API_KEY is caught here and never sent. With an API key, records go to .signafaide/outbox/ and are shipped in batches by a background thread: every 2 seconds, every 100 records, and once more on exit (at most 3 seconds). If the service can't be reached, they stay on disk and are retried with backoff; a refusal retrying cannot fix (quota used up, a revoked key) stops sending until the configuration changes. They ship on the next run or with signafaide flush. Records are never lost on exit. The delay shows as the gap between a record's time and its batch's server_time.
Containers that restart
A container with no persistent disk continues its chain after the witness's head, and its first record is a signed start note. So that a routine restart is not read as a possible loss, end the instance with signafaide.stop(): it ships what is left and then writes a signed stop note. A start right after a stop note is a clean restart; a start with no stop note before it (a crash, a kill, an unreachable witness) is shown as a warning, because records the earlier instance had not sent are not known.
import signal, sys, signafaide
def on_term(signum, frame):
signafaide.stop() # {shipped, left, errors, stopped}
sys.exit(0)
signal.signal(signal.SIGTERM, on_term)
A program that ends by itself with SIGNAFAIDE_HEAD_FILE set writes the stop note at exit, within the exit limit above. SIGNAFAIDE_INSTANCE_STOP=0 turns that off; =1 turns it on without a head file.
Errors
Service errors raise or log signafaide.SignafaideError. Its message is the service's one-sentence fix, word for word, and .code is the error code. A chain_conflict (the service's chain for an agent differs from yours) is reported with the service's head and blocks shipping for that agent. The local chain is never rewritten. Run signafaide verify and signafaide status to see why.
Verify
signafaide verify # the local .signafaide state
signafaide verify pack.json # a pack from `signafaide export`
signafaide verify pack.json --keys keys.json --json
There is one line per check (schema, hashes, signatures, chains, Merkle proofs, batch and head signatures, drand, anchors, OpenTimestamps, content), then the result line: PASS or FAIL and how many checks passed, are pending and were not checked, for example PASS: 11 of 12 checks passed, 1 pending (public timestamp). Pending means co-signed, waiting for the public timestamp (an anchor is made every hour and usually confirms within a few hours); pending and not checked are never counted as passed. The exit code is 0 for PASS, 1 for FAIL and 2 when an input can't be read. Locally, a chain the witness refuses for good (or that an older SDK wrote with time going back) shows as BLOCKED with the reason and the next step, and always exits 1; --fail-on-pending-send also fails while records wait to be co-signed, for CI. Locally, before anything was co-signed, the witness's checks show NOT CHECKED ("nothing co-signed yet") and no request is made. Service keys come from --keys <file|url>, or by default from the service's /.well-known/signafaide-keys.json. --trust-embedded-keys uses the keys inside the pack and prints a warning. The drand BLS signature is checked too, through py_ecc (a dependency, as @noble/curves is for the TypeScript SDK), so both SDKs count the same checks. A pack's rounds are checked together, so it takes well under a second.
report = signafaide.verify("pack.json", keys="keys.json")
print(report) # the same lines
report.ok # True / False
For an auditor the agent keys must come from you, not from the pack (otherwise a service could add a key of its own): signafaide keys export -o agent-keys.json writes every agent key, each signed by itself. The auditor runs npx signafaide verify pack.json --keys <witness>/.well-known/signafaide-keys.json --agent-keys agent-keys.json --head head.json (or the Python CLI with the same arguments; head.json is your .signafaide/head.json, which catches records cut off at the end). Without --agent-keys the client-signature check says NOT INDEPENDENT and the result is FAIL; --trust-embedded-agent-keys accepts the pack's keys and says so in the result line. On your own machine, signafaide verify pack.json uses this project's agent keys automatically. Public timestamps are checked online (--timestamp-check <url>, default https://mempool.space/api); with --offline they show NOT CHECKED, never confirmed. signafaide keys rotate --agent X gives an agent a new key; the SDK signs the registration of the new key with the old one.
Replay
signafaide replay --agent claims-bot --from 2026-11-01 --to 2026-11-13 --html replay.html
signafaide replay --agent claims-bot --record 3fa2b1c9
Shows the agent's decisions and outcomes in order, with their inputs and outputs from the local chain. Each record is checked against its content_hash, its signature and the service's receipt first, so an edited line shows as FAIL. --html also writes a self-contained page. In code: r = signafaide.replay(agent="claims-bot", since="2026-11-01"), then print(r), r.to_html(), r.ok.
Experiments: A/B on past decisions
def approve(claim_id, amount): # same arguments as the recorded tool
return {"approved": amount < 300}
report = signafaide.compare(approve, agent="claims-bot", name="approve_payout", since="2026-11-01", limit=500)
print(report) # n, agreed, changed, errors, then the changed decisions
report.upload() # optional: hash-only unless content is stored with the service
The chain is verified first; then each recorded decision with a co-signed outcome is re-run with your candidate, on your machine, with your own models and keys, and compared with the recorded output (exact canonical-JSON equality, or same=lambda recorded, candidate: ...). A candidate that raises counts as an error. Candidates must be side-effect free: compare never writes records, and a recorded tool called from a candidate raises instead of running. CLI: signafaide compare --module candidate.py:approve --name approve_payout --upload.
CLI
| command | does |
|---|---|
signafaide init |
the opt-in: creates a free sandbox if there is no key (no account, email or card), prints the claim link |
signafaide status |
key and env, agents, last receipt, outbox size, quota; BLOCKED chains (exit 1) |
signafaide repair [--agent X] [--dry-run] |
sets aside records no witness can take (kept in .signafaide/held/, still verified), gives the agent a new key and starts a new segment |
signafaide verify [pack.json] [--keys ...] [--agent-keys ...] [--head ...] [--offline] [--fail-on-pending-send] [--json] |
verifies; exit 0 PASS, 1 FAIL or BLOCKED, 2 unreadable input |
signafaide keys export [-o agent-keys.json] / signafaide keys rotate [--agent X] [--env test|live] |
the agent-key file for auditors / a new key for an agent |
signafaide keys create [--agent X] [--env test|live] [--print] |
a new key, registered with the witness, for a secret store; writes no record (--print: prints the key file and saves nothing here) |
signafaide export [--agent X] [--from T] [--to T] [-o pack.json] |
downloads a verification pack of the whole project (every agent); --agent narrows it to one |
signafaide replay [--agent X] [--from T] [--to T] [--record H] [--html out.html] [--json] |
the verified timeline from the local chain; exit 1 on FAIL |
signafaide compare --module file.py:fn [--agent X] [--name N] [--from T] [--to T] [--limit N] [--upload [--values]] |
re-runs recorded decisions with a candidate and compares; --values sends the values too (stored-content decisions only) |
signafaide claim |
prints the claim link again |
signafaide flush |
ships the outbox now (with no key it sends nothing and says so) |
What is sent besides records
Every request carries one header:
X-Signafaide-Client: signafaide-python/0.2.1 (python 3.12.3; adapter=none; agent=claude-code; via=sdk)
It holds the SDK and its version, the Python runtime and its version, and the framework adapter in use (langchain, openai-agents or none). It also holds the coding agent that set the project up (claude-code, codex, cursor, gemini-cli, copilot, windsurf or unknown) and how the call was made (sdk, cli or mcp). The agent is found from that tool's environment variables when the project is set up (signafaide init) and kept in .signafaide/config.json; it is never guessed per process. signafaide verify and signafaide export also send POST /v1/events {"name": "verify"} (or "export") when there is an API key. If that fails, the command is not affected. With no API key nothing at all is sent.
The header and the events hold no content, file paths, hostnames or user names. SIGNAFAIDE_TELEMETRY=0 removes the adapter, the coding agent and the strict-mode flag from the header, stops the coding agent being saved in .signafaide/config.json, and turns the events off. The SDK and its version, the runtime and its version, and how the call was made (via) are still sent.
Configuration
| variable | default |
|---|---|
SIGNAFAIDE_API_KEY |
read from the environment, then .env; created by signafaide init; none: local only |
SIGNAFAIDE_URL |
https://api.signafaide.co.uk; a self-hosted witness, or http://127.0.0.1:7474 for a local dev server. Alone it sends nothing |
SIGNAFAIDE_HOME |
.signafaide/ in the project root; a mounted volume or /tmp/signafaide in production |
SIGNAFAIDE_AGENT_KEY_<NAME> |
an agent's key file content from a secret store (or key_provider= in signafaide.init); live keys can use SIGNAFAIDE_AGENT_KEY_LIVE_<NAME>, made with signafaide keys create --env live --print |
SIGNAFAIDE_HEAD_FILE |
unset: a file outside .signafaide/ (a persistent volume) that also keeps the newest signed heads, for containers whose disk does not last; or on_head= in signafaide.init |
SIGNAFAIDE_INSTANCE_STOP |
unset: a signed stop note is written at a clean exit when a head file is set; 1 always, 0 never (see Containers that restart) |
SIGNAFAIDE_EXIT_FLUSH_MS |
3000: the longest a finished program is kept open to send; 0 never |
SIGNAFAIDE_TEST |
test mode is on by itself under pytest (records in a temporary folder, nothing sent); 1 forces it, 0 turns it off |
SIGNAFAIDE_DISABLED |
1: wrapped functions run and nothing is recorded |
SIGNAFAIDE_SEGMENT_BYTES |
67108864: a shipped chain file larger than this rolls into a sealed segment |
SIGNAFAIDE_TELEMETRY |
0 turns off the adapter, agent and strict fields and the events |
Running in containers, with replicas, on read-only or ephemeral disks, on serverless or in CI: see the production guide. A record's time never goes back along its chain: if the clock steps back, the record keeps the previous record's time and the clock's reading goes in meta.wall_time.
Each project and env has its own chain per agent. A new key, for example a live key replacing the sandbox key, starts a fresh chain at seq 1. The old chain stays on disk, and signafaide status lists every chain.
The project root is the nearest folder with .signafaide/, .git, pyproject.toml or package.json. signafaide init adds .signafaide/ to .gitignore (never a running program). Agent keys live in .signafaide/agents/<agent>.key (sandbox) and .signafaide/agents/live/<agent>.key (live), mode 0600, and never leave the machine. Back them up.
Python 3.9+. Dependencies: cryptography and py_ecc (drand BLS).
Metadata
Release files for signafaide 0.2.1
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 |
|---|---|---|---|---|
| signafaide-0.2.1.tar.gz | 395.8 kB | Without provenance | Details for signafaide-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| signafaide-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for signafaide-0.2.1-py3-none-any.whl |
Total release size: 500.1 kB
Release files / signafaide-0.2.1.tar.gz
| Download URL | signafaide-0.2.1.tar.gz |
|---|---|
| Size | 395.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
060c07163ab78691dd87b490b162110b23913cf90c9f96261933ee56296c743a
|
|
BLAKE2b-256 checksum How to use checksums |
aace650a6be53e521a3ab6a58772c9316e40b7b0c4008604d88990c00f91e3eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.11 {"installer":{"name":"uv","version":"0.10.11","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / signafaide-0.2.1-py3-none-any.whl
| Download URL | signafaide-0.2.1-py3-none-any.whl |
|---|---|
| Size | 104.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e7a6ca796cbb3dfdce94b1715de23aed64e21ba08ad1ce0195643e9e3862ae17
|
|
BLAKE2b-256 checksum How to use checksums |
680fb17eaabf3f3568f8b2a94ba74b8c66709ad71bfa94fd718f8e647c40ab20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.11 {"installer":{"name":"uv","version":"0.10.11","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for signafaide 0.2.1
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.