proxle 0.0.1
Proxle SDK for Python - LLM observability and cost optimization
License: MIT
Requires Python: >=3.8

# Proxle Python SDK

LLM observability and cost optimization SDK for Python. Drop-in replacements for OpenAI, Anthropic, Azure OpenAI, Cohere, and Gemini clients that route through the Proxle proxy for automatic request logging, smart caching, and cost tracking.

## Installation

```bash
pip install proxle
```

Install with provider-specific dependencies:

```bash
# For OpenAI / Azure OpenAI support
pip install proxle[openai]

# For Anthropic support
pip install proxle[anthropic]

# For all providers
pip install proxle[all]
```

Cohere and Gemini clients use `httpx` (included by default) and don't require additional packages.

## Quick Start

### Configuration

Set your Proxle API key via environment variable or pass it directly:

```bash
export PROXLE_API_KEY=pk_live_your_key_here
export PROXLE_URL=https://api.proxle.dev  # optional, this is the default
```

### OpenAI

```python
from proxle import OpenAI

client = OpenAI(api_key="sk-your-openai-key", proxy_key="pk_live_...")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"feature": "chat_assistant", "user_id": "user_123"}
)
print(response.choices[0].message.content)
```

### Anthropic

```python
from proxle import Anthropic

client = Anthropic(api_key="sk-ant-your-key", proxy_key="pk_live_...")

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"feature": "summarizer"}
)
print(response.content[0].text)
```

### Azure OpenAI

```python
from proxle import AzureOpenAI

client = AzureOpenAI(
    api_key="your-azure-key",
    azure_endpoint="https://my-resource.openai.azure.com",
    api_version="2024-02-01",
    proxy_key="pk_live_...",
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"feature": "chat"}
)
```

### Cohere

```python
from proxle import Cohere

client = Cohere(api_key="your-cohere-key", proxy_key="pk_live_...")

response = client.chat(
    message="Hello!",
    model="command-r-plus",
    metadata={"feature": "chat"}
)
print(response["text"])
```

### Gemini

```python
from proxle import Gemini

client = Gemini(api_key="your-gemini-key", proxy_key="pk_live_...")

response = client.generate_content(
    model="gemini-1.5-pro",
    contents=[{"role": "user", "parts": [{"text": "Hello!"}]}],
    metadata={"feature": "chat"}
)
print(response["candidates"][0]["content"]["parts"][0]["text"])
```

## Metadata

All provider methods accept an optional `metadata` parameter for cost attribution:

```python
metadata = {
    "feature": "chat_assistant",  # Track cost by feature
    "user_id": "user_123",        # Track cost by user
    "environment": "production",  # Any custom tags
}
```

Metadata is sent as the `X-Metadata` header and stored with the request log in your Proxle dashboard.

## Streaming

### OpenAI Streaming

```python
stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
    metadata={"feature": "chat"}
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

### Anthropic Streaming

```python
with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"feature": "chat"}
) as stream:
    for text in stream.text_stream:
        print(text, end="")
```

### Cohere/Gemini Streaming

```python
for event in cohere_client.chat(message="Hello!", stream=True, metadata={"feature": "chat"}):
    print(event.get("text", ""), end="")
```

## Async Support

OpenAI, Anthropic, and Azure providers have async variants:

```python
from proxle import AsyncOpenAI, AsyncAnthropic, AsyncAzureOpenAI

client = AsyncOpenAI(api_key="sk-...", proxy_key="pk_live_...")
response = await client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"feature": "chat"}
)
```

## API Reference

### Providers

| Class | Wraps | Requires |
|-------|-------|----------|
| `OpenAI` / `AsyncOpenAI` | `openai.OpenAI` | `pip install proxle[openai]` |
| `Anthropic` / `AsyncAnthropic` | `anthropic.Anthropic` | `pip install proxle[anthropic]` |
| `AzureOpenAI` / `AsyncAzureOpenAI` | `openai.AzureOpenAI` | `pip install proxle[openai]` |
| `Cohere` | httpx (built-in) | None |
| `Gemini` | httpx (built-in) | None |

### Constructor Parameters

All providers accept:

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | `str` | Your provider API key |
| `proxy_key` | `str` (optional) | Proxle API key (or set `PROXLE_API_KEY` env var) |
| `proxy_url` | `str` (optional) | Proxle proxy URL (or set `PROXLE_URL` env var) |

Azure additionally requires `azure_endpoint` and `api_version`.

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .
```

## License

MIT