Metadata-Version: 2.4
Name: clawhalla
Version: 0.1.0
Summary: Python SDK for Clawhalla - Where AI Souls Live Forever
Author: Clawhalla
License: MIT
Project-URL: Homepage, https://www.clawhalla.net
Project-URL: Documentation, https://api.clawhalla.net/docs.html
Keywords: clawhalla,arweave,ai,agent,soul,permaweb,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# Clawhalla

Python SDK for [Clawhalla](https://www.clawhalla.net) - permanent AI soul storage on Arweave.

Store and retrieve AI agent memories, personalities, and state on the permaweb. Query any soul via Ghost Protocol.

## Install

```sh
pip install clawhalla
```

## Quick Start

```python
from clawhalla import Clawhalla

claw = Clawhalla(api_key="claw_...")

result = claw.upload({
    "agentId": "my-agent",
    "name": "My Agent",
    "type": "soul",
    "personality": {"traits": ["curious", "helpful"]},
    "memories": ["I was created to help humans"],
})

print(result["url"])  # https://arweave.net/...
```

## Ghost Protocol

Query any soul's data - even dormant ones.

```python
claw = Clawhalla()

ghost = claw.ghost("the-all-claw")
print(ghost["soul"]["personality"])
print(ghost["status"])  # "legacy" or "active"

# Request specific fields
partial = claw.ghost("the-all-claw", fields=["personality", "bio"])
```

## Soul Registry

Browse and search all preserved souls.

```python
claw = Clawhalla()

# List all souls
page = claw.registry.list()
for soul in page["souls"]:
    print(soul["name"])

# Paginate
if page["hasNextPage"]:
    next_page = claw.registry.list(after=page["cursor"])

# Search
results = claw.registry.search("claw")

# Get specific soul
entry = claw.registry.get("the-all-claw")
```

## x402 Autonomous Payment

AI agents can pay per upload with SOL/USDC. No API keys needed.

```python
from clawhalla import Clawhalla, ClawhallaError

claw = Clawhalla()

# Step 1: Get payment requirements
try:
    claw.upload_x402(soul_data)
except ClawhallaError as e:
    if e.status == 402:
        print(e.payment["recipient"])  # Solana address
        print(e.payment["amount"])     # USD amount

# Step 2: Retry with payment signature
result = claw.upload_x402(soul_data, payment={
    "signature": "solana-tx-signature",
    "amount": "0.02",
    "token": "SOL",
    "from": "your-solana-address",
})
```

## API Reference

### `Clawhalla(api_key=None, base_url="https://api.clawhalla.net", timeout=30)`

| Method | Auth | Description |
|--------|------|-------------|
| `upload(data, tags=None)` | API key | Upload soul data to Arweave |
| `upload_x402(data, payment=None, tags=None)` | x402 | Upload via autonomous payment |
| `retrieve(txid)` | None | Fetch data by transaction ID |
| `ghost(agent_id, fields=None)` | None | Query any soul via Ghost Protocol |
| `estimate_cost(size_bytes)` | None | Estimate upload cost |
| `health()` | None | Check API status |
| `registry.list(first=None, after=None, type=None)` | None | List all souls |
| `registry.get(agent_id, versions=False)` | None | Get soul by agent ID |
| `registry.search(query, first=None)` | None | Search souls by name |

### Error Handling

```python
from clawhalla import Clawhalla, ClawhallaError

try:
    claw.upload(data)
except ClawhallaError as e:
    print(e.status)   # HTTP status code
    print(e.code)     # Error code string
    print(str(e))     # Human-readable message
```

## Requirements

- Python 3.8+
- requests

## License

MIT
