tealtiger-ai-sdk

TealTiger governance middleware for the Vercel AI SDK — deterministic policy evaluation, guardrails, cost tracking, circuit breaking, and audit logging for all LLM calls.

Quick Start

npm install tealtiger-ai-sdk ai tealtiger-sdk

import { wrapLanguageModel } from 'ai';
import { openai } from '@ai-sdk/openai';
import tealtigerMiddleware from 'tealtiger-ai-sdk';

// Zero-config: PII detection, prompt injection, content moderation enabled
const model = wrapLanguageModel({
  model: openai('gpt-4'),
  middleware: tealtigerMiddleware(),
});

That's it. Every call through model is now governed.

What It Does

The middleware intercepts LLM calls at three hook points:

| Hook | Phase | Governance | |------|-------|-----------| | transformParams | Pre-request | PII redaction, prompt injection detection, secret scanning, model allowlisting | | wrapGenerate | Non-streaming | Policy evaluation, circuit breaker, budget enforcement, output guardrails, audit logging | | wrapStream | Streaming | Same as wrapGenerate, with stream chunk accumulation |

Configuration

import tealtigerMiddleware from 'tealtiger-ai-sdk';

const middleware = tealtigerMiddleware({
  // Guardrails (all enabled by default in zero-config)
  guardrails: {
    pii: true,
    promptInjection: true,
    contentModeration: true,
    output: { contentModeration: true },
  },

  // Policy evaluation via TealEngine
  policy: { mode: 'ENFORCE' },

  // Circuit breaker per provider
  circuitBreaker: {
    failureThreshold: 5,
    timeout: 60000,
    halfOpenRequests: 3,
  },

  // Cost tracking and budget limits
  costTracking: {
    enabled: true,
    perRequestLimit: 0.50,
    dailyLimit: 50.00,
    anomalyThreshold: 200,
  },

  // Audit logging
  audit: {
    enabled: true,
    includeTraceIds: true,
  },

  // Secret detection
  secrets: { enabled: true, confidenceThreshold: 0.8 },

  // Model allowlisting
  registry: {
    enabled: true,
    allowedModels: ['openai/gpt-4', 'anthropic/claude-3-opus'],
  },

  // Fail behavior (default: fail-closed)
  failOpen: false,
  moduleTimeout: 5000,
});

Error Handling

The middleware throws typed errors you can catch:

import {
  PolicyViolationError,
  GuardrailViolationError,
  CircuitOpenError,
  BudgetExceededError,
} from 'tealtiger-ai-sdk';

try {
  const result = await generateText({ model, prompt: 'Hello' });
} catch (error) {
  if (error instanceof PolicyViolationError) {
    console.log('Blocked:', error.decision.reason_codes);
  } else if (error instanceof CircuitOpenError) {
    console.log(`${error.provider} is down, retry in ${error.retryAfterMs}ms`);
  } else if (error instanceof BudgetExceededError) {
    console.log(`${error.budgetType} limit reached, $${error.remainingBudget} remaining`);
  }
}

How It Works

1. Composition, not reimplementation — delegates to existing TealTiger v1.2 components (TealEngineV12, TealGuard, TealCircuit, TealAudit, CostTracker, TealSecrets, TealRegistry)
2. Synchronous factory, lazy init — tealtigerMiddleware() returns instantly; async module setup happens on first call
3. Deterministic — identical inputs produce identical decisions, no LLM in the governance path
4. Fail-closed by default — if governance evaluation fails, requests are denied (configurable)
5. Correlation IDs — UUID v4 links all decisions, logs, and cost records for a single request

Policy Files

Load external policy files:

const middleware = tealtigerMiddleware({
  policyPath: './governance/policy.json',
});

{
  "mode": "ENFORCE",
  "policyId": "production-v1",
  "rules": [
    {
      "id": "block-dangerous",
      "name": "Block dangerous prompts",
      "condition": "input.contains('hack')",
      "action": "DENY"
    }
  ]
}

Peer Dependencies

| Package | Version | |---------|---------| | ai (Vercel AI SDK) | ≥3.0.0 | | tealtiger-sdk | ≥1.2.0 |

Build

Dual ESM + CJS output targeting ES2020:

npm run build     # produces dist/index.mjs + dist/index.js + .d.ts files
npm run test      # vitest (430+ tests including property-based)
npm run typecheck # tsc --noEmit

License

Apache-2.0