Metadata-Version: 2.4
Name: starseer
Version: 0.1.0
Summary: Route LLM calls through Starport gateway
Project-URL: Repository, https://github.com/starseer-ai/starseer-python-sdk
Author-email: Starseer <support@starseer.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,anthropic,gemini,google,llm,openai,proxy,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: anthropic>=0.18.0; extra == 'dev'
Requires-Dist: google-genai>=1.0.0; extra == 'dev'
Requires-Dist: openai>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Description-Content-Type: text/markdown

# Starseer Python SDK

Route LLM API calls through Starport gateway.

## Install

```bash
pip install starseer
```

## Quick Setup (CLI) — Agent Frameworks

The SDK ships a `starseer install` CLI that configures AI agent frameworks (e.g. Claude Code)
to route their traffic through Starport. If you want to run that tool directly from the repo
rather than installing via pip:

```bash
git clone https://github.com/Starseer-ai/starseer-python-sdk
cd starseer-python-sdk
uv sync
uv run starseer install
#uv run python -m starseer install #(on Windows)
```

Configure AI agent frameworks (Claude Code, etc.) to use Starport with a single command:

```bash
# Interactive — walks you through setup
starseer install

# Silent — provide all options via flags
starseer install --api-key ssk_... --frameworks claude-code --scope global
```

Run `starseer install --help` for all options.

## Usage — Python SDK

```python
import starseer
import openai

starseer.protect(openai)

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

Async clients are also supported:

```python
client = openai.AsyncOpenAI()
response = await client.chat.completions.create(...)
```

To restore original SDK behavior:

```python
starseer.unprotect(openai)
```

## Tracing

Group multiple LLM calls under a single trace for correlated observability:

```python
with starseer.trace() as t:
    response1 = openai_client.chat.completions.create(...)
    response2 = anthropic_client.messages.create(...)
    print(f"Trace ID: {t.trace_id}")
```

All calls within the context share the same W3C trace ID.

## Configuration

Set your virtual key via environment variable:

```bash
export STARSEER_API_KEY=ssk_...
```

Or configure in code:

```python
starseer.configure(
    api_key="ssk_...",
    gateway_url="https://gateway.starseer.ai",  # optional
    openai_route="/openai/v1",              # optional, customize routing
    anthropic_route="/anthropic",           # optional
    auto_trace=True,                        # optional, auto-generate trace headers
)
```

## Environment Variables

| Variable | Required | Default |
|----------|----------|---------|
| `STARSEER_API_KEY` | Yes | - |
| `STARSEER_GATEWAY_URL` | No | `https://gateway.starseer.ai` |

## vLLM Routing

Route OpenAI SDK calls to a vLLM backend through the gateway:

```python
starseer.configure(
    gateway_url="http://localhost:8080",
    api_key="ssk_...",
    openai_route="/vllm/v1"
)

starseer.protect(openai)

client = openai.OpenAI()
response = client.chat.completions.create(
    model="meta-llama/Llama-3-8b",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

vLLM provides an OpenAI-compatible API, you can use the standard OpenAI SDK with the `openai_route` pointed to your vLLM endpoint.

## Cross-Provider Routing (Starport)

Use the OpenAI SDK to call Anthropic or other providers through Starport's OpenAI-compatible translation layer:

```python
import starseer
import openai

starseer.configure(
    gateway_url="https://your-starport-proxy.com",
    openai_route="/anthropic/openai/v1"
)

starseer.protect(openai)

client = openai.OpenAI()
response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

This allows you to use OpenAI SDK patterns while routing requests to Anthropic models on the backend.

## Supported SDKs

- `openai` (sync and async)
- `anthropic` (sync and async)
- `google-genai` (also detects the deprecated `google-generativeai`)

## Development

```bash
# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Lint and format
uv run ruff check src/
uv run ruff format src/
```
