OpenAI SDK
caesura-io-openai wraps OpenAI Chat Completions and Responses, including streaming, with sync and async clients. Requires Python 3.10+ and OpenAI Python 2.x or 3.x.
Install and use
pip install caesura-io-openai "openai>=2,<4"
Set OPENAI_API_KEY and CAESURA_API_KEY on the server.
from openai import OpenAI
from caesura_core import AnalysisContext, AnalyzeMessage, CustomerTurn
from caesura_openai import CaesuraOpenAIOptions, create_caesura
with create_caesura(OpenAI(), CaesuraOpenAIOptions(mode="sync")) as client:
conversation_id = client.create_conversation(name="Support session")
if conversation_id is None:
raise RuntimeError("Could not create a saved conversation.")
response = client.responses.create(
model="gpt-5.4-mini",
input="Can you help me?",
caesura_conversation_id=conversation_id,
caesura_context=AnalysisContext(
turn=CustomerTurn("customer-1", AnalyzeMessage("user", "Can you help me?")),
),
)
print(response.output_text)
For Chat Completions, call client.chat.completions.create() with messages and the same caesura_conversation_id and caesura_context options. Both APIs support stream=True; consume or close the stream to finalize persistence and usage reporting. Use the wrapped create() methods; native convenience .stream() and raw-response helpers bypass analysis.
Async applications
Use create_async_caesura(AsyncOpenAI(), options) in an async with block and await conversation creation and model calls. mode="sync" waits for guidance before generation with either client. The default, "async", makes completed background guidance available to a later call.
Reuse the backend conversation ID and supply growing dialogue history. Give each genuine customer message a distinct CustomerTurn ID; reuse it for retries. Put earlier participant dialogue in CustomerTurn.background, excluding tools, retrieval, and internal events. AnalysisContext() explicitly selects no new customer turn for an internal call.
Saving and failures
persist=True saves customer messages, their analyses, and completed agent replies to CaesuraO. Interrupted partial replies are not uploaded as completed messages. Use persist_transcript to also maintain an application-owned transcript and persist_result for required analysis-result storage. See Conversations & Persistence.
By default, analysis/storage failures are reported through on_error and generation continues. Set failure_policy="raise" with mode="sync" when guidance must succeed. Cancellation propagates; async callers can cancel their task, and explicit operation controls are available through AnalysisContext.
Drain background analysis with client.engine.drain() or await client.engine.drain() before closing if its result is required. Closing the client cancels unfinished analysis.
Observability
on_credit_usage receives analysis credits. on_provider_request receives the finalized model request; on_provider_outcome reports responses, stream completion, errors, and available usage. Analysis success and provider success are separate outcomes.