Metadata-Version: 2.4
Name: starseer
Version: 0.2.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
(currently **Claude Code** and **OpenCode**) 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, OpenCode, etc.) to use Starport with a single command:

```bash
# Interactive — walks you through setup (prompts for OAuth or API key)
starseer install

# Silent — Claude Code via OAuth (sign in with your claude.ai account through Starport)
starseer install --auth oauth --frameworks claude-code --scope global

# Silent — Claude Code via Starseer virtual key
starseer install --auth api-key --api-key ssk_... --frameworks claude-code --scope global

# Silent — OpenCode (Anthropic + OpenAI providers, both routed through Starport)
starseer install --api-key ssk_... --frameworks opencode --providers anthropic,openai --scope global
```

**Authentication methods for Claude Code:**

- **OAuth** (default when `--api-key` is not provided): You sign into Claude Code with your
  claude.ai account as usual. Starport proxies your traffic. Only `ANTHROPIC_BASE_URL`
  is written to `settings.json` — starseer does not write or update an API key in OAuth
  mode. Note: if you previously ran an API-key install, the existing `ANTHROPIC_API_KEY`
  is left in place; run `starseer uninstall` first if you want to clear it.
- **API key**: Claude Code authenticates using a Starseer virtual key (`ssk_...`).
  Both `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` are written. Requires that you are
  logged out of claude.ai (the installer will prompt, or pass `--logout` to do it automatically).

**OpenCode:**

OpenCode supports many LLM providers; pass `--providers` to choose which ones to route
through Starport (default: `anthropic`). Each selected provider gets a
`provider.<name>.options.{baseURL, apiKey}` block in `opencode.json` pointing at the
gateway path for that provider, including the upstream API's version prefix where
known: `<gateway>/anthropic/v1`, `<gateway>/openai/v1`, `<gateway>/google/v1beta`.
Other provider names pass through unchanged (e.g. `<gateway>/xai`) — OpenCode's
AI-SDK-based clients append only the endpoint name (`/messages`, `/chat/completions`),
so the version prefix has to live in baseURL. The same Starseer virtual key (`ssk_...`)
authenticates all providers; OpenCode is **API-key only** — OAuth mode is not supported.
Project scope writes `./opencode.json` at your repo root; add it to `.gitignore` if you
don't want to commit it.

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/
```
