SDK Quick Start

Native provider Batch APIs (OpenAI, Anthropic, Google Gemini Developer API) run async and file-based. Usage is only known after a job completes, so sp.wrap() / wrap() does not auto-capture them. Call a track_*_batch / track*Batch helper once when the job reaches a terminal success state.

import superpenguin as sp
from openai import OpenAI

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

batch = client.batches.retrieve("batch_abc")  # status == "completed"
count = sp.track_openai_batch(
    client,
    batch,
    metadata={"feature": "nightly-eval"},
)

Each succeeded request line emits one batch=true row backdated to the batch completion time, with a deterministic idempotency key (batch_id:custom_id). Retries are safe: duplicate keys dedupe on the server.

The server prices batch=true rows from explicit rate_variants.batch catalog legs (no runtime multiplier). Each batch event also carries base_url (the provider endpoint hostname) so the dashboard can infer which platform billed the job (e.g. Azure vs first-party OpenAI).

Some providers charge different token rates by AWS region, deployment type (Azure data zone / Bedrock cross-region), or service tier (OpenAI flex / priority / batch). The SDK forwards these as first-class event fields so the server can pick the right rate card. They are not attribution tags: reserved keys are stripped from custom_tags.

Precedence:per-call value > wrap-level override > auto-capture > omitted (server uses the model's default reference price). Every field is optional.

AWS Bedrock sends cost_usd_micros: 0 from the client; the server always prices Bedrock rows with the live aws_bedrock catalog (including per-region variants when present). Converse has no per-call metadata passthrough, so use wrap kwargs for deployment_type and attribute with sp.metadata() / @sp.trace.

# AWS Bedrock: region is auto-captured from the boto3 client.
# deployment_type is wrap-level only (Converse has no per-call metadata bag).
import boto3

client = sp.wrap(
    boto3.client("bedrock-runtime", region_name="ap-northeast-1"),
    metadata={"feature": "doc_summary"},
    deployment_type="global",  # optional: global / geo / in-region Nova profiles
)

client.converse(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role": "user", "content": [{"text": "Hello"}]}],
)
# Row carries region="ap-northeast-1" and cost is priced server-side.

By default the SDK sends only cost metadata, never prompt or completion text. If your org opts in from Settings (Pro or Enterprise), the SDK then captures a sampled subset of prompts and completions automatically. There is nothing to call to turn it on. Samples are text-only (images, audio, and binary parts are stripped), redacted by default, encrypted at rest, and deletable by the org owner from Settings.

Grouping multi-turn conversations. Set two metadata keys so captured rows can be stitched back together: session_id identifies one conversation, and turn_id identifies one turn. Each model call is its own row, so a turn that makes a tool call (model → tool → model) spans two rows: reuse the same turn_id across those calls to group them. If you omit turn_id, each row gets a fresh random one and will not group.

import superpenguin as sp
from openai import OpenAI

sp.init(api_key="sp-...")
client = sp.wrap(OpenAI())

# Capture is OFF until your org opts in from Settings (Pro/Enterprise). Once on,
# sampled prompts + completions are captured automatically and encrypted at rest.
# Group them with two metadata keys:
#   session_id  -> one conversation
#   turn_id     -> one turn (reuse it across a tool round-trip to group calls)
with sp.metadata({
    "session_id":  conversation_id,
    "turn_id":     turn_id,
    "customer_id": "cust_acme_123",
    "prompt_key":  "support-reply",
}):
    first = client.chat.completions.create(model="gpt-4o", messages=msgs)
    # ...the model requests a tool; you run it locally...
    final = client.chat.completions.create(model="gpt-4o", messages=msgs_with_tool_result)

# Optional: narrow capture from the SDK side. It can only REDUCE capture,
# never enable it (the Settings opt-in is always required).
sp.configure_content_capture(
    allow=True,           # False vetoes ALL capture from this process
    record_prompt=True,   # False drops inputs, keeps outputs
    record_outcome=True,  # False drops outputs, keeps inputs
)

configure_content_capture() / configureContentCapture() can only narrow what is captured (veto entirely with allow=False, or keep only one side with record_prompt / record_outcome). It can never enable capture, the Settings opt-in is always required.

Get notified in Slack, email, or Discord when your AI spend crosses a threshold. Alerts require a Growth plan or above.