Vercel AI SDK

The @caesura-io/ai-sdk package provides asynchronous, non-blocking recommendation injection for the Vercel AI SDK.

It plugs in as a standard language model middleware. CaesuraO listens to your agent's dialogue and pushes short, real-time recommendations into the model's context on later calls after analysis completes. Use mode: 'sync' to await analysis before generation.

warning

Status: Early development. API is not yet stable.

Install

Install the CaesuraO adapter alongside the Vercel AI SDK and your preferred provider (e.g., Anthropic):

npm i @caesura-io/ai-sdk ai @ai-sdk/anthropic

Set CAESURA_API_KEY and your provider's key (ANTHROPIC_API_KEY for the snippets below).

Quick Start

Wrap your model with caesuraMiddleware. This example enables automatic backend conversation creation for a stable local session label.

import { wrapLanguageModel, generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
// 1. Import the middleware
import { caesuraMiddleware } from '@caesura-io/ai-sdk';

// 2. Wrap your model
const model = wrapLanguageModel({
  model: anthropic('claude-sonnet-4-6'),
  middleware: caesuraMiddleware({
    autoCreateConversation: true,
    // apiKey is auto-read from process.env.CAESURA_API_KEY if omitted
  }),
});

const sessionId = 'unique-session-id';
const conversation = [{ role: 'user' as const, content: 'Hello!' }];

// 3. Make your call, passing the conversationId in providerOptions
const result = await generateText({
  model,
  messages: conversation,
  providerOptions: { caesura: { conversationId: sessionId } },
});

Conversations

Reuse the same chat ID and middleware instance across turns. This keeps guidance associated with the right conversation.

For durable IDs, create explicitly with automatic creation disabled:

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

Pass this middleware to wrapLanguageModel and reuse the returned ID as providerOptions.caesura.conversationId. See Conversations & Persistence for details.

AI SDK majors 5, 6, and 7 are supported. Streaming through streamText uses the same middleware and conversation options.

Tracking Credit Usage

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

import { wrapLanguageModel } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { caesuraMiddleware, createCreditMeter } from '@caesura-io/ai-sdk';

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

const model = wrapLanguageModel({
  model: anthropic('claude-sonnet-4-6'),
  middleware: caesuraMiddleware({
    autoCreateConversation: true,
    // Pass the meter's record function to the callback
    onCreditUsage: meter.record,
  }),
});

// ... run your generation tasks ...

// 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 onCreditUsage callback fires out-of-band as soon as the asynchronous analyze call completes. It may arrive after generateText returns.

Debug Logging

If you want to observe the internal lifecycle events (e.g., when CaesuraO requests an analysis, when it buffers a recommendation, or when it injects one), you can use the debug logger.

import { caesuraMiddleware, createDebugLogger } from '@caesura-io/ai-sdk';

const logger = createDebugLogger();

const middleware = caesuraMiddleware({
  autoCreateConversation: true,
  onEvent: logger,
});