Metadata-Version: 2.4
Name: suede-ai
Version: 0.1.0
Summary: Python SDK for the Suede AI x402 surface (17 pay-per-call endpoints, USDC on Base)
Project-URL: Homepage, https://github.com/Suede-AI/suede-sdk-python
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: x402 manifest, https://app.suedeai.ai/.well-known/x402.json
Author-email: Suede AI <hello@suedeai.ai>
License: MIT
License-File: LICENSE
Keywords: agent-commerce,ai,base,eip-3009,music,suede,suede-ai,usdc,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 :: 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/badge/pypi-coming%20soon-yellow)](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)

Python SDK for the [Suede AI](https://suedeai.ai) **x402** surface — 17 pay-per-call endpoints settled in USDC on Base. No API keys. No subscriptions. Just sign an EIP-3009 authorization and call the endpoint.

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

> **Status:** Alpha scaffold. Endpoint signatures track the live manifest at <https://app.suedeai.ai/.well-known/x402.json>. Once the OpenAPI spec covers all 17 endpoints, codegen will finish typing the request/response models.

## 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.xyz/audio/trk_...mp3
    print(track["provenance"])    # {"fingerprint": "0x..."} — on-chain attestation
```

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

## The 17 endpoints

| Method                      | Endpoint                       | Price (USDC) | What it does                                          |
| --------------------------- | ------------------------------ | ------------ | ----------------------------------------------------- |
| `create_music`              | `POST /create-music`           | 0.20         | Rights-aware music generation                         |
| `agent_generate`            | `POST /agent/generate`         | 0.20         | Agent-facing music output (same payload)              |
| `agent_video`               | `POST /agent/video`            | 1.50         | Short music-video clip generation                     |
| `extend`                    | `POST /v1/extend`              | 0.40         | Continue an existing Suede track                      |
| `cover`                     | `POST /v1/cover`               | 0.40         | Stylistic re-imagining of a track                     |
| `voice_cover`               | `POST /v1/vox`                 | 0.40         | Replace lead vocal with a Suede voice                 |
| `continue_track`            | `POST /v1/continue`            | 0.40         | Extend an uploaded audio file                         |
| `stems_pro`                 | `POST /v1/stems-pro`           | 0.40         | 4-stem split: vocals / drums / bass / other           |
| `stems_basic`               | `POST /v1/stems`               | 0.20         | 2-stem split: vocals + instrumental                   |
| `vox`                       | `POST /v1/acapella`            | 0.20         | Isolate the vocal stem                                |
| `midi`                      | `POST /v1/midi`                | 0.10         | Transcribe audio to MIDI                              |
| `wav_master`                | `POST /v1/mastering`           | 0.10         | High-quality WAV master                               |
| `lyric_sync`                | `POST /v1/lyric-sync`          | 0.10         | Timestamped lyrics for a track                        |
| `lyrics`                    | `POST /v1/lyrics`              | 0.04         | Generate fresh song lyrics from a prompt              |
| `style_coach`               | `POST /v1/style-coach`         | 0.02         | Expand short tags into a prompt-ready style brief     |
| `rights_lookup`             | `GET  /v1/rights/{assetHash}`  | 0.005        | Suede Registry attestation lookup (owner / IP / NFT)  |
| `analyze`                   | `POST /v1/analyze`             | 0.003        | BPM / key / mode / energy / danceability              |

Prices are sourced from the live manifest at the time of writing and are enforced server-side.

## How payment works

1. Client calls `POST /create-music`.
2. Server returns **402 Payment Required** with a JSON `accepts` array. Each entry declares scheme (`exact`), network (`eip155:8453`), asset (USDC on Base), `payTo` address, and `maxAmountRequired`.
3. SDK builds an EIP-3009 `TransferWithAuthorization` typed message and signs it with the configured wallet.
4. SDK base64-encodes the payment payload and replays the original request with the `X-PAYMENT` 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 endpoint

```python
result = suede.request("POST", "/v1/style-coach", json={"tags": "lofi, rainy"})
```

### Inspect the live manifest

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

## Roadmap

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

See the [0.1.0 release checklist](https://github.com/Suede-AI/suede-sdk-python/issues/1).

## License

MIT. See [LICENSE](LICENSE).
