Configuration

Most applications can use the SDK defaults. Set CAESURA_API_KEY and follow Conversations & Persistence to create and reuse a backend conversation ID. The API URL defaults to https://api.caesurao.com.

JavaScript accepts an options object. Python uses CaesuraOpenAIOptions with the configuration classes shown below.

To override the endpoint, set baseUrl in JavaScript or base_url in Python. Supply the base URL without /api; the SDK adds the route paths. The runnable examples read this setting from CAESURA_BASE_URL.

When guidance is available

• async (default): Analysis runs in the background. Completed guidance is available to a later model call.
• sync: Analysis finishes before generation, so guidance can affect the current call.

Set mode: 'sync' in JavaScript or mode="sync" in Python. Both modes work with Python's sync and async clients. Use sync in short scripts that need analysis to finish before exiting.

Limit analysis and prompt size

send limits what goes to CaesuraO. inject controls how much guidance goes to your model. For example, send at most 10 messages and 4,000 characters, and inject the latest three analyses:

import { createCaesura } from '@caesura-io/openai';
import OpenAI from 'openai';

const client = createCaesura(new OpenAI(), {
  send: { maxMessages: 10, maxInputChars: 4000 },
  inject: { keepLast: 3 },
});

from openai import OpenAI
from caesura_openai import (
    CaesuraOpenAIOptions, InjectConfig, SendConfig, create_caesura,
)

client = create_caesura(OpenAI(), CaesuraOpenAIOptions(
    send=SendConfig(max_messages=10, max_input_chars=4000),
    inject=InjectConfig(keep_last=3),
))

Send limits include dialogue and previous analyses, prioritizing the newest dialogue. They do not trim your model's input. By default, the SDK sends at most 10 messages with no character cap, and injects all retained guidance.

Set keepLast: 0 / keep_last=0 to turn off injection. A zero send limit skips analysis.

Guidance placement and formatting

By default, guidance is inserted after the dialogue it analyzed, as a user message. Set inject.placement to "end" to append it instead. Keep your application's dialogue history separate from injected guidance; the SDK manages guidance for you.

The default template is CONVERSATION ANALYSIS:\n{analysis}. It includes the full analysis, which can be JSON or text. A recommendation field is not guaranteed. Use a field template such as {analysis.recommendation} only when your response includes that field.

To expire guidance, use inject.ttl: { type: 'turns', turns: 5 } in JavaScript or InjectConfig(ttl=TtlTurns(turns=5)) in Python. Import TtlTurns from caesura_openai. Guidance does not expire by default.

Speaker names

Give CaesuraO useful participant names with speakerNames: { agent: 'Support Rep', customer: 'Client' } in JavaScript or speaker_names=SpeakerNames(agent="Support Rep", customer="Client") in Python. Import SpeakerNames from caesura_openai.

Guidance is for the configured agent. Keep normal user and assistant roles in your model messages; the SDK handles the analysis API's speaker mapping. Only genuine customer turns trigger analysis; earlier agent dialogue provides background. System instructions and tool results are excluded. For retrieval or other application-generated user messages, explicitly select trusted dialogue with JavaScript dialogue or Python CustomerTurn.background.

Optional controls

Purpose	JavaScript	Python
Analyze at most every two turns	cadence: { everyTurns: 2 }	cadence=CadenceConfig(every_turns=2)
Report analysis errors	onError	on_error
Inspect lifecycle events	onEvent	on_event
Track reported credits	onCreditUsage	on_credit_usage

Python's CadenceConfig is exported by caesura_openai. Model generation can continue after an analysis error, so use the error callback when troubleshooting.

For similar recommendations, optionally set similarityThreshold / similarity_threshold. Similarity calculation alone does not suppress duplicates. When the backend returns isSame: true, the SDK keeps the previous guidance without adding the duplicate.

Failures, cancellation, and background work

Under the default continue policy, a failed hosted customer-message save still permits analysis without persistence for that call. Failed analysis permits generation without new guidance; a failed reply save does not withhold the reply. Failed creation returns undefined / None; explicitly select a stateless call to continue without an ID. Configure error callbacks to observe failures. Required application hooks retain their own contracts. Use failurePolicy: 'throw' in JavaScript or failure_policy="raise" in Python with synchronous analysis when guidance is required. Caller cancellation and deadlines still stop the call regardless of this policy. Dependency timeouts follow the failure policy.

JavaScript accepts an AbortSignal through the provider call (abortSignal in AI SDK, signal in OpenAI). Python supports async task cancellation and explicit AnalysisContext operation controls.

Finish required background work before your process exits: await JavaScript client.caesura.flush() / middleware.caesura.flush(), or call Python client.engine.drain() (await it for an async client). Closing the Python client cancels unfinished work.

SDK metadata and audit hooks

SDK requests identify the language, core/integration package versions, transport, and runtime. This diagnostic metadata is separate from dialogue and is not an instruction to the model.

To inspect the request after guidance injection, use JavaScript onProviderEvent or Python on_provider_request / on_provider_outcome. Required request storage uses JavaScript persistProviderRequest; Python's provider-request hook is awaited; use failure_policy="raise" when its storage must succeed before generation. Follow the advanced JavaScript or Python guide for custom storage and auditing.