Orbit SDK for Python
Track, monitor, and optimize your AI spend across OpenAI, Anthropic, and other LLM providers.
Installation
pip install withorbit-sdk
# With OpenAI support
pip install withorbit-sdk[openai]
# With Anthropic support
pip install withorbit-sdk[anthropic]
# With Google Gemini support (new SDK)
pip install withorbit-sdk[google]
# With Google Gemini support (legacy SDK)
pip install withorbit-sdk[google-legacy]
# With all providers
pip install withorbit-sdk[all]
Quick Start
1. Get your API key
Sign up at Orbit and create an API key.
2. Initialize the SDK
from withorbit_sdk import Orbit
orbit = Orbit(
api_key="orb_live_xxxxxxxxxxxxxxxxxxxxxxxx",
default_feature="my-app", # Optional: default feature for all events
)
3. Track your LLM calls
Option A: Automatic tracking (Recommended)
Wrap your OpenAI or Anthropic client for automatic tracking:
from openai import OpenAI
from withorbit_sdk import Orbit, WrapperOptions
orbit = Orbit(api_key="orb_live_xxx")
openai = orbit.wrap_openai(OpenAI(), WrapperOptions(feature="chat-assistant"))
# All API calls are now automatically tracked!
response = openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello, world!"}],
)
Works with Anthropic too:
from anthropic import Anthropic
from withorbit_sdk import Orbit, WrapperOptions
orbit = Orbit(api_key="orb_live_xxx")
anthropic = orbit.wrap_anthropic(Anthropic(), WrapperOptions(feature="document-analysis"))
message = anthropic.messages.create(
model="claude-3-opus-20240229",
max_tokens=1024,
messages=[{"role": "user", "content": "Analyze this document..."}],
)
Works with Google Gemini (new google-genai SDK):
from google.genai import Client
from withorbit_sdk import Orbit, WrapperOptions
orbit = Orbit(api_key="orb_live_xxx")
client = orbit.wrap_google(Client(api_key="your-gemini-key"), WrapperOptions(feature="chat"))
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="Hello, how are you?",
)
Works with Google Gemini (legacy google-generativeai SDK):
import google.generativeai as genai
from withorbit_sdk import Orbit, WrapperOptions
genai.configure(api_key="your-gemini-key")
model = genai.GenerativeModel("gemini-2.0-flash")
orbit = Orbit(api_key="orb_live_xxx")
wrapped_model = orbit.wrap_google_legacy(model, WrapperOptions(feature="chat"))
response = wrapped_model.generate_content("Hello, how are you?")
Option B: Manual tracking
For other providers or custom implementations:
from withorbit_sdk import Orbit
orbit = Orbit(api_key="orb_live_xxx")
# Track a successful request
orbit.track(
model="gpt-4o",
input_tokens=150,
output_tokens=50,
latency_ms=1234,
feature="summarization",
environment="production",
)
# Track an error
orbit.track_error(
model="gpt-4o",
error_type="rate_limit_exceeded",
error_message="Rate limit exceeded",
feature="chat-assistant",
input_tokens=150,
)
Configuration
from withorbit_sdk import Orbit, OrbitConfig
orbit = Orbit(config=OrbitConfig(
# Required
api_key="orb_live_xxx",
# Optional
base_url="https://app.withorbit.io/api/v1", # Custom API endpoint
default_feature="my-app", # Default feature name
default_environment="production", # 'production' | 'staging' | 'development'
debug=False, # Enable debug logging
# Batching (for high-volume applications)
batch_events=True, # Batch events before sending
batch_size=10, # Max events per batch
batch_interval=5.0, # Max seconds before sending batch
# Reliability
retry=True, # Retry failed requests
max_retries=3, # Max retry attempts
))
Feature Attribution
Features are Orbit's key differentiator - they let you see exactly which parts of your application are consuming AI resources:
# Track different features
orbit.track(
model="gpt-4o",
input_tokens=100,
output_tokens=50,
feature="chat-assistant", # Attribute to chat feature
)
orbit.track(
model="gpt-4o",
input_tokens=500,
output_tokens=200,
feature="document-analysis", # Attribute to doc analysis
)
Then in the Orbit dashboard, you'll see:
- Cost breakdown by feature
- Request volume by feature
- Error rates by feature
- And more!
Agentic Task Tracking
Track multi-step agentic workflows by grouping related LLM calls under a task:
# All calls with the same task_id are grouped together
openai = orbit.wrap_openai(OpenAI(), WrapperOptions(
feature="ai-agent",
task_id="task_abc123", # Group all LLM calls for this task
customer_id="cust_xyz789", # Attribute costs to this customer
))
# Step 1: Plan
openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Plan how to analyze this data..."}],
)
# Step 2: Execute
openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Now execute the analysis..."}],
)
# Both calls are tracked under task_abc123
In the Orbit dashboard, you can then see:
- All LLM calls grouped by task
- Total cost per task
- Customer-level cost attribution
Context Manager Support
from withorbit_sdk import Orbit
with Orbit(api_key="orb_live_xxx") as orbit:
orbit.track(model="gpt-4o", input_tokens=100, output_tokens=50)
# Automatically flushes on exit
Graceful Shutdown
For long-running processes, flush events before exit:
# Before your process exits
orbit.shutdown()
Event Properties
| Property | Type | Required | Description |
|---|---|---|---|
model |
str | Yes | Model name (e.g., 'gpt-4o', 'claude-3-opus') |
input_tokens |
int | Yes | Number of input tokens |
output_tokens |
int | Yes | Number of output tokens |
provider |
str | No | Provider name (auto-detected if not provided) |
latency_ms |
int | No | Request latency in milliseconds |
feature |
str | No | Feature name for attribution |
environment |
str | No | Environment ('production', 'staging', 'development') |
status |
str | No | Request status ('success', 'error', 'timeout') |
error_type |
str | No | Error type if status is 'error' |
error_message |
str | No | Error message if status is 'error' |
user_id |
str | No | Your application's user ID |
session_id |
str | No | Session ID for grouping requests |
request_id |
str | No | Unique request ID for tracing |
task_id |
str | No | Task ID for grouping related LLM calls in agentic workflows |
customer_id |
str | No | Customer ID for billing attribution |
metadata |
dict | No | Additional key-value metadata |
License
MIT
Metadata
Release files for withorbit-sdk 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| withorbit_sdk-0.1.5.tar.gz | 14.6 kB | Without provenance | Details for withorbit_sdk-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| withorbit_sdk-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for withorbit_sdk-0.1.5-py3-none-any.whl |
Total release size: 33.2 kB
Release files / withorbit_sdk-0.1.5.tar.gz
| Download URL | withorbit_sdk-0.1.5.tar.gz |
|---|---|
| Size | 14.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1bd3dc3b2bf9b228974c422cf54b47a475ed696a7ad9aa079b29a2e164531689
|
|
BLAKE2b-256 checksum How to use checksums |
97afcebd8bf4e3f833beeefb490064cac1e12ee9e50195da697bc736a7932e47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Release files / withorbit_sdk-0.1.5-py3-none-any.whl
| Download URL | withorbit_sdk-0.1.5-py3-none-any.whl |
|---|---|
| Size | 18.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67aa1729e91908c73f0ed258ba647cfe97e60690672f44df74e89f0769cda507
|
|
BLAKE2b-256 checksum How to use checksums |
a0561516abb664b176e4f9d9dcebd4c38789791bb31faad7650b0600340501d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Security for withorbit-sdk 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.