ai-contracts

ai-contracts

Reliability layer for AI outputs: schema validation, JSON repair, retry, fallback, and budget guards.

Stop losing users to broken JSON and flaky LLM responses. ai-contracts gives you production-grade structured output handling in a few lines of code.

30-Second Quickstart

npm install ai-contracts zod

import { safeParse } from 'ai-contracts';
import { z } from 'zod';

const UserSchema = z.object({
  name: z.string(),
  age: z.number(),
});

// Parse LLM output safely
const result = safeParse(llmOutput, { schema: UserSchema });

if (result.success) {
  console.log(result.data); // { name: "John", age: 30 }
} else {
  console.error(result.error.code); // "VALIDATION_FAILED" | "PARSE_FAILED" | etc.
}

Why ai-contracts?

Real problems this solves:

• 🔧 Malformed JSON - LLMs return markdown code blocks, trailing commas, unquoted keys
• 📋 Schema mismatches - Response structure doesn't match your types
• 🔄 Retry storms - Retries without backoff hammer rate limits
• 🔀 Unstable fallbacks - Switching providers breaks your app
• 💸 Budget blowouts - No visibility into token/cost usage
• 🔍 Debugging nightmares - Raw output lost when parsing fails

Features

Feature	Description
Schema Validation	Zod-first, type-safe validation
JSON Repair	Auto-fix markdown blocks, trailing commas, unquoted keys
Bounded Retry	Exponential backoff with jitter
Ordered Fallback	Deterministic provider failover
Budget Guards	Token and cost limits with hard stops
Typed Errors	Error codes, raw output traces, provider metadata
Observability Hooks	onAttempt, onRepair, onRetry, onFallback, onFail

Installation

npm install ai-contracts zod

Core API

safeParse(input, options)

Parse and validate a string against a Zod schema.

import { safeParse } from 'ai-contracts';
import { z } from 'zod';

const schema = z.object({ answer: z.string() });

// Auto-repairs malformed JSON
const result = safeParse('```json\n{answer: "hello"}\n```', { schema });
// result.success === true
// result.data === { answer: "hello" }
// result.stage === "repair"

safeGenerate(generateFn, callOptions, options)

Full pipeline: generate → parse → validate → retry → fallback.

import { safeGenerate } from 'ai-contracts';
import { createOpenAIGenerateFn } from 'ai-contracts/adapters/openai';
import OpenAI from 'openai';
import { z } from 'zod';

const openai = new OpenAI();
const generate = createOpenAIGenerateFn(openai);

const result = await safeGenerate(
  generate,
  {
    prompt: 'Return a JSON object with name and age',
    model: 'gpt-4o',
  },
  {
    schema: z.object({ name: z.string(), age: z.number() }),
    retry: { maxAttempts: 3 },
    fallbacks: [
      { provider: 'openai', model: 'gpt-4o-mini' },
    ],
    budget: { maxTokens: 1000 },
    hooks: {
      onRetry: ({ attempt, error }) => console.log(`Retry ${attempt}: ${error.message}`),
      onFallback: ({ from, to }) => console.log(`Fallback: ${from.model} → ${to.model}`),
    },
  }
);

withRetry(fn, policy, hooks)

Retry any async function with configurable backoff.

import { withRetry } from 'ai-contracts';

const data = await withRetry(
  () => fetchFromAPI(),
  {
    maxAttempts: 3,
    baseDelayMs: 1000,
    exponentialBackoff: true,
  }
);

withFallback(fn, fallbacks, createFallbackFn)

Execute with ordered fallback providers.

import { withFallback } from 'ai-contracts';

const result = await withFallback(
  () => primaryProvider(),
  [{ provider: 'backup', model: 'backup-model' }],
  (config) => () => backupProvider(config)
);

withBudget(fn, config)

Enforce token and cost limits.

import { withBudget } from 'ai-contracts';

const result = await withBudget(
  async () => ({
    result: await generate(),
    usage: { promptTokens: 100, completionTokens: 50, totalTokens: 150 },
  }),
  { maxTokens: 1000, maxCostUsd: 0.10 }
);

Provider Adapters

OpenAI

import OpenAI from 'openai';
import { createOpenAIGenerateFn } from 'ai-contracts/adapters/openai';
import { safeGenerate } from 'ai-contracts';

const openai = new OpenAI();
const generate = createOpenAIGenerateFn(openai);

const result = await safeGenerate(
  generate,
  { prompt: 'Hello', model: 'gpt-4o' },
  { schema: mySchema }
);

Anthropic

import Anthropic from '@anthropic-ai/sdk';
import { createAnthropicGenerateFn } from 'ai-contracts/adapters/anthropic';
import { safeGenerate } from 'ai-contracts';

const anthropic = new Anthropic();
const generate = createAnthropicGenerateFn(anthropic);

const result = await safeGenerate(
  generate,
  { prompt: 'Hello', model: 'claude-sonnet-4-20250514' },
  { schema: mySchema }
);

Vercel AI SDK

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { createAISDKGenerateFn } from 'ai-contracts/adapters/ai-sdk';
import { safeGenerate } from 'ai-contracts';

const model = openai('gpt-4o');
const generate = createAISDKGenerateFn(generateText, model);

const result = await safeGenerate(
  generate,
  { prompt: 'Hello', model: 'gpt-4o' },
  { schema: mySchema }
);

Error Model

All errors include:

interface ContractError {
  code: 'PARSE_FAILED' | 'REPAIR_FAILED' | 'VALIDATION_FAILED' | 
        'RETRY_EXHAUSTED' | 'FALLBACK_EXHAUSTED' | 'BUDGET_EXCEEDED' | 
        'PROVIDER_ERROR' | 'TIMEOUT';
  message: string;
  stage: 'strict' | 'repair' | 'validation';
  attempts: number;
  rawOutput?: string;        // Truncated to 500 chars
  meta?: ProviderMeta;       // provider, model, requestId
  validationErrors?: ZodError['errors'];
  cause?: Error;
}

Migration from Manual JSON.parse

Before:

// Fragile, no repair, no retries, no observability
try {
  const data = JSON.parse(llmOutput);
  // Hope it matches your expected shape...
} catch (e) {
  console.error('Parse failed:', e);
}

After:

import { safeParse } from 'ai-contracts';
import { z } from 'zod';

const result = safeParse(llmOutput, {
  schema: z.object({ answer: z.string() }),
});

if (result.success) {
  // Type-safe, validated data
  console.log(result.data.answer);
} else {
  // Actionable error with full context
  console.error(result.error.code, result.error.rawOutput);
}

Benchmarks

Metric	Without ai-contracts	With ai-contracts
Parse success rate	~85%	~99%
Schema validation errors	Uncaught	Typed & actionable
Retry logic	Manual	Built-in with backoff
Fallback handling	Ad-hoc	Deterministic chain
Debug info on failure	Lost	Full context preserved
Overhead	N/A	<1ms parse, <5ms repair

Tested on 10,000 synthetic malformed JSON samples with common LLM artifacts.

Configuration Reference

Retry Policy

interface RetryPolicy {
  maxAttempts: number;        // Default: 3
  baseDelayMs: number;        // Default: 1000
  exponentialBackoff: boolean; // Default: true
  maxDelayMs: number;         // Default: 30000
  jitter: number;             // Default: 0.1 (10%)
}

Budget Config

interface BudgetConfig {
  maxTokens?: number;
  maxCostUsd?: number;
  promptTokenCostPer1k?: number;
  completionTokenCostPer1k?: number;
}

Logging Hooks

interface LoggingHooks<T> {
  onAttempt?: (info: { attempt: number; provider?: string; model?: string }) => void;
  onRepair?: (info: { rawOutput: string; repairAttempt: number }) => void;
  onRetry?: (info: { attempt: number; error: ContractError; delayMs: number }) => void;
  onFallback?: (info: { from: ProviderMeta; to: FallbackConfig; error: ContractError }) => void;
  onSuccess?: (result: ContractSuccess<T>) => void;
  onFail?: (error: ContractError) => void;
}

TypeScript Support

Full type inference from Zod schemas:

import { safeParse, type InferSchema } from 'ai-contracts';
import { z } from 'zod';

const MySchema = z.object({
  name: z.string(),
  items: z.array(z.number()),
});

type MyData = InferSchema<typeof MySchema>;
// { name: string; items: number[] }

const result = safeParse(input, { schema: MySchema });
if (result.success) {
  result.data.name;  // TypeScript knows this is string
}

Contributing

git clone https://github.com/wnxd/ai-contracts.git
cd ai-contracts
npm install
npm run test
npm run typecheck

License

MIT