Skip to main content

OpenAI SDK

The @caesura-io/openai package provides asynchronous, non-blocking recommendation injection for the official OpenAI Node SDK.

It acts as a transparent proxy wrapper around the OpenAI client. CaesuraO listens to your agent's dialogue and pushes short, real-time recommendations into the model's context without blocking the conversation.

warning

Status: Early development. API is not yet stable.

Install​

Install the CaesuraO wrapper alongside the official OpenAI package:

npm i @caesura-io/openai openai

Set OPENAI_API_KEY and CAESURA_API_KEY before running the snippets.

Quick Start​

Wrap your existing OpenAI client with createCaesura. Every call to responses.create or chat.completions.create is automatically intercepted. All other methods and nested resources pass through untouched.

Chat Completions API​

import OpenAI from 'openai';
// 1. Import the wrapper
import { createCaesura } from '@caesura-io/openai';

// 2. Wrap your client
const client = createCaesura(new OpenAI(), {
  // apiKey is auto-read from process.env.CAESURA_API_KEY if omitted
});

// Create once, save the backend ID, and reuse it on every turn.
const conversationId = await client.createConversation({ name: 'Support session' });
const conversation = [{ role: 'user' as const, content: 'Hello agent!' }];

// 3. Make your call, passing the caesura options in the second argument
const completion = await client.chat.completions.create({
  model: 'gpt-5.4-mini',
  messages: conversation,
}, {
  caesura: { conversationId },
});

Responses API​

You can also use the Responses API:

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

const client = createCaesura(new OpenAI(), {});

const conversationId = await client.createConversation({ name: 'Support session' });

const response = await client.responses.create({
  model: 'gpt-5.4-mini',
  input: 'Hello agent!',
}, {
  caesura: { conversationId },
});

Conversations and streaming​

Create a conversation once and reuse its ID on each turn. For automatic creation or analysis without saving, see Conversations & Persistence.

Pass caesura in the second argument and include your dialogue history in messages or input. Both APIs support stream: true.

Supported OpenAI Node versions are >=4.87.3 <8. The CaesuraO endpoint defaults to https://api.caesurao.com.

Tracking Credit Usage​

You can request credit-usage metadata on every analysis call and receive the reported value via the onCreditUsage callback.

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

// Initialize a credit meter
const meter = createCreditMeter();

const client = createCaesura(new OpenAI(), {
  // Pass the meter's record function to the callback
  onCreditUsage: meter.record,
});

// ... run requests with the backend ID for each conversation ...

// Query credit metrics later
console.log('Total credits consumed:', meter.total());
console.log('Credits by conversation:', meter.breakdown());
console.log('Retained credit events:', meter.events());
note

In async mode (the default), the onCreditUsage callback fires out-of-band as soon as the asynchronous analyze call completes. This is decoupled from the synchronous OpenAI request resolution.