Configuration

Most applications can use the SDK defaults. Set CAESURA_API_KEY and follow Conversations & Persistence to choose a 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.

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 dialogue text is analyzed, excluding system instructions and tool results.

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. The integration guides include credit-meter and logger examples. 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.