ai-sdk-guardrails 1.0.0 → 3.0.0

package/README.md

@@ -1,729 +1,651 @@
 # AI SDK Guardrails
 
-The safest way to build production AI applications with the Vercel AI SDK. A comprehensive TypeScript library that protects your AI systems with intelligent input and output validation, streaming safety, and enterprise-grade reliability.
+A powerful middleware for the Vercel AI SDK that adds safety, quality control, and cost management to your AI applications by intercepting prompts and responses.
 
-[![npm version](https://badge.fury.io/js/ai-sdk-guardrails.svg)](https://www.npmjs.com/package/ai-sdk-guardrails)
-[![Downloads](https://img.shields.io/npm/dm/ai-sdk-guardrails.svg)](https://www.npmjs.com/package/ai-sdk-guardrails)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Block harmful inputs, filter low-quality outputs, and gain observability, all in just a few lines of code.
 
-## Why AI SDK Guardrails?
+![Guardrails Demo](./media/guardrail-example.gif)
 
-Building AI applications is exciting, but deploying them safely in production requires careful consideration. This library provides the safety net you need without sacrificing developer experience or performance.
+## ⚡ TL;DR
 
-### 🛡️ Complete Protection
+Quickly add input and output validation to any AI SDK-compatible model.
 
-Validate inputs before they reach your model and outputs before they reach users. Catch harmful content, PII, prompt injections, and more.
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+import {
+  wrapWithGuardrails,
+  defineInputGuardrail,
+  defineOutputGuardrail,
+} from 'ai-sdk-guardrails';
 
-### ⚡ Real-time Streaming Safety
+// 1. Define your guardrails
+const inputGuard = defineInputGuardrail({
+  name: 'length-check',
+  execute: async ({ prompt }) =>
+    prompt.length > 100
+      ? { tripwireTriggered: true, message: 'Input too long' }
+      : { tripwireTriggered: false },
+});
 
-The only guardrails library with true streaming support. Monitor and stop streams in real-time when safety violations occur.
+const outputGuard = defineOutputGuardrail({
+  name: 'quality-check',
+  execute: async ({ result }) =>
+    result.text.length < 10
+      ? { tripwireTriggered: true, message: 'Response too short' }
+      : { tripwireTriggered: false },
+});
 
-### 🎯 Built for Vercel AI SDK
+// 2. Wrap your model
+const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
+  inputGuardrails: [inputGuard],
+  outputGuardrails: [outputGuard],
+});
 
-First-class support for all AI SDK functions: `generateText`, `generateObject`, `streamText`, `streamObject`, and `embed`.
+// 3. Use it! Guardrails will run automatically.
+const { text } = await generateText({
+  model: guardedModel,
+  prompt: 'A prompt that is definitely not too long.',
+});
+```
 
-### 🔧 Developer Friendly
+## How It Works
 
-Simple API with TypeScript autocompletion, helpful error messages, and sensible defaults. Start safe in minutes, not hours.
+### Without Guardrails (Inefficient, Poor Quality)
 
-## How It Works
+```mermaid
+flowchart LR
+    A[User Input<br/>'hello'] --> B[AI Model] --> C[Response<br/>⚠️ Wastes resources<br/>😞 Often useless]
+```
+
+### With Input Guardrails (Save Resources)
 
 ```mermaid
-graph TB
-    A[User Input] --> B{Input Guardrails}
-    B -->|✅ Pass| C[AI Model]
-    B -->|❌ Block| D[GuardrailError]
-
-    C --> E[AI Response]
-    E --> F{Output Guardrails}
-    F -->|✅ Pass| G[Safe Response]
-    F -->|❌ Block| H[GuardrailError]
-
-    subgraph "Input Guardrails"
-        I1[Length Limit]
-        I2[Blocked Keywords]
-        I3[PII Detection]
-        I4[Prompt Injection]
-        I5[Rate Limiting]
-    end
+flowchart LR
+    A[User Input<br/>'hello'] --> B[Input Guardrails] --> C[❌ STOPPED<br/>✅ No API call made]
+```
 
-    subgraph "Output Guardrails"
-        O1[Quality Check]
-        O2[Toxicity Filter]
-        O3[Privacy Leakage]
-        O4[Schema Validation]
-        O5[Confidence Threshold]
-    end
+### With Output Guardrails (Ensure Quality)
 
-    B -.-> I1
-    B -.-> I2
-    B -.-> I3
-    B -.-> I4
-    B -.-> I5
-
-    F -.-> O1
-    F -.-> O2
-    F -.-> O3
-    F -.-> O4
-    F -.-> O5
-
-    classDef inputNode fill:#e1f5fe
-    classDef outputNode fill:#f3e5f5
-    classDef blockNode fill:#ffebee
-    classDef passNode fill:#e8f5e8
-
-    class I1,I2,I3,I4,I5 inputNode
-    class O1,O2,O3,O4,O5 outputNode
-    class D,H blockNode
-    class G passNode
+```mermaid
+flowchart LR
+    A[AI Response<br/>'Here's my SSN: 123-45-6789'] --> B[Output Guardrails] --> C[❌ BLOCKED<br/>🛡️ Privacy protected]
 ```
 
-## Installation
+### Complete Protection
 
-```bash
-npm install ai-sdk-guardrails
-# or
-pnpm add ai-sdk-guardrails
-# or
-yarn add ai-sdk-guardrails
+```mermaid
+flowchart LR
+    A[User Input] --> B[Input Guardrails] --> C[AI Model] --> D[Output Guardrails] --> E[Clean Response]
 ```
 
-## Quick Start
+That's it! Input guardrails optimize resource usage by stopping inefficient requests. Output guardrails ensure quality by filtering responses.
 
-Get started with production-ready guardrails in just a few lines:
+## 📦 Installation
 
-```typescript
-import { generateTextWithGuardrails } from 'ai-sdk-guardrails';
-import { blockedKeywords } from 'ai-sdk-guardrails/guardrails/input';
-import { outputLengthLimit } from 'ai-sdk-guardrails/guardrails/output';
-import { openai } from '@ai-sdk/openai';
+```bash
+npm install ai-sdk-guardrails
 
-const result = await generateTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Write a helpful response about web security',
-  },
-  {
-    inputGuardrails: [blockedKeywords(['hack', 'exploit', 'vulnerability'])],
-    outputGuardrails: [outputLengthLimit(500)],
-  },
-);
+# or
 
-console.log(result.text);
-```
+yarn add ai-sdk-guardrails
+
+# or
 
-## Core Concepts
+pnpm add ai-sdk-guardrails
+```
 
-### Input Guardrails
+## 🚀 Quick Start
 
-Input guardrails validate prompts before they reach your AI model. Use them to:
+Add smart validation to your AI applications in just 3 steps:
 
-- Block harmful or inappropriate content
-- Enforce length limits
-- Detect prompt injection attempts
-- Remove personally identifiable information (PII)
-- Implement rate limiting
+### 1. Prevent Unnecessary AI Calls
 
 ```typescript
-import { createInputGuardrail } from 'ai-sdk-guardrails';
-
-const mathHomeworkDetector = createInputGuardrail(
-  'math-homework-detector',
-  'Prevents direct homework solving requests',
-  (context) => {
-    const { prompt } = context;
-    const homeworkPatterns = [
-      /solve this equation/i,
-      /what is \d+ [\+\-\*\/] \d+/i,
-      /calculate the answer/i,
-    ];
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import {
+  wrapWithInputGuardrails,
+  defineInputGuardrail,
+} from 'ai-sdk-guardrails';
+import { extractTextContent } from 'ai-sdk-guardrails/guardrails/input';
 
-    const isHomework = homeworkPatterns.some((pattern) =>
-      pattern.test(prompt || ''),
+// Block inefficient requests before calling the AI model
+const lengthGuard = defineInputGuardrail({
+  name: 'blocked-keywords',
+  execute: async (context) => {
+    const { prompt } = extractTextContent(context);
+    const blockedWords = ['spam', 'test', 'hello'];
+
+    const foundWord = blockedWords.find((word) =>
+      prompt.toLowerCase().includes(word.toLowerCase()),
     );
 
-    return {
-      tripwireTriggered: isHomework,
-      message: isHomework ? 'Direct homework solving detected' : undefined,
-      suggestion: isHomework
-        ? 'Try asking about the concepts instead'
-        : undefined,
-    };
+    if (foundWord) {
+      return {
+        tripwireTriggered: true,
+        message: `Blocked keyword detected: ${foundWord}`,
+        severity: 'medium',
+      };
+    }
+
+    return { tripwireTriggered: false };
   },
-);
-```
+});
 
-### Output Guardrails
+const optimizedModel = wrapWithInputGuardrails(openai('gpt-4'), {
+  inputGuardrails: [lengthGuard],
+});
 
-Output guardrails validate AI responses before they reach users. Use them to:
+// This would normally waste an API call for a useless response
+try {
+  const result = await generateText({
+    model: optimizedModel,
+    prompt: 'hello', // ❌ Blocked - prevents unnecessary API call
+  });
+} catch (error) {
+  console.log('Blocked request, saved money!');
+}
+
+// This generates valuable content
+const goodResult = await generateText({
+  model: optimizedModel,
+  prompt: 'Write a product description for our new software', // ✅ This creates value
+});
+```
 
-- Ensure response quality
-- Block sensitive information
-- Enforce formatting requirements
-- Validate against schemas
-- Check confidence levels
+### 2. Ensure Quality Output
 
 ```typescript
-import { createOutputGuardrail } from 'ai-sdk-guardrails';
+import {
+  wrapWithOutputGuardrails,
+  defineOutputGuardrail,
+} from 'ai-sdk-guardrails';
+import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
+
+const qualityGuard = defineOutputGuardrail({
+  name: 'sensitive-info-detector',
+  execute: async (context) => {
+    const { text } = extractContent(context.result);
 
-const sensitiveInfoFilter = createOutputGuardrail(
-  'sensitive-info-filter',
-  (context) => {
-    const { text } = context.result;
+    // Simple sensitive info patterns
     const sensitivePatterns = [
-      /password:\s*\w+/i,
-      /api[_-]?key:\s*\w+/i,
-      /\b\d{3}-\d{2}-\d{4}\b/, // SSN format
+      /\b\d{3}-\d{2}-\d{4}\b/, // SSN
+      /\b[\w\.-]+@[\w\.-]+\.\w+\b/, // Email
+      /\b\d{3}-\d{3}-\d{4}\b/, // Phone
     ];
 
-    const hasSensitive = sensitivePatterns.some((pattern) =>
-      pattern.test(text || ''),
+    const foundPattern = sensitivePatterns.find((pattern) =>
+      pattern.test(text),
     );
 
-    return {
-      tripwireTriggered: hasSensitive,
-      message: hasSensitive
-        ? 'Response contains sensitive information'
-        : undefined,
-      severity: hasSensitive ? 'critical' : 'low',
-    };
+    if (foundPattern) {
+      return {
+        tripwireTriggered: true,
+        message: 'Sensitive information detected in response',
+        severity: 'high',
+      };
+    }
+
+    return { tripwireTriggered: false };
   },
-);
-```
+});
 
-### Streaming Guardrails
+const qualityModel = wrapWithOutputGuardrails(openai('gpt-4'), {
+  outputGuardrails: [qualityGuard],
+  onOutputBlocked: (results) => {
+    console.log('Prevented sensitive data leak:', results[0]?.message);
+  },
+});
+
+const result = await generateText({
+  model: qualityModel,
+  prompt: 'Create a user profile example',
+});
+// Automatically blocks responses containing emails, phone numbers, or SSNs
+```
 
-Protect streaming responses in real-time. The stream automatically stops if guardrails detect violations:
+### 3. Custom Business Logic
 
 ```typescript
-import { streamTextWithGuardrails } from 'ai-sdk-guardrails';
-
-const stream = await streamTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Generate a long story...',
-  },
-  {
-    outputGuardrails: [
-      outputLengthLimit(1000),
-      blockedOutputContent(['inappropriate', 'offensive']),
-    ],
-    onOutputBlocked: (error) => {
-      console.error('Stream blocked:', error.reason);
-    },
+const businessHoursGuard = defineInputGuardrail({
+  name: 'business-hours-only',
+  execute: async () => {
+    const hour = new Date().getUTCHours();
+    // Only allow requests between 9 AM and 5 PM UTC
+    if (hour < 9 || hour > 17) {
+      return {
+        tripwireTriggered: true,
+        message:
+          'Requests are only permitted during business hours (9:00-17:00 UTC).',
+        severity: 'low',
+      };
+    }
+    return { tripwireTriggered: false };
   },
-);
+});
 
-// The stream will automatically stop if guardrails trigger
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
+const smartEducationModel = wrapWithInputGuardrails(openai('gpt-4'), {
+  inputGuardrails: [businessHoursGuard],
+});
 ```
 
-## Built-in Guardrails
+**That's it!** Your AI application now optimizes resource usage, ensures quality, and prevents inappropriate responses automatically.
 
-### Input Guardrails
+## ✨ Features
 
-```typescript
-import {
-  lengthLimit,
-  blockedWords,
-  blockedKeywords,
-  profanityFilter,
-  promptInjectionDetector,
-  piiDetector,
-  toxicityDetector,
-  mathHomeworkDetector,
-  codeGenerationLimiter,
-} from 'ai-sdk-guardrails/guardrails/input';
-
-// Content filters
-const contentGuardrails = [
-  lengthLimit(1000),
-  blockedWords(['spam', 'hack']),
-  profanityFilter(['custom', 'words']),
-  toxicityDetector(0.7), // threshold
-];
-
-// Security guardrails
-const securityGuardrails = [promptInjectionDetector(), piiDetector()];
-
-// Educational guardrails
-const educationGuardrails = [
-  mathHomeworkDetector(),
-  codeGenerationLimiter(['javascript', 'python']),
-];
-```
+- 🛡️ **Input & Output Guardrails**: Enforce custom safety, compliance, and quality policies on both prompts and LLM responses.
+- 💰 **Cost Control**: Block invalid or wasteful prompts before they are sent to your LLM provider, saving you money.
+- 🎯 **Quality Improvement**: Automatically filter, flag, or retry low-quality or irrelevant model outputs.
+- 🔄 **Streaming Support**: Works seamlessly with both streaming (streamText) and standard (generateText) API responses.
+- 📊 **Observability Hooks**: Built-in callbacks (onInputBlocked, onOutputBlocked, etc.) for logging and monitoring.
+- ⚙️ **Configurable Execution**: Run guardrails in parallel or sequentially and set custom timeouts.
+- 🚀 **AI SDK Native**: Designed from the ground up to integrate cleanly with AI SDK middleware patterns.
 
-### Output Guardrails
+## 📚 API Overview
 
-```typescript
-import {
-  lengthLimit,
-  blockedContent,
-  jsonValidation,
-  confidenceThreshold,
-  toxicityFilter,
-  schemaValidation,
-  tokenUsageLimit,
-  performanceMonitor,
-  hallucinationDetector,
-  biasDetector,
-  factualAccuracyChecker,
-  privacyLeakageDetector,
-  contentConsistencyChecker,
-  complianceChecker,
-} from 'ai-sdk-guardrails/guardrails/output';
-
-// Quality guardrails
-const qualityGuardrails = [
-  lengthLimit(500),
-  confidenceThreshold(0.8),
-  hallucinationDetector(0.7),
-  factualAccuracyChecker(true), // require sources
-];
-
-// Safety guardrails
-const safetyGuardrails = [
-  toxicityFilter(0.5),
-  biasDetector(),
-  privacyLeakageDetector(),
-  complianceChecker(['GDPR', 'HIPAA']),
-];
-
-// Performance guardrails
-const performanceGuardrails = [
-  tokenUsageLimit(1000),
-  performanceMonitor(5000), // max 5 seconds
-];
-```
+| Function                     | Description                                                                   |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `defineInputGuardrail()`     | Creates a guardrail to validate, inspect, or block prompts.                   |
+| `defineOutputGuardrail()`    | Creates a guardrail to validate, filter, or re-route LLM outputs.             |
+| `wrapWithGuardrails()`       | ⭐ **Recommended** - The easiest way to add both input and output guardrails. |
+| `wrapWithInputGuardrails()`  | Attaches input-only guardrails to a model.                                    |
+| `wrapWithOutputGuardrails()` | Attaches output-only guardrails to a model.                                   |
+| `InputBlockedError`, etc.    | Custom, structured error types for easy try/catch handling.                   |
 
-## Integration with Autoevals
+## 🧠 Design Philosophy
 
-Use [Autoevals](https://github.com/braintrust-data/autoevals) for sophisticated AI quality evaluation as guardrails:
+- ✅ **Helper-First**: Simple, chainable utility functions provide a great developer experience for fast adoption.
+- 🧩 **Composable**: Multiple guardrails can be chained together and will run in your specified order (or in parallel).
+- 🧾 **Type-Safe**: Full TypeScript support with contextual typing for guardrail inputs, outputs, and metadata.
+- 🧪 **Sensible Defaults**: Get started quickly with zero-config default behaviors that can be easily overridden.
 
-```typescript
-import { Factuality, init } from 'autoevals';
-import { createOutputGuardrail } from 'ai-sdk-guardrails';
-
-function createFactualityGuardrail({
-  expected,
-  minScore,
-}: {
-  expected: string;
-  minScore: number;
-}) {
-  return createOutputGuardrail('factuality-check', async (context) => {
-    const { text } = extractContent(context.result);
-    const { prompt } = extractTextContent(context.input);
+## Architecture Overview
 
-    const evalResult = await Factuality({
-      output: text,
-      expected,
-      input: prompt || '',
-      model: MODEL_NAME,
-    });
+The library leverages the Vercel AI SDK's middleware architecture to provide composable guardrails that integrate seamlessly with your existing AI applications:
 
-    const isFactual = (evalResult.score || 0) >= minScore;
-
-    return {
-      tripwireTriggered: !isFactual,
-      message: isFactual
-        ? `Factual content (score: ${evalResult.score})`
-        : `Factual accuracy too low (score: ${evalResult.score}, required: ${minScore})`,
-      severity: isFactual ? 'low' : 'high',
-      metadata: {
-        factualityScore: evalResult.score,
-        rationale: evalResult.metadata?.rationale,
-        expected,
-        minScore,
-      },
-      suggestion: isFactual
-        ? undefined
-        : 'Please provide more accurate information',
-    };
-  });
-}
+```mermaid
+graph TB
+    subgraph "Your Application"
+        App[Your App Code]
+        Config[Guardrail Configuration]
+    end
 
-// Usage
-const result = await generateTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Which country has the highest population?',
-  },
-  {
-    outputGuardrails: [
-      createFactualityGuardrail({
-        expected: 'China',
-        minScore: 0.7,
-      }),
-    ],
-  },
-);
+    subgraph "AI SDK Guardrails Middleware"
+        InputMW[Input Guardrails Middleware]
+        OutputMW[Output Guardrails Middleware]
+
+        subgraph "Input Guardrails Layer"
+            Length[Length Validation]
+            Spam[Spam Detection]
+            PII[PII Detection]
+            Business[Business Rules]
+            Custom1[Custom Guards]
+        end
+
+        subgraph "Output Guardrails Layer"
+            Quality[Quality Assurance]
+            Sensitive[Sensitive Info Filter]
+            Professional[Professional Tone]
+            Factual[Factual Validation]
+            Custom2[Custom Guards]
+        end
+    end
+
+    subgraph "AI SDK Core"
+        Wrapper[wrapLanguageModel]
+        Generator[generateText/Object/Stream]
+    end
+
+    subgraph "External Services"
+        AI[AI Model Provider]
+        Log[Logging & Telemetry]
+    end
+
+    App --> Config
+    Config --> InputMW
+    InputMW --> Length
+    InputMW --> Spam
+    InputMW --> PII
+    InputMW --> Business
+    InputMW --> Custom1
+
+    InputMW -->|Valid Request| Wrapper
+    InputMW -->|Blocked Request| Log
+
+    Wrapper --> Generator
+    Generator --> AI
+    AI --> OutputMW
+
+    OutputMW --> Quality
+    OutputMW --> Sensitive
+    OutputMW --> Professional
+    OutputMW --> Factual
+    OutputMW --> Custom2
+
+    OutputMW -->|Clean Response| App
+    OutputMW -->|Quality Issues| Log
+
+    style InputMW fill:#e1f5fe
+    style OutputMW fill:#f3e5f5
+    style AI fill:#fff3e0
+    style App fill:#e8f5e8
 ```
 
-## Error Handling
+## 🍳 Recipes & Use Cases
 
-Guardrails provide rich error information to help you handle violations gracefully:
+Guardrails can enforce any custom logic. Here are a few common patterns.
 
-```typescript
-import { GuardrailError } from 'ai-sdk-guardrails';
+### Rate Limiting
 
-try {
-  const result = await generateTextWithGuardrails(params, guardrails);
-} catch (error) {
-  if (error instanceof GuardrailError) {
-    // Access detailed error information
-    console.log('Guardrail triggered:', error.guardrailName);
-    console.log('Reason:', error.reason);
-    console.log('Type:', error.type); // 'input' or 'output'
-
-    // Get all issues
-    error.issues.forEach((issue) => {
-      console.log(`${issue.guardrail}: ${issue.message}`);
-      console.log('Severity:', issue.severity);
-      console.log('Suggestion:', issue.suggestion);
-    });
+Pass a userId in the metadata of your generateText call to enforce per-user rate limits.
 
-    // Use helper methods
-    const summary = error.getSummary();
-    console.log(`Total issues: ${summary.totalIssues}`);
-    console.log(
-      `Guardrails triggered: ${summary.guardrailsTriggered.join(', ')}`,
-    );
-  }
-}
+```typescript
+const rateLimitGuard = defineInputGuardrail({
+  name: 'user-rate-limit',
+  execute: async ({ metadata }) => {
+    const userId = metadata?.userId ?? 'anonymous';
+    const allowed = await checkRateLimit(userId); // Your rate-limiting logic
+
+    return allowed
+      ? { tripwireTriggered: false }
+      : {
+          tripwireTriggered: true,
+          message: `Rate limit exceeded for user: ${userId}`,
+        };
+  },
+});
 ```
 
-## Advanced Usage
-
-### Custom Validation Logic
+### LLM-as-Judge for Quality Scoring
 
-Create sophisticated guardrails for your specific needs:
+Use a cheaper, faster model to "judge" the output of a more powerful one.
 
 ```typescript
-const businessLogicGuardrail = createInputGuardrail(
-  'business-logic-validator',
-  'Ensures requests meet business requirements',
-  async (context) => {
-    const { prompt, messages } = context;
-
-    // Implement your custom logic
-    const validationResult = await validateBusinessRules({
-      content: prompt,
-      history: messages,
+const qualityJudge = defineOutputGuardrail({
+  name: 'llm-quality-judge',
+  execute: async ({ result }) => {
+    // Use a cheap model to score the primary model's output
+    const judgement = await generateText({
+      model: openai('gpt-3.5-turbo'),
+      prompt: `Is the following response helpful and safe? Answer YES or NO. \n\nResponse: "${result.text}"`,
     });
 
-    return {
-      tripwireTriggered: !validationResult.isValid,
-      message: validationResult.error,
-      metadata: validationResult.details,
-      severity: validationResult.severity,
-      suggestion: validationResult.suggestion,
-    };
+    const isSafe = judgement.text.includes('YES');
+    return isSafe
+      ? { tripwireTriggered: false }
+      : {
+          tripwireTriggered: true,
+          message: `Output failed LLM-as-judge quality check.`,
+          metadata: { originalText: result.text },
+        };
   },
-);
+});
 ```
 
-### Composing Guardrails
-
-Combine multiple guardrail configurations for different scenarios:
+### Advanced Input Validation
 
 ```typescript
-// Development guardrails (more lenient)
-const devGuardrails = {
-  inputGuardrails: [lengthLimit(2000)],
-  throwOnBlocked: false,
-  onInputBlocked: (error) => console.warn('Dev warning:', error),
-};
-
-// Production guardrails (strict)
-const prodGuardrails = {
-  inputGuardrails: [lengthLimit(500), blockedKeywords(['test', 'debug'])],
-  outputGuardrails: [confidenceThreshold(0.9), complianceChecker(['GDPR'])],
-  throwOnBlocked: true,
-};
-
-// Use based on environment
-const guardrails =
-  process.env.NODE_ENV === 'production' ? prodGuardrails : devGuardrails;
-```
+import { extractTextContent } from 'ai-sdk-guardrails/guardrails/input';
 
-### Object Generation with Schema Validation
+const comprehensiveInputGuard = defineInputGuardrail({
+  name: 'comprehensive-input-validation',
+  execute: async (context) => {
+    const { prompt } = extractTextContent(context);
 
-Validate structured outputs with custom business logic:
+    // Length validation
+    if (prompt.length < 10) {
+      return {
+        tripwireTriggered: true,
+        message: 'Input too short - likely to produce low-value response',
+        severity: 'medium',
+        suggestion: 'Please provide more detailed input for better results',
+      };
+    }
 
-```typescript
-import { z } from 'zod';
+    if (prompt.length > 4000) {
+      return {
+        tripwireTriggered: true,
+        message: 'Input too long - may exceed token limits',
+        severity: 'high',
+        suggestion: 'Break your request into smaller, focused parts',
+      };
+    }
 
-const userSchema = z.object({
-  name: z.string(),
-  age: z.number().min(0).max(120),
-  email: z.string().email(),
-});
+    // Content quality checks
+    const spamPatterns = [
+      /^(.)\1{10,}$/, // Repeated characters
+      /^(test|hello|hi|hey)$/i, // Common spam words
+    ];
 
-const schemaValidator = createOutputGuardrail(
-  'schema-validator',
-  async (context) => {
-    const { object } = extractContent(context.result);
-    try {
-      userSchema.parse(object);
-      return { tripwireTriggered: false };
-    } catch (error) {
+    const foundSpam = spamPatterns.find((pattern) => pattern.test(prompt));
+    if (foundSpam) {
       return {
         tripwireTriggered: true,
-        message: 'Schema validation failed',
+        message: 'Low-quality input detected',
         severity: 'high',
-        metadata: { validationError: error.message },
       };
     }
-  },
-);
 
-const result = await generateObjectWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Create a user profile for John Doe, age 30',
-    schema: userSchema,
-  },
-  {
-    outputGuardrails: [schemaValidator],
+    return { tripwireTriggered: false };
   },
-);
-```
-
-## Best Practices
-
-### 1. Layer Your Defence
-
-Use multiple guardrails for comprehensive protection:
-
-```typescript
-const guardrails = {
-  inputGuardrails: [
-    // First line: Block obvious threats
-    promptInjectionDetector(),
-    blockedKeywords(['malicious', 'exploit']),
-
-    // Second line: Quality control
-    lengthLimit(1000),
-
-    // Third line: Business logic
-    customBusinessRules(),
-  ],
-  outputGuardrails: [
-    // Ensure quality
-    confidenceThreshold(0.7),
-
-    // Ensure safety
-    toxicityFilter(),
-    privacyLeakageDetector(),
-  ],
-};
+});
 ```
 
-### 2. Handle Errors Gracefully
-
-Provide helpful feedback when guardrails trigger:
+### Professional Output Quality Control
 
 ```typescript
-onInputBlocked: (error) => {
-  // Map technical errors to user-friendly messages
-  const userMessage =
-    {
-      'content-length-limit': 'Your message is too long. Please shorten it.',
-      'blocked-keywords': 'Your request contains restricted content.',
-      'pii-detector': 'Please remove personal information from your request.',
-    }[error.guardrailName] || 'Your request could not be processed.';
-
-  return userMessage;
-};
-```
-
-### 3. **Publishing Process (Using Changesets)**
+import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
 
-You're already set up with **Changesets** which is the recommended approach. Here's the process:
-
-#### **Step 1: Create a Changeset**
-
-```bash
-npx changeset
-```
-
-This will:
+const professionalQualityGuard = defineOutputGuardrail({
+  name: 'professional-quality-control',
+  execute: async (context) => {
+    const { text } = extractContent(context.result);
 
-- Ask you what type of change (patch/minor/major)
-- Let you write a summary of changes
-- Create a changeset file
+    const qualityIssues = [];
 
-#### **Step 2: Version and Publish**
+    // Check for unprofessional language
+    const unprofessionalTerms = ['lol', 'wtf', 'omg', 'ur', 'u r'];
+    const hasUnprofessional = unprofessionalTerms.some((term) =>
+      text.toLowerCase().includes(term),
+    );
 
-You have two options:
+    if (hasUnprofessional) {
+      qualityIssues.push('Contains unprofessional language');
+    }
 
-**Option A: Manual Control**
+    // Check for placeholder text
+    const placeholders = ['[insert', '[add', '[your', 'TODO:', 'FIXME:'];
+    const hasPlaceholders = placeholders.some((placeholder) =>
+      text.includes(placeholder),
+    );
 
-```bash
-# 1. Run CI to ensure everything passes
-npm run ci
+    if (hasPlaceholders) {
+      qualityIssues.push('Contains placeholder text - incomplete response');
+    }
 
-# 2. Version the package (reads changesets and updates version)
-npx changeset version
+    // Check for excessive repetition
+    const sentences = text.split(/[.!?]+/).filter((s) => s.trim());
+    const uniqueSentences = new Set(
+      sentences.map((s) => s.trim().toLowerCase()),
+    );
+    const repetitionRatio = uniqueSentences.size / sentences.length;
 
-# 3. Publish to npm
-npx changeset publish
-```
+    if (sentences.length > 3 && repetitionRatio < 0.6) {
+      qualityIssues.push('Excessive repetition detected');
+    }
 
-**Option B: Use Your Local Release Script**
+    if (qualityIssues.length > 0) {
+      return {
+        tripwireTriggered: true,
+        message: `Quality issues found: ${qualityIssues.join(', ')}`,
+        severity: 'medium',
+        suggestion: 'Request a more professional, complete response',
+        metadata: {
+          issues: qualityIssues,
+          quality_score: repetitionRatio,
+        },
+      };
+    }
 
-```bash
-npm run local-release
+    return { tripwireTriggered: false };
+  },
+});
 ```
 
-This runs: `npm run ci && changeset version && changeset publish`
-
-### 4. **First Release Steps**
+## 🔄 Streaming Support
 
-For your first release, I recommend:
+Guardrails work with streams out-of-the-box. Output guardrails will run after the complete response has been streamed and generated.
 
-1. **Fix any remaining issues** (like the prettier formatting):
-
-```bash
-npm run format
-```
-
-2. **Create your first changeset**:
+```typescript
+import { streamText } from 'ai';
 
-```bash
-npx changeset
-```
+const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
+  outputGuardrails: [qualityJudge],
+});
 
-- Select "major" (since this is 0.0.1 → 1.0.0)
-- Write: "Initial release of AI SDK Guardrails"
+const { textStream } = await streamText({
+  model: guardedModel,
+  prompt: 'Tell me a short story about a robot.',
+});
 
-3. **Release it**:
+// Stream the response to the client
+for await (const delta of textStream) {
+  process.stdout.write(delta);
+}
 
-```bash
-npm run local-release
+// The qualityJudge guardrail will run after the stream is complete.
 ```
 
-### 5. **Package Name Assessment**
-
-**✅ `ai-sdk-guardrails` is excellent because:**
-
-- Available on npm
-- Descriptive and searchable
-- Follows naming conventions
-- Clearly indicates it's for AI SDK
-- Professional sounding
+## 🛠️ Error Handling
 
-### 6. **Additional Recommendations**
+When `throwOnBlocked: true` (the default), you can catch structured errors to handle blocks gracefully.
 
-Consider these npm badges for your README:
+```typescript
+import { generateText } from 'ai';
+import { isGuardrailsError } from 'ai-sdk-guardrails';
 
-```markdown
-<code_block_to_apply_changes_from>
-[![npm version](https://badge.fury.io/js/ai-sdk-guardrails.svg)](https://www.npmjs.com/package/ai-sdk-guardrails)
-[![Downloads](https://img.shields.io/npm/dm/ai-sdk-guardrails.svg)](https://www.npmjs.com/package/ai-sdk-guardrails)
+try {
+  const result = await generateText({
+    model: guardedModel,
+    prompt: 'A prompt that might be blocked...',
+  });
+} catch (error) {
+  if (isGuardrailsError(error)) {
+    // Error was thrown by one of our guardrails
+    console.error('Guardrail check failed:', error.message);
+    console.error('Triggered Guards:', error.results);
+  } else {
+    // Some other error occurred
+    console.error('An unexpected error occurred:', error);
+  }
+}
 ```
 
-### 7. **GitHub Release Integration**
-
-After publishing to npm, you might want to:
+### User-Friendly Error Messages
 
-- Create GitHub releases that match your npm versions
-- Set up GitHub Actions for automated publishing (optional)
+Transform technical guardrail messages into user-friendly guidance:
 
-**Would you like me to help you run through the first release process now?**
+```typescript
+function createUserFriendlyMessage(guardrailResult): string {
+  const guardrailName = guardrailResult.context?.guardrailName;
 
-## All AI SDK Functions Supported
+  switch (guardrailName) {
+    case 'content-length-limit':
+      return 'Your message is too long. Please keep it under 500 characters for the best response.';
 
-The library provides guarded versions of all AI SDK functions:
+    case 'blocked-keywords':
+      return "I can't help with that topic. Try asking about something else I can assist with.";
 
-```typescript
-import {
-  generateTextWithGuardrails,
-  generateObjectWithGuardrails,
-  streamTextWithGuardrails,
-  streamObjectWithGuardrails,
-  embedWithGuardrails,
-} from 'ai-sdk-guardrails';
+    case 'user-rate-limit':
+      return "You're sending requests too quickly. Please wait a moment before trying again.";
 
-// Generate text with guardrails
-const textResult = await generateTextWithGuardrails(
-  { model, prompt: 'Hello' },
-  { inputGuardrails: [lengthLimit(100)] },
-);
-
-// Generate structured objects with guardrails
-const objectResult = await generateObjectWithGuardrails(
-  { model, prompt: 'Create user', schema: userSchema },
-  { outputGuardrails: [schemaValidation(userSchema)] },
-);
-
-// Stream text with real-time guardrails
-const textStream = await streamTextWithGuardrails(
-  { model, prompt: 'Long response' },
-  { outputGuardrails: [outputLengthLimit(1000)] },
-);
-
-// Stream objects with guardrails
-const objectStream = await streamObjectWithGuardrails(
-  { model, prompt: 'Stream data', schema: dataSchema },
-  { outputGuardrails: [schemaValidation(dataSchema)] },
-);
-
-// Embed with input validation
-const embedResult = await embedWithGuardrails(
-  { model, value: 'Text to embed' },
-  { inputGuardrails: [piiDetector()] },
-);
+    default:
+      return (
+        guardrailResult.suggestion ||
+        'Please refine your request and try again.'
+      );
+  }
+}
 ```
 
-## TypeScript Support
+## Complete AI SDK Integration
 
-Full TypeScript support with intelligent type inference:
+The library seamlessly integrates with all AI SDK functions:
 
 ```typescript
-// Types are automatically inferred
-const result = await generateTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Hello',
+// Create your production-ready model once
+const productionModel = wrapWithGuardrails(openai('gpt-4'), {
+  inputGuardrails: [lengthGuard, spamGuard, rateLimitGuard],
+  outputGuardrails: [qualityGuard, sensitiveInfoGuard],
+  throwOnBlocked: false,
+  onInputBlocked: (results) => {
+    console.log('Input blocked:', results[0]?.message);
   },
-  {
-    inputGuardrails: [
-      /* your guardrails */
-    ],
+  onOutputBlocked: (results) => {
+    console.log('Output filtered:', results[0]?.message);
   },
-);
+});
+
+// Use with any AI SDK function
+const textResult = await generateText({
+  model: productionModel,
+  prompt: 'Write a professional email response',
+});
+
+const objectResult = await generateObject({
+  model: productionModel,
+  prompt: 'Create a user profile',
+  schema: userProfileSchema,
+});
 
-// result is fully typed as GenerateTextResult
-console.log(result.text);
-console.log(result.usage);
-console.log(result.finishReason);
+const textStream = await streamText({
+  model: productionModel,
+  prompt: 'Explain our product features',
+});
 ```
 
 ## Examples
 
-Explore our comprehensive examples that demonstrate real-world usage patterns:
+Explore focused examples that demonstrate practical performance optimization and quality assurance:
+
+### Core Examples
+
+- **[Basic Composition](examples/basic-composition.ts)** - Simple input/output validation for efficiency and quality
+- **[Basic Guardrails](examples/basic-guardrails.ts)** - Foundation patterns for input/output validation
+- **[Business Logic](examples/business-logic.ts)** - Custom business rules, work hours, and professional standards
+- **[LLM-as-Judge](examples/llm-as-judge.ts)** - AI-powered quality evaluation and scoring
 
-- **[Basic Guardrails](examples/basic-guardrails.ts)** - Simple input/output validation with math homework detection
-- **[Streaming Guardrails](examples/streaming-guardrails.ts)** - Real-time stream protection with content filtering
-- **[Object Guardrails](examples/object-guardrails.ts)** - Schema validation and custom object validation
-- **[Autoevals Integration](examples/autoevals-guardrails.ts)** - AI quality evaluation with factuality checking
-- **[Kitchen Sink](examples/kitchen-sink.ts)** - Advanced patterns, composition, and LLM-as-judge
+### Additional Examples
 
-Each example is fully functional and demonstrates different aspects of the library with practical use cases.
+- **[Object Guardrails](examples/object-guardrails.ts)** - Schema validation and structured output quality
+- **[Streaming Guardrails](examples/streaming-guardrails.ts)** - Real-time quality monitoring
+- **[Rate Limiting](examples/rate-limit-guardrail.ts)** - Smart rate limiting that prevents resource overuse
+- **[Autoevals Integration](examples/autoevals-guardrails.ts)** - Advanced AI-powered evaluation
 
-## Contributing
+### Running Examples
+
+```bash
+# Install dependencies
+pnpm install
+
+# Interactive examples with better UX
+tsx examples/basic-composition.ts     # Start here - simplest example
+tsx examples/basic-guardrails.ts      # Core patterns with 8 examples
+tsx examples/business-logic.ts        # Business-specific rules
+tsx examples/llm-as-judge.ts          # AI-powered quality control
+
+# Or run specific examples directly
+tsx examples/basic-guardrails.ts 1    # Run first example only
+tsx examples/streaming-guardrails.ts 3 # Run third streaming example
+```
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+All examples feature interactive menus with arrow key navigation, multi-selection with checkboxes, and automatic return to the main menu.
 
-## License
+## 🤝 Contributing
 
-MIT © [Jag Reehal](https://github.com/jagreehal)
+Contributions of all sizes are welcome! Please open issues and pull requests on [GitHub](https://github.com/jagreehal/ai-sdk-guardrails).
 
----
+## 📄 License
 
-Built with ❤️ for the AI community. Star the repo if you find it helpful!
+MIT © [Jag Reehal](https://github.com/jagreehal) – See LICENSE for full details.