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. Caesura 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 Caesura wrapper alongside the official OpenAI package:

npm i @caesura-io/openai openai

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(), {
  baseUrl: 'https://dev.caesura.io',
  // apiKey is auto-read from process.env.CAESURA_API_KEY if omitted
});

const sessionId = 'unique-session-id';
const conversation = [{ role: 'user', 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: sessionId },
});

Responses API​

The wrapper also fully supports the newer Responses API:

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

const client = createCaesura(new OpenAI(), {
  baseUrl: 'https://dev.caesura.io',
});

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

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(), {
  baseUrl: 'https://dev.caesura.io',
  // Pass the meter's record function to the callback
  onCreditUsage: meter.record,
});

// ... run your API requests ...

// 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.