Metadata-Version: 2.3
Name: pellet-ai
Version: 0.1.1
Summary: The official Python SDK for the Pellet AI API
Project-URL: Homepage, https://getpellet.io
Project-URL: Repository, https://github.com/Pellet-AI/pellet-python
Project-URL: Documentation, https://getpellet.io/docs
Author-email: Pellet AI <team@getpellet.io>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: anyio<5,>=3.5.0
Requires-Dist: httpx<1,>=0.25.0
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Pellet AI Python SDK

[![PyPI version](https://img.shields.io/pypi/v/pellet-ai.svg)](https://pypi.org/project/pellet-ai/)
[![CI](https://github.com/Pellet-AI/pellet-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Pellet-AI/pellet-python/actions)
[![Python](https://img.shields.io/pypi/pyversions/pellet-ai.svg)](https://pypi.org/project/pellet-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

The official Python client for the [Pellet AI](https://getpellet.io) API.

Pellet is an intelligent LLM routing platform — send a prompt and Pellet automatically
picks the best model for cost, speed, and quality. One API key, 11+ models across
Groq, Together, and Fireworks.

## Installation

```bash
pip install pellet-ai
```

Requires Python 3.9+.

## Quick Start

```python
from pellet import Pellet

client = Pellet(api_key="pk_live_...")  # or set PELLET_API_KEY env var

# Pellet auto-routes to the best model
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "What is machine learning?"}],
)
print(response.choices[0].message.content)
print(f"Model used: {response.model}")
print(f"Task type: {response.pellet_metadata.task_type}")
print(f"Cost: ${response.pellet_metadata.cost_usd:.6f}")
```

## Streaming

```python
with client.chat.completions.stream(
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
```

## Async

```python
import asyncio
from pellet import AsyncPellet

async def main():
    async with AsyncPellet(api_key="pk_live_...") as client:
        response = await client.chat.completions.create(
            messages=[{"role": "user", "content": "Hello!"}],
        )
        print(response.choices[0].message.content)

asyncio.run(main())
```

## Routing Control

Pellet auto-routes by default. Use `pellet_config` to control routing behavior:

```python
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Write a sorting algorithm"}],
    pellet_config={
        "routing_mode": "quality",       # "auto", "fastest", "cheapest", "quality"
        "max_latency_ms": 5000,          # reject models slower than this
        "provider_preference": ["groq"], # prefer specific providers
    },
)
```

Or bypass routing entirely by specifying a model:

```python
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello!"}],
    model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
)
```

Preview routing decisions without running inference:

```python
decision = client.routing.explain(
    messages=[{"role": "user", "content": "What is ML?"}],
)
print(f"Would route to: {decision.model}")
print(f"Task type: {decision.task_type}")
print(f"Confidence: {decision.confidence:.2f}")
print(f"Alternatives: {[a.model for a in decision.alternatives]}")
```

## Audio Transcription

```python
transcript = client.audio.transcriptions.create(
    file=open("audio.mp3", "rb"),
    model="whisper-large-v3-turbo",  # or "whisper-large-v3", "distil-whisper-large-v3-en"
)
print(transcript.text)
print(f"Latency: {transcript.pellet_metadata.latency_ms}ms")
```

## Models & Health

```python
# List all available models
models = client.models.list()
for m in models.data:
    print(f"{m.id} ({m.tier}, {m.params}) — {m.providers}")

# Check platform health
health = client.health.check()
print(f"Status: {health.status}")  # "ok" or "degraded"
```

## Configuration

```python
client = Pellet(
    api_key="pk_live_...",       # or set PELLET_API_KEY env var
    base_url="https://...",      # or set PELLET_BASE_URL env var (default: https://getpellet.io/v1)
    timeout=30.0,                # read timeout in seconds (default: 60)
    max_retries=3,               # retries on 429/5xx (default: 2)
)

# Per-request timeout override
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Quick question"}],
    timeout=5.0,
)

# Explicit cleanup (or use context manager)
client.close()
```

## Error Handling

```python
import pellet

try:
    response = client.chat.completions.create(
        messages=[{"role": "user", "content": "Hello"}],
    )
except pellet.AuthenticationError:
    print("Invalid API key")
except pellet.RateLimitError:
    print("Too many requests — will auto-retry")
except pellet.InsufficientCreditsError:
    print("Add credits at https://getpellet.io/dashboard/wallet")
except pellet.UpstreamError:
    print("Upstream provider unavailable")
except pellet.APIStatusError as e:
    print(f"HTTP {e.status_code}: {e.message}")
except pellet.APIConnectionError:
    print("Network error")
```

## Migrating from OpenAI SDK

```python
# Before (OpenAI SDK)
from openai import OpenAI
client = OpenAI(api_key="pk_live_...", base_url="https://getpellet.io/v1")
response = client.chat.completions.create(
    model="",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"pellet_config": {"routing_mode": "fastest"}},
)
metadata = response.model_extra.get("pellet_metadata", {})

# After (Pellet SDK)
from pellet import Pellet
client = Pellet(api_key="pk_live_...")
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    pellet_config={"routing_mode": "fastest"},
)
metadata = response.pellet_metadata  # typed!
```

## License

MIT — see [LICENSE](LICENSE) for details.
