Python SDK overview

The Python package wraps native provider clients and captures per-request cost metadata. Calls go directly to the provider; there is no proxy.

Hosted OTLP is a separate no-SDK option for providers/exporters such as OpenRouter Broadcast. The Python otel extra only adds trace correlation to wrapped calls.

• Package: superpenguin on PyPI
• Current version: 0.18.0
• License: MIT
• Python: 3.9+

Install

pip install superpenguin

Optional extras:

pip install "superpenguin[otel]"       # OpenTelemetry trace correlation
pip install "superpenguin[deepgram]"   # Deepgram STT
pip install "superpenguin[elevenlabs]" # ElevenLabs TTS
pip install "superpenguin[voice]"      # Deepgram + ElevenLabs
pip install "superpenguin[google]"     # Google Gemini (google-genai)

Initialize and wrap

import superpenguin as sp
from openai import OpenAI

sp.init(api_key="sp-...")

client = sp.wrap(OpenAI(), metadata={
    "customer_id": "cust_acme_123",
    "feature": "doc_summary",
})

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

Every create() through the wrapped client is captured with provider, model, token or unit counts, estimated cost, and latency.

Read current spend

Version 0.14.1 provides typed, low-latency spend reads. Use the same SDK key you use for ingestion; the authenticated organization is selected from that key.

import os
import superpenguin as sp

sp.init(api_key=os.environ["SP_API_KEY"])

current = sp.spend.get(window="1d")

print(current["spendUsd"])
print(current["asOf"], current["stalenessMs"])

1d means the current UTC calendar day, not the trailing 24 hours. Numbered windows include today plus the preceding N - 1 UTC days. month means the current UTC calendar month through today. Supported values are 1d through 7d, 14d, and month.

Filter by the feature or model recorded on usage events, or combine them:

filtered = sp.spend.get(
    window="7d",
    feature="document-processing",
    model="gpt-5",
)

The response contains:

There is no public freshThrough field; use asOf and stalenessMs to assess freshness. A spend result is advisory, not a reservation or concurrency-safe budget guarantee.

The SDK flushes locally buffered usage before the read by default. The ingest and materialization path is still asynchronous, so a flush does not guarantee a zero-staleness result. Pass flush=False to skip that local flush. Identical concurrent reads in one process share a single flush and HTTP request.

Spend reads use https://spend.superpenguin.ai automatically. You do not need to set SP_SPEND_BASE_URL. Advanced staging or private-gateway setups can set that variable or pass spend_base_url; the override affects only spend reads, while ingestion continues to use SP_BASE_URL / base_url.

Invalid requests and service failures raise SuperPenguinSpendError, with code, retryable, and optional HTTP status attributes. The SDK makes one bounded spend request and does not retry it automatically; retry only when retryable is true and doing so fits your application's policy. Codes are invalid_request, invalid_api_key, rate_limited, spend_unavailable, and request_failed.

Architecture

Your code
  |  client = sp.wrap(OpenAI())
  |  client.chat.completions.create(...)
  |
  |-- Call goes directly to the provider (no proxy)
  |
  '-- SDK extracts usage from the response
      '-- Batches events in a background thread
          '-- POSTs to /api/sdk/ingest

Next

• Supported providers
• Advanced usage
• Attribution metadata