Metadata-Version: 2.4
Name: ptrace-sdk
Version: 0.1.1
Summary: Python SDK for ptrace — verifiable audit trails for AI agents
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.13
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ptrace SDK for Python

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

## Install

```bash
pip install ptrace-sdk
```

## Quick Start

```python
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](https://ptrace.xyz)
