Skip to main content

tezca

Zero-dependency, hash-chained forensic ledger for AI agents.

PyPI version Python License Dependencies

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 < 1ms per 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

  1. Deterministic Canonicalization: Every event payload is canonicalized using deterministic JSON serialization (lexicographically sorted keys, standard separators, UTF-8 normalization) before hashing.
  2. SHA-256 Chaining: Each record hashes index + timestamp + agent_id + event_type + canonical_data + canonical_metadata + prev_hash.
  3. Genesis Anchor: The first event links to a known 64-zero genesis hash (0000...0000), establishing an unbroken lineage.
  4. Resilient Local Storage: Default SQLite storage operates with Write-Ahead Logging (PRAGMA journal_mode=WAL) and PRAGMA synchronous=NORMAL for 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 .tezcaproof export/verification.
  • examples/agent_integrations.py: Demonstrates @wrap_tool, @wrap_completion, TezcaCallbackHandler, and AgentEvent.

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)

Source distribution for tezca 0.3.0
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)

Table of built distributions (wheels) for tezca 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page