Metadata-Version: 2.5
Name: assisters
Version: 0.1.0
Summary: Official Python SDK for the Assisters AI API
Project-URL: Homepage, https://assisters.dev
Project-URL: Documentation, https://docs.assisters.dev
Project-URL: Issues, https://www.assisters.dev/contact
License: MIT
Keywords: ai,api,assisters,openai,sdk
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# Assisters Python SDK

Official Python SDK for the [Assisters](https://assisters.dev) AI API.

## Install

> **Not published yet.** `pip install assisters` fails — this package is not on
> PyPI. Until it ships, use the OpenAI SDK against our base URL, which the API
> is compatible with:
>
> ```bash
> pip install openai
> ```
> ```python
> from openai import OpenAI
> client = OpenAI(api_key=os.environ["ASSISTERS_API_KEY"],
>                 base_url="https://api.assisters.dev/v1")
> ```
>
> The rest of this README describes this package's own interface, for when it
> is released. See [the SDK docs](https://docs.assisters.dev/docs/sdks/overview).

```bash
pip install assisters
```

Requires Python 3.9+. Depends on [`httpx`](https://www.python-httpx.org/).

## Quickstart

```python
from assisters import Assisters

client = Assisters(api_key="sk-...")  # base_url defaults to https://api.assisters.dev/v1

resp = client.chat.completions.create(
    model="assisters-chat-v1",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp["choices"][0]["message"]["content"])
```

Authentication uses `Authorization: Bearer <api_key>`.

## API

```python
# Chat (non-streaming)
client.chat.completions.create(model="assisters-chat-v1", messages=[...])

# Chat (streaming)
for chunk in client.chat.completions.create(
    model="assisters-chat-v1", messages=[...], stream=True
):
    print(chunk["choices"][0]["delta"].get("content", ""), end="")

# Embeddings
client.embeddings.create(model="assisters-embed-v1", input=["hello", "world"])

# Moderation
client.moderations.create(input="some text")

# Rerank
client.rerank(model="assisters-rerank-v1", query="q", documents=["a", "b"])

# Models
client.models.list()

# Image generation
client.images.generations.create(
    model="assisters-image-v1", prompt="a green robot", size="1024x1024"
)

# Audio transcription
with open("audio.webm", "rb") as f:
    client.audio.transcriptions.create(file=f, model="assisters-stt-v1")

# Text-to-speech -> raw audio bytes
audio = client.audio.speech.create(
    model="assisters-tts-v1", input="Hello there", voice="nova", response_format="mp3"
)

# Audio enhancement -> enhanced audio bytes
with open("noisy.wav", "rb") as f:
    enhanced = client.audio.enhance(file=f, model="assisters-voice-enhance")

# Translation
client.translate(text="Hello", target_language="Spanish")

# Agent (Max tier) — synchronous run
client.agent.run(query="Research the latest on X", mode="research")

# Agent — streaming events (SSE)
for event in client.agent.stream(query="Research X", mode="research"):
    print(event)

# Rate limit
client.get_rate_limit()

# One model, with its pricing and limits
client.models.retrieve("assisters-chat-v1")
```

> **Removed:** `client.keys.*` and `client.webhooks.*` were here. Both call
> `/api/keys` and `/api/webhooks`, which authenticate with a signed-in browser
> session rather than a Bearer key — so every call returned 401 for a client
> built with an API key, as this one is. Manage keys and webhooks in the
> [dashboard](https://www.assisters.dev/dashboard/api-keys).

## Errors

Every failure raises `AssistersAPIError` (`.status`, `.message`, `.type`), or one
of its subclasses so you can branch on the cause:

```python
from assisters import Assisters, AssistersAPIError, AuthError, NotFoundError, RateLimitError

try:
    client.chat.completions.create(model="assisters-chat-v1", messages=[...])
except RateLimitError as e:
    ...          # 429 — rate limited, or the wallet is empty
except AuthError as e:
    ...          # 401/403 — key missing, invalid or revoked
except NotFoundError as e:
    ...          # 404 — no such model
except AssistersAPIError as e:
    print(e.status, e.type, e.message)
```

Transport failures raise `AssistersAPIError` with `status=0` and
`type="network_error"`.
