tezca
Zero-dependency, hash-chained forensic ledger for AI agents.
Named after Tezcatlipoca (the "Smoking Mirror") -- the obsidian mirror that reflects and records everything hidden.
tezca is a lightweight, pure-Python library that creates cryptographically sealed, tamper-evident receipts for every prompt, tool call, and guardrail verdict your AI agents execute.
Why tezca?
When an AI agent issues a refund, modifies a database, or summarizes a medical record, standard application logs are not enough. Logs can be altered, observability SaaS platforms add latency and vendor lock-in, and compliance auditors (SOC2, HIPAA, ISO 42001, EU AI Act) demand verifiable proof of what happened and why.
tezca provides verifiable integrity with classical cryptography and zero bloat:
- Zero Dependencies: Built 100% on the Python standard library (
hashlib,json,sqlite3). No PyTorch, no heavy SDKs, no supply-chain bloat. - Tamper-Evident Hash Chaining: Every event is canonicalized and sealed with SHA-256, mathematically linked to the preceding record hash. Altering a single byte invalidates the chain.
- Sub-Millisecond Overhead: Executes locally in
< 1msper event, making it suitable for serverless, edge, and high-throughput agent workflows. - Built-in Forensic CLI: Verify audit trail integrity instantly using
tezca verify. - Framework Agnostic: Compatible with any LLM provider (OpenAI, Anthropic, Gemini, Ollama) and agent framework (LangGraph, CrewAI, AutoGen, or custom Python code).
Installation
pip install tezca
Quickstart
Recording Agent Events
from tezca import Ledger
# Initialize ledger (uses SQLite with WAL mode by default)
ledger = Ledger("audit.db")
# Record an agent decision or tool invocation
receipt = ledger.record(
agent_id="finance-agent-01",
event_type="tool_call",
data={
"action": "issue_refund",
"order_id": "ord_9876",
"amount_usd": 149.99,
"recipient": "user@example.com"
},
metadata={
"session_id": "sess_4f89a",
"model": "gpt-4o"
}
)
print(f"Recorded index: {receipt.index}")
print(f"Receipt hash: {receipt.hash}")
print(f"Previous hash: {receipt.prev_hash}")
Verifying Chain Integrity Programmatically
from tezca import Ledger
ledger = Ledger("audit.db")
is_valid, report = ledger.verify()
if is_valid:
print(f"Ledger intact: {report['verified_events']} events verified.")
else:
print(f"TAMPER DETECTED at index {report['failed_at_index']}: {report['error']}")
Forensic CLI
tezca includes a built-in CLI for audits and CI/CD pipelines:
Verify a Ledger
tezca verify audit.db
Output:
[OK] 1,420 events verified.
[OK] Chain integrity: INTACT (Genesis: 00000000... -> Latest: e4b219af...)
If any byte in the database or JSON payload has been altered:
[FAIL] Tampering detected at record #42
Expected prev_hash: 8f3c1a...
Computed hash: d1490e...
Chain broken.
Inspect the Latest Events
tezca tail audit.db -n 5
Export Receipts to JSON Lines
tezca export audit.db --output audit.jsonl
Export Standalone Cryptographic Proof (.tezcaproof)
Export a portable proof bundle for a specific event (e.g. event #42) that compliance auditors can verify offline:
tezca proof audit.db 42 -o event_42.tezcaproof
Verify an Offline Proof Bundle
Verify proof bundles without access to the original SQLite database:
tezca verify-proof event_42.tezcaproof
Output:
[OK] Proof verified: Receipt #42 is cryptographically sealed.
[OK] Merkle Root: 0bc8e92e178936f47081d43e...
[OK] Event Hash: b51f283543dc5a13373e...
Merkle Trees & Cryptographic Non-Repudiation
tezca supports binary Merkle trees for $O(\log N)$ batch verification and HMAC-SHA256 signature sealing:
from tezca import Ledger, ProofBundle
# Initialize with an optional secret key for HMAC non-repudiation
ledger = Ledger("audit.db", secret_key="secure-hmac-key", signer_id="agent-01")
# Record signed events
receipt = ledger.record("agent-01", "tool_call", {"action": "wire_transfer", "amount": 5000})
assert receipt.signature is not None
# Query Merkle root over all recorded receipts
print("Merkle Root:", ledger.merkle_root())
# Export a portable, self-contained proof bundle
bundle = ledger.export_proof(receipt.index, output_path="transfer.tezcaproof")
# Verify offline anywhere
loaded = ProofBundle.load("transfer.tezcaproof")
valid, report = loaded.verify(secret_key="secure-hmac-key")
assert valid
Agent Framework Integrations
tezca provides zero-dependency adapters and decorators for major agent frameworks:
Decorating Tools and Functions
Automatically capture inputs, latency, outputs, and errors:
from tezca import Ledger, wrap_tool
ledger = Ledger("audit.db")
@wrap_tool(ledger, agent_id="support-bot", tool_name="fetch_user_profile")
def fetch_profile(user_id: str):
return {"id": user_id, "tier": "enterprise"}
# Every invocation is sealed with its execution duration into the ledger
profile = fetch_profile("usr_123")
Wrapping LLM Completions (OpenAI / Anthropic)
from tezca import Ledger, wrap_completion
@wrap_completion(ledger, agent_id="support-bot", model="gpt-4o")
def call_llm(prompt: str):
return client.chat.completions.create(...)
LangChain & LangGraph Callback Handler
from tezca import Ledger, TezcaCallbackHandler
handler = TezcaCallbackHandler(ledger, agent_id="langchain-agent", session_id="sess_102")
# Pass handler into any LangChain or LangGraph runnable
agent.invoke({"input": "Hello"}, config={"callbacks": [handler]})
How It Works
- Deterministic Canonicalization: Every event payload is canonicalized using deterministic JSON serialization (lexicographically sorted keys, standard separators, UTF-8 normalization) before hashing.
- SHA-256 Chaining: Each record hashes
index + timestamp + agent_id + event_type + canonical_data + canonical_metadata + prev_hash. - Genesis Anchor: The first event links to a known 64-zero genesis hash (
0000...0000), establishing an unbroken lineage. - Resilient Local Storage: Default SQLite storage operates with Write-Ahead Logging (
PRAGMA journal_mode=WAL) andPRAGMA synchronous=NORMALfor maximum performance and multi-process concurrency.
Examples
Runnable scripts are provided in the examples/ directory:
examples/basic_usage.py: Basic ledger initialization, recording prompt/tool/response events, and verification.examples/guardrails_and_tools.py: Demonstrates compliance logging, safety guardrail verdicts, and blocked actions.examples/tamper_demonstration.py: Simulates out-of-band tampering in SQLite and demonstrates automatic tamper detection.examples/merkle_and_proofs.py: Demonstrates binary Merkle roots, HMAC-signed receipts, and standalone.tezcaproofexport/verification.examples/agent_integrations.py: Demonstrates@wrap_tool,@wrap_completion,TezcaCallbackHandler, andAgentEvent.
To run an example:
python examples/basic_usage.py
License
Apache License 2.0. See LICENSE for details.
Metadata
Release files for tezca 0.3.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 |
|---|---|---|---|---|
| tezca-0.3.0.tar.gz | 32.7 kB | With provenance | Details for tezca-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tezca-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for tezca-0.3.0-py3-none-any.whl |
Total release size: 58.5 kB
Release files / tezca-0.3.0.tar.gz
| Download URL | tezca-0.3.0.tar.gz |
|---|---|
| Size | 32.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a405c7f60c41ddb364c31452c2c8b50938141e04da767f829cd914bbeda3058
|
|
BLAKE2b-256 checksum How to use checksums |
5975c4e4c7e533f5bb2857bd6429a552628f3a8aced97caff310b44f36950dab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / tezca-0.3.0-py3-none-any.whl
| Download URL | tezca-0.3.0-py3-none-any.whl |
|---|---|
| Size | 25.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a471ae5b6dfa0cead131ecf99becd0b9bfc188d55a053b455178362de56c9203
|
|
BLAKE2b-256 checksum How to use checksums |
04f81d6367e1bb009922b0c9dfeb9d25f81bbc2c00b96436d7ec4e3c127ec9c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for tezca 0.3.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tezca-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA 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.