Skip to main content

OpenAI SDK

The caesura-io-openai package wraps the official OpenAI Python client and intercepts Chat Completions and Responses calls to analyze dialogue and inject guidance.

warning

Status: Early development. API is not yet stable.

Install​

Requires Python 3.10+ and OpenAI Python 2.x or 3.x (openai>=2.0.0,<4.0.0).

pip install caesura-io-openai openai

Set OPENAI_API_KEY and CAESURA_API_KEY. The CaesuraO URL defaults to https://api.caesurao.com.

Sync client​

Use CaesuraOpenAIOptions for configuration. Persistence is enabled by default: create a backend conversation once, save its ID, and reuse it on every turn.

from openai import OpenAI
from caesura_openai import CaesuraOpenAIOptions, create_caesura

client = create_caesura(OpenAI(), CaesuraOpenAIOptions(mode="sync"))
conversation_id = client.create_conversation(name="Support session")

completion = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello agent!"}],
    caesura_conversation_id=conversation_id,
)

mode="sync" makes this example wait for analysis before generation. The default is "async", which runs analysis in the background. The model's response is separate from the CaesuraO analysis; receive analysis values through on_event.

Async client​

Use create_async_caesura with AsyncOpenAI. The following runs inside an async function:

from openai import AsyncOpenAI
from caesura_openai import CaesuraOpenAIOptions, create_async_caesura

client = create_async_caesura(AsyncOpenAI(), CaesuraOpenAIOptions(mode="sync"))
conversation_id = await client.create_conversation(name="Support session")

completion = await client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello agent!"}],
    caesura_conversation_id=conversation_id,
)

Python's sync/async client choice is independent of CaesuraO's observation mode. mode="sync" awaits analysis with either client. mode="async" makes completed guidance available to a later call with either client.

Responses and streaming​

Using the sync client and ID above:

response = client.responses.create(
    model="gpt-5.4-mini",
    input=[{"role": "user", "content": "Help me prepare for a meeting."}],
    caesura_conversation_id=conversation_id,
)

Both APIs support stream=True; async clients await the create call.

Supply your application's dialogue history on each turn. The ID associates saved analyses; it does not load history automatically. Close the client when finished (client.close() or await client.close() for async clients).

Local sessions or unsaved analysis​

For automatic conversation creation or analysis without saving, see Conversations & Persistence.

Tracking credit usage​

Adding on_credit_usage opts into usage metadata:

from openai import OpenAI
from caesura_openai import CaesuraOpenAIOptions, create_caesura, create_credit_meter

meter = create_credit_meter()
client = create_caesura(OpenAI(), CaesuraOpenAIOptions(
    on_credit_usage=meter.record,
))

# Run requests with the backend ID for each conversation.
print("Total credits consumed:", meter.total())
print("Credits by conversation:", meter.breakdown())

In background mode, credit callbacks arrive when analysis completes, which may be after the OpenAI response. Use on_error to report analysis failures and on_event to inspect activity.

See Configuration for typed options, analysis templates, budgets, speaker labels, and deduplication.