Metadata-Version: 2.1
Name: clervo-sdk
Version: 0.1.0
Summary: Clervo x402 Gateway SDK
License: MIT
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# clervo

Python SDK for the [Clervo x402 Gateway](https://api.clervo.dev).

23 AI models. 8 free. Pay per call in USDC on Solana. No API keys.

## Install

```bash
pip install clervo
```

## Quick start

```python
from clervo import Clervo

client = Clervo()

# Free call — no wallet needed
text = client.chat("groq/llama-3.1-8b-instant", "Explain recursion in 2 sentences")
print(text)

# List models
models = client.models()
free = client.free_models()
print(f"{len(free)} free models available")
```

## Free models

No payment, no wallet, no signup:

| Model | Speed | Best for |
|-------|-------|----------|
| `groq/llama-3.1-8b-instant` | 170ms | Fast responses |
| `groq/llama-3.3-70b` | 800ms | Strong general |
| `sambanova/deepseek-v3.2` | 1.6s | Reasoning |
| `sambanova/llama-3.3-70b` | 1.5s | General |
| `hcn/qwen3.6-35b` | 0.9s | Fast small |
| `hcn/step-3.7-flash` | 3s | Reasoning |
| `hcn/deepseek-v4-pro` | 9s | Deep reasoning |
| `hcn/auto` | 3s | Auto-routed |

## Paid models (10-20% cheaper than BlockRun)

```python
from clervo import Clervo, PaymentRequired

client = Clervo()

try:
    text = client.chat("tongkhokr/claude-opus-5", "Review this code...")
except PaymentRequired:
    print("Fund a Solana wallet with USDC for paid models")
```

| Model | Price/req |
|-------|-----------|
| `tongkhokr/claude-haiku-4.5` | $0.002 |
| `tongkhokr/claude-sonnet-5` | $0.015 |
| `tongkhokr/claude-opus-5` | $0.084 |
| `quickai/gpt-5.4-mini` | $0.005 |
| `quickai/gpt-5.5` | $0.035 |

## API

### `Clervo(api_url=None, timeout=30.0)`

| Param | Default | Description |
|-------|---------|-------------|
| `api_url` | `https://api.clervo.dev` | API base URL |
| `timeout` | `30.0` | Request timeout seconds |

### `client.chat(model, message, *, system=None, max_tokens=1024)`

Simple chat. Returns the text response.

### `client.chat_completion(model, messages, *, max_tokens=1024, response_format=None)`

Full OpenAI-compatible chat completion. Returns the full response dict.

### `client.models()`

List all available models.

### `client.free_models()`

List only free models.

### `client.operation(operation_id)`

Look up an operation by ID.

## OpenAI drop-in

Since Clervo is OpenAI-compatible:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clervo.dev/v1",
    api_key="unused"  # no key needed for free models
)

response = client.chat.completions.create(
    model="groq/llama-3.1-8b-instant",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

## Links

- API: https://api.clervo.dev
- Models: https://api.clervo.dev/v1/models
- Quickstart: https://api.clervo.dev/quickstart.md
- TypeScript SDK: https://npmjs.com/package/@clervo/sdk
- MCP: https://npmjs.com/package/@clervo/mcp
