# SDKRouter

Unified Python SDK for AI services. Access 300+ LLM models, vision, audio, image generation, search, translation, and more through a single interface.

## Installation

```bash
pip install sdkrouter
```

## Quick Start

```python
from sdkrouter import SDKRouter, Model

client = SDKRouter(api_key="your-api-key")

response = client.chat.completions.create(
    model=Model.cheap(),
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

## Features

| Feature | Description | Docs |
|---------|-------------|------|
| **Chat** | OpenAI-compatible completions, streaming | [@docs/01-chat.md](@docs/01-chat.md) |
| **Structured Output** | Pydantic models, JSON extraction | [@docs/02-structured-output.md](@docs/02-structured-output.md) |
| **Audio** | TTS, STT, Deepgram streaming | [@docs/03-audio.md](@docs/03-audio.md) |
| **Vision** | Image analysis, OCR | [@docs/04-vision.md](@docs/04-vision.md) |
| **Image Gen** | AI image generation | [@docs/05-image-gen.md](@docs/05-image-gen.md) |
| **Search** | Web search with modes | [@docs/06-search.md](@docs/06-search.md) |
| **CDN** | File storage | [@docs/07-cdn.md](@docs/07-cdn.md) |
| **Translator** | JSON/text translation | [@docs/08-translator.md](@docs/08-translator.md) |
| **Payments** | Crypto payments | [@docs/09-payments.md](@docs/09-payments.md) |
| **Proxies** | Proxy management | [@docs/10-proxies.md](@docs/10-proxies.md) |
| **Embeddings** | Text embeddings | [@docs/11-embeddings.md](@docs/11-embeddings.md) |
| **Other** | Shortlinks, cleaner, models API | [@docs/12-other.md](@docs/12-other.md) |

## Model Routing

Smart model selection with IDE autocomplete:

```python
from sdkrouter import Model

Model.cheap()                    # Lowest cost
Model.smart()                    # Highest quality
Model.balanced()                 # Best value
Model.fast()                     # Fastest

# With capabilities
Model.cheap(vision=True)         # + vision
Model.smart(tools=True)          # + function calling
Model.balanced(json=True)        # + JSON mode

# Categories
Model.smart(code=True)           # Coding
Model.cheap(reasoning=True)      # Problem solving
```

## Async Support

```python
from sdkrouter import AsyncSDKRouter, Model
import asyncio

async def main():
    client = AsyncSDKRouter(api_key="your-api-key")

    response = await client.chat.completions.create(
        model=Model.cheap(),
        messages=[{"role": "user", "content": "Hello!"}]
    )

    # Parallel requests
    results = await asyncio.gather(
        client.vision.analyze(image_url="..."),
        client.audio.speech(input="Hello!"),
    )

asyncio.run(main())
```

## Audio Example

```python
from sdkrouter import SDKRouter, AudioModel

client = SDKRouter()

# Text-to-Speech
response = client.audio.speech(
    input="Hello!",
    model=AudioModel.cheap(),
    voice="nova",
)
Path("output.mp3").write_bytes(response.audio_bytes)

# Speech-to-Text
result = client.audio.transcribe(file=audio_bytes)
print(result.text)
```

### Deepgram Streaming

```python
from sdkrouter import AsyncSDKRouter
from sdkrouter.tools.audio.stt import DeepgramConfig

sdk = AsyncSDKRouter()

config = DeepgramConfig(
    model="nova-3",
    endpointing=300,   # VAD: silence threshold (ms)
    vad_events=True,   # Enable VAD events
)

async with sdk.audio.stt.stream_deepgram(config) as session:
    await session.send(audio_chunk)
    async for segment in session.transcripts():
        print(segment.text)
```

## Configuration

```python
# Environment variables (auto-loaded)
# SDKROUTER_API_KEY
# SDKROUTER_LLM_URL
# SDKROUTER_API_URL
# SDKROUTER_AUDIO_URL

client = SDKRouter(
    api_key="your-key",
    timeout=60.0,
    max_retries=3,
)
```

## Supported Providers

- **OpenAI**: GPT-4.5, GPT-4o, o3, o1
- **Anthropic**: Claude Opus 4.5, Claude Sonnet 4
- **Google**: Gemini 2.5 Pro, Gemini 2.0 Flash
- **Meta**: Llama 4, Llama 3.3
- **Mistral**: Mistral Large, Codestral
- **DeepSeek**: DeepSeek V3, R1
- And 300+ more via OpenRouter

## License

MIT
