Skip to main content

OpenAI SDK

The Caesura Python SDKs provide asynchronous, non-blocking recommendation injection for Python applications.

Which SDK should I use?​

Currently, we provide a wrapper for the official OpenAI SDK.

caesura-io-openai​

This package is a transparent proxy wrapper around the official OpenAI Python SDK. It intercepts calls to the Chat Completions and Responses APIs.

warning

Status: Early development. API is not yet stable.

Install​

Install the Caesura wrapper alongside the official OpenAI package:

pip install caesura-io-openai openai

Quick Start​

Wrap your existing OpenAI client with create_caesura. Every call to chat.completions.create or responses.create is automatically intercepted. All other methods and nested resources pass through untouched.

Sync Client (Chat Completions)​

import openai
from caesura_openai import create_caesura

# 1. Wrap your client
client = create_caesura(openai.OpenAI(), {
    "base_url": "https://dev.caesura.io",
    # api_key is auto-read from process.env.CAESURA_API_KEY if omitted
})

session_id = 'unique-session-id'
conversation = [{"role": "user", "content": "Hello agent!"}]

# 2. Make your call, passing the caesura options
completion = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=conversation,
    caesura_conversation_id=session_id,
)

Async Client (Chat Completions)​

If you are using AsyncOpenAI, use create_async_caesura instead:

import openai
from caesura_openai import create_async_caesura

client = create_async_caesura(openai.AsyncOpenAI(), {
    "base_url": "https://dev.caesura.io",
})

completion = await client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=conversation,
    caesura_conversation_id=session_id,
)

Tracking Credit Usage​

You can request credit-usage metadata on every analysis call and receive the reported value via the on_credit_usage callback.

import openai
from caesura_openai import create_caesura, create_credit_meter

# Initialize a credit meter
meter = create_credit_meter()

client = create_caesura(openai.OpenAI(), {
    "base_url": "https://dev.caesura.io",
    # Pass the meter's record function to the callback
    "on_credit_usage": meter.record,
})

# ... run your API requests ...

# Query credit metrics later
print("Total credits consumed:", meter.total())
print("Credits by conversation:", meter.breakdown())
note

In async mode (the default), the on_credit_usage callback fires out-of-band as soon as the asynchronous analyze call completes. This is decoupled from the synchronous OpenAI request resolution.

Sync vs Async Observation Mode​

Caesura's mode setting ("sync" or "async") controls whether recommendation generation blocks the model call. It is independent of whether you use Python's sync OpenAI or async AsyncOpenAI client:

  • mode="async" (default): Observation runs in the background. Recommendations appear on the next turn.
  • mode="sync": Observation runs inline. Recommendations are injected into the current turn.

Both modes work with both the sync and async Python clients.