starseer 0.2.0

Route LLM calls through Starport gateway

Starseer Python SDK

Route LLM API calls through Starport gateway.

Install

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:

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:

# 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

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:

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

To restore original SDK behavior:

starseer.unprotect(openai)

Tracing

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

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:

export STARSEER_API_KEY=ssk_...

Or configure in code:

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:

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:

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

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