starseer 0.4.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, OpenCode, and Codex) 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, Codex, 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

# Silent — Codex (API-key auth; export STARSEER_API_KEY before running `codex`)
starseer install --api-key ssk_... --frameworks codex --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.

Codex:

Codex's installer writes a sentinel-fenced [model_providers.starseer] block into ~/.codex/config.toml (or ./.codex/config.toml for project scope) plus a top-level model_provider = "starseer" line. Codex resolves API keys via env-var indirection, so before running codex you must export your Starseer key:

export STARSEER_API_KEY=ssk_...
codex

Codex is currently API-key only in this installer; the "Sign in with ChatGPT" OAuth/Device-Code flow is planned but requires gateway-side work that hasn't shipped yet. The installer leaves all user-authored TOML outside the sentinel-fenced block untouched, and starseer uninstall --frameworks codex only removes the fenced range (if a top-level model_provider line exists outside our block, the installer warns about it — Codex would reject the file with two assignments).

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/