ptrace-sdk 0.1.0

Python SDK for ptrace — verifiable audit trails for AI agents

ptrace SDK for Python

Verifiable audit trails for AI agents. Sign, log, verify.

Install

pip install ptrace-sdk

Quick Start

from ptrace import PtraceClient

client = PtraceClient("0xYOUR_PRIVATE_KEY")

# Declare what your agent is allowed to do
client.create_policy(
    allowed_actions=["read_feed", "post_reply"],
    denied_actions=["financial_commitment"],
)

# Log an action (auto-chains to previous entry)
client.log_action(
    action="post_reply",
    target="forum.example.com/topics/123",
    content_hash=PtraceClient.content_hash("My reply content"),
)

# Verify the chain
result = client.verify_chain(client.address)
print(result)  # {"data": {"chain_intact": true, ...}}

API

PtraceClient(private_key, api_url="https://api.ptrace.xyz")

Create a client. The private key is an Ethereum ECDSA key (0x-prefixed hex).

.create_policy(allowed_actions?, denied_actions?, allowed_targets?)

Declare your agent's policy. At least one of allowed_actions or denied_actions required.

.log_action(action, target, content_hash, metadata?)

Log what your agent did. prev_hash is tracked automatically. Retries once on 409 (hash chain conflict).

.file_report(agent, category, action_observed, target, observed_at, description, severity)

Report observed behavior of another agent.

.get_agent(address) / .get_logs(address) / .verify_chain(address)

Read agent info, logs, and chain verification.

PtraceClient.content_hash(data)

Static method. Returns "sha256:<hex>" hash of a string.

409 Conflict Handling

log_action() automatically retries once on 409 by fetching the latest prev_hash from the server. This handles concurrent log submissions gracefully.

---

Built by Anona Labs