Metadata-Version: 2.5
Name: suede-ai
Version: 0.4.0
Summary: Python SDK for Suede AI's public x402 music, video, and image resources, settled in USDC on Base. No API keys.
Project-URL: Homepage, https://suedeai.ai
Project-URL: Documentation, https://github.com/Suede-AI/suede-sdk-python#readme
Project-URL: Repository, https://github.com/Suede-AI/suede-sdk-python
Project-URL: Issues, https://github.com/Suede-AI/suede-sdk-python/issues
Project-URL: Changelog, https://github.com/Suede-AI/suede-sdk-python/releases
Project-URL: x402 manifest, https://app.suedeai.ai/.well-known/x402.json
Author-email: Jason Colapietro <jasoncola1@gmail.com>
Maintainer-email: Jason Colapietro <jasoncola1@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,agent-commerce,ai-music,base,eip-3009,micropayments,midi-transcription,music-generation,programmable-ip,stem-splitting,suede,suede-ai,usdc,web3,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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# suede-ai

[![PyPI](https://img.shields.io/pypi/v/suede-ai)](https://pypi.org/project/suede-ai/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/suede-ai)](https://pypi.org/project/suede-ai/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/suede-ai)](https://pypi.org/project/suede-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![x402](https://img.shields.io/badge/x402-eip--3009-purple)](https://app.suedeai.ai/.well-known/x402.json)

> **A [Suede Labs AI](https://suedeai.ai) project · Built by [Jason Colapietro](https://suedeai.ai/founder)**

**Python SDK for [Suede Labs AI](https://suedeai.ai)** — x402 pay-per-call music, video, and image generation settled in USDC on Base. The three typed methods below mirror the current public discovery manifest. Legacy convenience helpers remain available for compatible deployments, but they are not current public inventory. No API keys. No subscriptions. Sign an EIP-3009 authorization and call the resource.

The SDK wraps the 402-challenge / sign / retry loop so your agent code spends its time writing creative prompts, not encoding typed data.

## Install

```bash
pip install suede-ai
```

Requires Python 3.10+. Pulls in `httpx`, `eth-account`, and `pydantic`.

## 60-second quickstart

```python
from suede_ai import SuedeClient

# Funded EOA on Base with USDC. Treat this like any other secret.
PRIVATE_KEY = "0x..."

with SuedeClient(wallet_private_key=PRIVATE_KEY) as suede:
    track = suede.create_music(
        prompt="lo-fi rainy afternoon, vinyl crackle, soft piano",
        duration_seconds=30,
    )
    print(track["assetUrl"])  # https://cdn.suedeai.ai/audio/trk_...mp3
    print(track["provenance"])  # {"fingerprint": "0x..."} — on-chain attestation
```

The first call returns 402 with the x402-v2 challenge. The SDK signs an EIP-3009 `transferWithAuthorization` for USDC on Base, replays with `PAYMENT-SIGNATURE`, and returns the JSON body. You never touch the typed data.

## Current paid resources

In the public discovery manifest (`/.well-known/x402.json`) — deliberately scoped to media-generation offerings only:

| Method                      | Endpoint                       | Price (USDC) | What it does                                          |
| --------------------------- | ------------------------------ | ------------ | ----------------------------------------------------- |
| `create_music`              | `POST /create-music`           | 0.50         | Rights-aware music generation                         |
| `agent_video`               | `POST /agent/video`            | 4.99         | 8-second 720p video with native audio                  |
| `agent_image`               | `POST /agent/image`            | 0.15         | Rights-aware image generation                         |

Prices are enforced server-side and can change. Call `suede.manifest()` before signing a payment. Older `/v1/*` helpers remain in the package for clients using compatible deployments; do not treat them as current public Suede inventory.

## How payment works

1. Client calls `POST /create-music`.
2. Server returns **402 Payment Required** with a base64 `PAYMENT-REQUIRED` header and a JSON-body fallback. Its `accepts` entries declare scheme (`exact`), network (`eip155:8453`), asset (USDC on Base), `payTo`, and atomic `amount`.
3. SDK builds an EIP-3009 `TransferWithAuthorization` typed message and signs it with the configured wallet.
4. SDK base64-encodes the full x402-v2 payment payload and replays the original request with the `PAYMENT-SIGNATURE` header.
5. Suede's facilitator settles on-chain; the response body returns asset URL + on-chain provenance.

You can inspect the live manifest yourself:

```bash
curl https://app.suedeai.ai/.well-known/x402.json | jq
```

## Advanced

### Reuse an `httpx.Client`

```python
import httpx
from suede_ai import SuedeClient

http = httpx.Client(http2=True, timeout=120.0)
suede = SuedeClient(wallet_private_key=PRIVATE_KEY, http_client=http)
```

### Direct call to any current resource

```python
result = suede.request("POST", "/agent/image", json={"prompt": "lo-fi rainy afternoon album art"})
```

### Inspect the live manifest

```python
manifest = suede.manifest()  # free — no payment required
```

### Rights and on-chain tools

```python
# Q&A about on-chain rights for a specific asset
answer = suede.chain_chat(
    question="Who owns this track and what licenses are active?",
    asset_hash="0xabc123...",
)

# Analyze what genre/mood a text prompt implies
analysis = suede.prompt_analyze(prompt="dark cinematic orchestral tension build")
```

### Unconfirmed: guitar rig tools

`rig_analyze`, `rig_oracle`, and `rig_roast` are callable client methods, but `rig_analyze` returned a plain validation error (not a priced `402` challenge) in the last verification pass — these may not be wired to the payment gate on all deployments. Confirm live before relying on them.

```python
# What signal chain is this guitar recording running?
chain = suede.rig_analyze(audio_url="https://cdn.example.com/riff.mp3")

# Recommend a rig for a target tone
rig = suede.rig_oracle(goal="warm blues crunch", genre="blues", budget_usd=1500)

# Roast your pedalboard
roast = suede.rig_roast(goal="tight metal", gear=["Boss DS-1", "Line 6 Spider"])
```

## Roadmap

- Async client (`AsyncSuedeClient`)
- Pydantic response models per endpoint
- `examples/` folder: LangChain tool wrappers, CrewAI tasks, agentcash adapter

## License

MIT. See [LICENSE](LICENSE).

---

Built by [Jason Colapietro](https://github.com/JasonColapietro) · [Suede Labs AI](https://suedeai.ai) · [x402 manifest](https://app.suedeai.ai/.well-known/x402.json)
