caesura-io-openai

CaesuraO recommendations for OpenAI Python 2.x and 3.x. Supports Chat Completions and Responses through create(), including streaming, with sync and async clients.

pip install caesura-io-openai openai

Set OPENAI_API_KEY and CAESURA_API_KEY, then create a conversation once:

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 conversation")
    response = client.responses.create(
        model="gpt-5.4-mini",
        input="Can you help me?",
        caesura_conversation_id=conversation_id,
        caesura_stateless=conversation_id is None,
        caesura_context=AnalysisContext(
            turn=CustomerTurn("customer-message-1", AnalyzeMessage("user", "Can you help me?")),
        ),
    )
    print(response.output_text)

Save a successfully returned conversation ID and reuse it on later calls. With continue policy, creation failure returns None; caesura_stateless=True explicitly permits a one-shot call without saved conversation state. Fallback respects mode; choose "sync" for same-call guidance. Use a distinct customer message ID for each new turn and reuse it on retries. The SDK does not fetch history.

For async applications, use create_async_caesura(AsyncOpenAI(), options) and await creation/model calls. For Chat Completions, use client.chat.completions.create() with messages and the same caesura_conversation_id / caesura_context options.

Behavior and options

Analysis mode is independent of Python's sync/async client type. An authoritative conversation ID is required for stateful calls even with persist=False. Completed customer messages and agent replies are saved by default. Use persist_transcript for an additional application-owned archive, including partial output.

New customer turns trigger analysis. Earlier assistant dialogue provides background; tool/RAG content should be excluded with explicit CustomerTurn selection. Keep your application dialogue separate from SDK-injected requests.

Use stream=True and consume or close streams to finalize usage and persistence. The wrapper preserves native chunks but returns a delegating stream proxy. Convenience .stream() and raw-response helpers bypass the analysis wrapper; use create().

on_credit_usage=create_credit_meter().record collects credit usage. on_provider_request captures the finalized model request; on_provider_outcome reports responses, stream completion, errors, and available usage.

See application integration for guidance placement, stores, cancellation, and audit contracts; migration for breaking changes; and runnable applications for local examples.

Licensed under Apache-2.0.