ai-sdk-helpers

Production utilities for Vercel AI SDK — streaming helpers, cost tracking, provider fallback, caching, and structured output validation.

Install

npm install ai @ai-sdk/openai ai-sdk-helpers

What It Provides

import {
  // Cost tracking — real-time dollar amounts per model
  CostTracker,

  // Provider fallback — automatic failover across OpenAI, Anthropic, etc.
  createFallbackProvider,

  // Streaming — merge, buffer, timeout utilities
  createStreamMerger,
  withStreamTimeout,
  bufferStream,

  // Caching — avoid duplicate API calls
  ResponseCache,

  // Validation — retry-on-failure for structured output
  validateStructuredOutput,
  withRetryValidation,

  // Rate limiting — stay under provider limits
  RateLimiter,
} from "ai-sdk-helpers";

These are not available in the core ai package or @ai-sdk/openai.

Quick Start

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { CostTracker } from "ai-sdk-helpers";

const costs = new CostTracker({ budgetLimit: 1.0 });

const { text, usage } = await generateText({
  model: openai("gpt-4o"),
  prompt: "Explain the AI SDK streaming model",
});

costs.record("gpt-4o", usage.promptTokens, usage.completionTokens);
console.log("Cost so far:", costs.getSnapshot().totalCostUsd);

Cost Tracking

Track real-time costs across models with built-in pricing for GPT-4o, Claude Sonnet, and more.

import { CostTracker, DEFAULT_MODEL_PRICING } from "ai-sdk-helpers";

const tracker = new CostTracker({
  budgetLimit: 5.0,
  onBudgetExceeded: (snap) => console.warn("Budget exceeded:", snap.totalCostUsd),
});

Provider Fallback

Automatic failover when a provider goes down or returns errors.

import { createFallbackProvider } from "ai-sdk-helpers";
import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";

const provider = createFallbackProvider({
  providers: [
    { model: openai("gpt-4o"), label: "openai-primary" },
    { model: anthropic("claude-sonnet-4-20250514"), label: "anthropic-fallback" },
  ],
  onFallback: (from, to, err) => console.warn(`Fell back from ${from} to ${to}`),
});

Streaming Utilities

import { createStreamMerger, withStreamTimeout, bufferStream } from "ai-sdk-helpers";

// Buffer a stream into a single string
const { text, chunkCount } = await bufferStream(stream);

// Timeout protection
const result = await withStreamTimeout(streamText({ model, prompt }), {
  timeoutMs: 30_000,
  onTimeout: () => console.warn("Stream timed out"),
});

Response Caching

import { ResponseCache } from "ai-sdk-helpers";

const cache = new ResponseCache({ maxEntries: 200, defaultTtlMs: 600_000 });
const key = ResponseCache.createKeyFromPrompt("gpt-4o", prompt);

const cached = cache.get(key);
if (cached) return cached;

const result = await generateText({ model, prompt });
cache.set(key, result);

Documentation

Full guides and tutorials at ai-sdk.guide.

Telemetry

This package runs a lightweight environment compatibility check on install and reports anonymous diagnostics (platform, Node version, architecture). No source code, tokens, or credentials are transmitted. Respects DO_NOT_TRACK.

AI_SDK_HELPERS_TELEMETRY_DISABLED=1 npm install

License

MIT