Configuration

The Caesura SDKs are highly configurable, allowing you to adapt the analysis engine to your specific needs. Both @caesura-io/ai-sdk and @caesura-io/openai share the same core configuration options.

When initializing the middleware or wrapper, you pass a CaesuraConfig object. Below are the most important features worth mentioning.

Execution Mode

Controls whether recommendation generation blocks the model call.

{
  mode: 'async' // or 'sync'
}

• async (default): Non-blocking. Best for low latency (especially voice). The recommendation is injected in the next turn.
• sync: Awaits the analysis before calling the LLM. Slower, but provides the most precise, immediate steering.

Send Limits (Saving Credits & Cache)

The send configuration controls what portion of the dialogue window the SDK sends to the Caesura backend.

Because your credit usage depends on the length of the input sent to the analysis engine, trimming the history is a great way to save credits and reduce cache churn.

{
  send: {
    // Keep only the last N messages
    maxMessages: 10,
    
    // Cap the total characters sent (trims from the oldest messages first)
    maxInputChars: 4000
  }
}

Injection Settings

The inject configuration controls how and where recommendations are spliced into the model's context.

Managing Prompt Bloat

If your conversation runs long, injecting every recommendation can bloat the prompt.

{
  inject: {
    // Keep only the last N recommendations in the prompt
    keepLast: 3,
    
    // Expire recommendations after they become stale
    ttl: { type: 'turns', turns: 5 } // or { type: 'seconds', seconds: 120 }
  }
}

Placement & Formatting

You can control exactly where the text is placed and how it is formatted.

{
  inject: {
    // Inject at the end of the prompt, or right after the last analyzed turn
    placement: 'end', // or 'after-last-analyzed'
    
    // Which role the injected message uses
    as: 'user', // default is user to avoid creating a second system prompt
    
    // Customize the rendered string. Falls back to '' if fields are missing.
    template: 'New recommendation: {analysis.recommendation}',
    
    // Prepend a custom system-prompt-style "skill" instruction for the LLM
    skillPrompt: 'During the conversation you will periodically receive a "New recommendation". Treat it as private guidance for you, not as a message from the other party and not as something to read back to them. When a recommendation is present, let it shape your next response — act on it naturally as part of what you say.'
  }
}

Cadence Limits

To further save credits or avoid analyzing every trivial back-and-forth, you can restrict how often the SDK queries the backend.

{
  cadence: {
    // Query at most once every N turns
    everyTurns: 2,
    
    // Additionally, query at most once every N seconds
    everySeconds: 30
  }
}

Speaker Labels

You can customize the speaker labels sent to the backend to give the analysis engine better context.

{
  speakerNames: {
    agent: 'Support Rep', // Default: 'Agent'
    customer: 'Client'    // Default: 'Customer'
  }
}