ai-sdk-guardrails 2.0.0 → 3.0.0

package/README.md

@@ -1,41 +1,53 @@
 # AI SDK Guardrails
 
-Stop unnecessary AI calls. Optimize performance, improve quality, and prevent inappropriate AI responses with intelligent middleware for the Vercel AI SDK.
+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.
 
-## Requirements
+![Guardrails Demo](./media/guardrail-example.gif)
 
-This library requires the Vercel AI SDK (v5 and above) for its composable middleware architecture:
+## ⚡ TL;DR
 
-```bash
-pnpm add ai@latest ai-sdk-guardrails
-```
-
-## Why Use AI SDK Guardrails?
-
-Every AI call consumes resources and carries risk. One inappropriate response can damage your reputation whilst inefficient requests waste valuable API resources. AI SDK Guardrails helps you:
-
-![Guardrails](./media/guardrail-example.gif)
-
-### ⚡ **Optimize API Usage**
+Quickly add input and output validation to any AI SDK-compatible model.
 
-Block inefficient requests before they reach your AI model. Validate inputs, enforce length limits, detect spam, and prevent unnecessary calls that would have failed anyway.
-
-### 🎯 **Improve Response Quality**
-
-Ensure every AI response meets your standards. Filter out hallucinations, check factuality, enforce formatting requirements, and maintain consistent quality across your application.
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+import {
+  wrapWithGuardrails,
+  defineInputGuardrail,
+  defineOutputGuardrail,
+} from 'ai-sdk-guardrails';
 
-### 🛡️ **Prevent Embarrassing Responses**
+// 1. Define your guardrails
+const inputGuard = defineInputGuardrail({
+  name: 'length-check',
+  execute: async ({ prompt }) =>
+    prompt.length > 100
+      ? { tripwireTriggered: true, message: 'Input too long' }
+      : { tripwireTriggered: false },
+});
 
-Stop your AI from saying things you'll regret. Block inappropriate content, filter sensitive information, detect bias, and maintain professional standards in all interactions.
+const outputGuard = defineOutputGuardrail({
+  name: 'quality-check',
+  execute: async ({ result }) =>
+    result.text.length < 10
+      ? { tripwireTriggered: true, message: 'Response too short' }
+      : { tripwireTriggered: false },
+});
 
-### ⚡ **Focus AI Generations**
+// 2. Wrap your model
+const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
+  inputGuardrails: [inputGuard],
+  outputGuardrails: [outputGuard],
+});
 
-Guide your AI to stay on topic and provide useful responses. Prevent prompt injection, enforce business policies, and ensure responses align with your application's purpose.
+// 3. Use it! Guardrails will run automatically.
+const { text } = await generateText({
+  model: guardedModel,
+  prompt: 'A prompt that is definitely not too long.',
+});
+```
 
 ## How It Works
 
@@ -69,44 +81,71 @@ flowchart LR
 
 That's it! Input guardrails optimize resource usage by stopping inefficient requests. Output guardrails ensure quality by filtering responses.
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install ai-sdk-guardrails
+
 # or
-pnpm add ai-sdk-guardrails
-# or
+
 yarn add ai-sdk-guardrails
+
+# or
+
+pnpm add ai-sdk-guardrails
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 Add smart validation to your AI applications in just 3 steps:
 
 ### 1. Prevent Unnecessary AI Calls
 
 ```typescript
-import { generateText, wrapLanguageModel } from 'ai';
+import { generateText } from 'ai';
 import { openai } from '@ai-sdk/openai';
-import { createInputGuardrailsMiddleware } from 'ai-sdk-guardrails';
-import { blockedKeywords } from 'ai-sdk-guardrails/guardrails/input';
+import {
+  wrapWithInputGuardrails,
+  defineInputGuardrail,
+} from 'ai-sdk-guardrails';
+import { extractTextContent } from 'ai-sdk-guardrails/guardrails/input';
 
 // Block inefficient requests before calling the AI model
-const optimizedModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createInputGuardrailsMiddleware({
-      inputGuardrails: [blockedKeywords(['spam', 'test', 'hello'])],
-    }),
-  ],
+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()),
+    );
+
+    if (foundWord) {
+      return {
+        tripwireTriggered: true,
+        message: `Blocked keyword detected: ${foundWord}`,
+        severity: 'medium',
+      };
+    }
+
+    return { tripwireTriggered: false };
+  },
 });
 
-// This would normally waste an API call for a useless response
-const result = await generateText({
-  model: optimizedModel,
-  prompt: 'hello', // ❌ Blocked - prevents unnecessary API call
+const optimizedModel = wrapWithInputGuardrails(openai('gpt-4'), {
+  inputGuardrails: [lengthGuard],
 });
-// → Throws GuardrailError: "Blocked keyword detected: hello"
+
+// 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({
@@ -118,25 +157,45 @@ const goodResult = await generateText({
 ### 2. Ensure Quality Output
 
 ```typescript
-import { createOutputGuardrailsMiddleware } from 'ai-sdk-guardrails';
-import { sensitiveInfoDetector } from 'ai-sdk-guardrails/guardrails/output';
-
-const qualityModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    // Optimize by filtering inefficient inputs
-    createInputGuardrailsMiddleware({
-      inputGuardrails: [blockedKeywords(['spam', 'test'])],
-    }),
-
-    // Ensure quality outputs
-    createOutputGuardrailsMiddleware({
-      outputGuardrails: [sensitiveInfoDetector()], // Prevents data leaks
-      onOutputBlocked: (results) => {
-        console.log('Prevented embarrassing response:', results[0]?.message);
-      },
-    }),
-  ],
+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);
+
+    // Simple sensitive info patterns
+    const sensitivePatterns = [
+      /\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 foundPattern = sensitivePatterns.find((pattern) =>
+      pattern.test(text),
+    );
+
+    if (foundPattern) {
+      return {
+        tripwireTriggered: true,
+        message: 'Sensitive information detected in response',
+        severity: 'high',
+      };
+    }
+
+    return { tripwireTriggered: false };
+  },
+});
+
+const qualityModel = wrapWithOutputGuardrails(openai('gpt-4'), {
+  outputGuardrails: [qualityGuard],
+  onOutputBlocked: (results) => {
+    console.log('Prevented sensitive data leak:', results[0]?.message);
+  },
 });
 
 const result = await generateText({
@@ -144,388 +203,227 @@ const result = await generateText({
   prompt: 'Create a user profile example',
 });
 // Automatically blocks responses containing emails, phone numbers, or SSNs
-// Prevents: "Here's a profile: john.doe@email.com, (555) 123-4567, SSN: 123-45-6789"
-// Returns: "Here's a profile: [contact information], [phone number], [SSN removed]"
 ```
 
 ### 3. Custom Business Logic
 
 ```typescript
-import { defineInputGuardrail } from 'ai-sdk-guardrails';
-import { extractTextContent } from 'ai-sdk-guardrails/guardrails/input';
-
-// Prevent inefficient homework help requests
-const homeworkDetector = defineInputGuardrail({
-  name: 'homework-detector',
-  execute: async (context) => {
-    const { prompt } = extractTextContent(context);
-
-    if (prompt.includes('solve this equation') || prompt.includes('homework')) {
+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: 'Homework help blocked - prevents inefficient API usage',
-        suggestion: 'Ask about learning concepts instead',
+        message:
+          'Requests are only permitted during business hours (9:00-17:00 UTC).',
+        severity: 'low',
       };
     }
-
     return { tripwireTriggered: false };
   },
 });
 
-const smartEducationModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createInputGuardrailsMiddleware({
-      inputGuardrails: [homeworkDetector],
-    }),
-  ],
+const smartEducationModel = wrapWithInputGuardrails(openai('gpt-4'), {
+  inputGuardrails: [businessHoursGuard],
 });
 ```
 
 **That's it!** Your AI application now optimizes resource usage, ensures quality, and prevents inappropriate responses automatically.
 
-### Smart API Optimization Strategy
+## ✨ Features
 
-Build intelligent resource management by combining multiple validation layers:
+- 🛡️ **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.
 
-```typescript
-// Layer 1: Immediate optimization - block inefficient requests
-const optimizationLayer = [
-  defineInputGuardrail({
-    name: 'length-validator',
-    description: 'Prevents expensive long requests that often fail',
-    execute: async (params) => {
-      const { prompt } = extractTextContent(params);
-      if (typeof prompt === 'string') {
-        // Block extremely short requests that waste resources
-        if (prompt.trim().length < 10) {
-          return {
-            tripwireTriggered: true,
-            message: 'Request too short - inefficient API usage',
-            severity: 'medium',
-          };
-        }
-        // Block extremely long requests that often hit limits anyway
-        if (prompt.length > 8000) {
-          return {
-            tripwireTriggered: true,
-            message: 'Request too long - would likely hit token limits',
-            severity: 'medium',
-            suggestion: 'Break into smaller, focused requests',
-          };
-        }
-      }
-      return { tripwireTriggered: false };
-    },
-  }),
-
-  defineInputGuardrail({
-    name: 'spam-detector',
-    description: 'Blocks repetitive or low-value requests',
-    execute: async (params) => {
-      const { prompt } = extractTextContent(params);
-
-      // Detect repetitive patterns that waste money
-      const spamPatterns = [
-        /^(.)\1{10,}$/, // Repeated characters
-        /^(test|hello|hi|hey)$/i, // Common spam words
-        /(.{1,20})\1{3,}/g, // Repetitive phrases
-      ];
-
-      if (
-        typeof prompt === 'string' &&
-        spamPatterns.some((pattern) => pattern.test(prompt))
-      ) {
-        return {
-          tripwireTriggered: true,
-          message:
-            'Spam-like content blocked - preventing unnecessary API calls',
-          severity: 'high',
-        };
-      }
-      return { tripwireTriggered: false };
-    },
-  }),
-];
-
-// Layer 2: Quality assurance - ensure responses are useful
-const qualityAssuranceLayer = [
-  defineOutputGuardrail({
-    name: 'response-value-checker',
-    description: 'Ensures responses provide actual value',
-    execute: async (context) => {
-      const { text } = extractContent(context.result);
-
-      // Check for low-value responses that waste resources
-      const lowValueIndicators = [
-        text.length < 20, // Too short to be useful
-        /^(I don't know|I cannot|Sorry, I can't)/.test(text), // Refusal without help
-        text.split(' ').length < 5, // Minimal effort response
-      ];
-
-      if (
-        lowValueIndicators.some((indicator) => indicator === true || indicator)
-      ) {
-        return {
-          tripwireTriggered: true,
-          message: 'Low-value response detected - inefficient use of resources',
-          severity: 'medium',
-          suggestion: 'Rephrase request for more specific, actionable help',
-        };
-      }
-
-      return { tripwireTriggered: false };
-    },
-  }),
-];
-
-// Smart model that optimizes performance and ensures quality
-const smartModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createInputGuardrailsMiddleware({
-      inputGuardrails: optimizationLayer,
-      throwOnBlocked: true, // Stop wasteful requests immediately
-    }),
-
-    createOutputGuardrailsMiddleware({
-      outputGuardrails: qualityAssuranceLayer,
-      throwOnBlocked: false, // Log quality issues but don't break flow
-      onOutputBlocked: (results) => {
-        // Track quality metrics for optimization
-        console.log(
-          'Quality issue detected - optimizing for next time:',
-          results[0]?.message,
-        );
-      },
-    }),
-  ],
-});
+## 📚 API Overview
 
-// Example usage with cost tracking
-const result = await generateText({
-  model: smartModel,
-  prompt: 'Write a comprehensive guide to software testing best practices',
-  experimental_telemetry: {
-    isEnabled: true,
-    functionId: 'cost-optimised-generation',
-    metadata: {
-      resource_optimization: true,
-      quality_checks: true,
-    },
-  },
-});
-```
+| 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.                   |
 
-## Error Handling and Response Strategies
+## 🧠 Design Philosophy
 
-When guardrails block requests or filter responses, your application needs to handle these situations gracefully. Understanding the middleware flow helps you implement proper error handling:
+- ✅ **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.
 
-### Middleware Flow and Decision Points
+## Architecture Overview
+
+The library leverages the Vercel AI SDK's middleware architecture to provide composable guardrails that integrate seamlessly with your existing AI applications:
 
 ```mermaid
-flowchart TB
-    A[Your Application] --> B[wrapLanguageModel]
-    B --> C[Input Middleware]
-    C --> D{Validation<br/>Passed?}
-    D -->|❌ Blocked| E[GuardrailError<br/>+ Callbacks]
-    D -->|✅ Approved| F[AI SDK Core]
-    F --> G[AI Model Call]
-    G --> H[Output Middleware]
-    H --> I{Quality<br/>Check?}
-    I -->|⚠️ Issues| J[Filtered Response<br/>+ Callbacks]
-    I -->|✅ Clean| K[Final Response]
-
-    style C fill:#e1f5fe
-    style H fill:#f3e5f5
-    style E fill:#ffebee
-    style J fill:#fff3e0
-```
+graph TB
+    subgraph "Your Application"
+        App[Your App Code]
+        Config[Guardrail Configuration]
+    end
 
-The diagram shows two key decision points where your error handling strategies activate:
+    subgraph "AI SDK Guardrails Middleware"
+        InputMW[Input Guardrails Middleware]
+        OutputMW[Output Guardrails Middleware]
 
-- **Input validation failures** → Trigger callbacks or throw errors
-- **Output quality issues** → Filter responses and log concerns
+        subgraph "Input Guardrails Layer"
+            Length[Length Validation]
+            Spam[Spam Detection]
+            PII[PII Detection]
+            Business[Business Rules]
+            Custom1[Custom Guards]
+        end
 
-Here's how to implement proper error handling for each scenario:
+        subgraph "Output Guardrails Layer"
+            Quality[Quality Assurance]
+            Sensitive[Sensitive Info Filter]
+            Professional[Professional Tone]
+            Factual[Factual Validation]
+            Custom2[Custom Guards]
+        end
+    end
 
-### Input Guardrail Errors
+    subgraph "AI SDK Core"
+        Wrapper[wrapLanguageModel]
+        Generator[generateText/Object/Stream]
+    end
 
-Input guardrails can either throw errors or trigger callbacks, depending on your configuration:
+    subgraph "External Services"
+        AI[AI Model Provider]
+        Log[Logging & Telemetry]
+    end
 
-```typescript
-const protectedModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createInputGuardrailsMiddleware({
-      inputGuardrails: [lengthLimitGuardrail, spamFilterGuardrail],
-
-      // Option 1: Handle via callbacks (recommended for production)
-      throwOnBlocked: false,
-      onInputBlocked: (results) => {
-        results.forEach((result) => {
-          console.warn(
-            `Blocked by ${result.context?.guardrailName}: ${result.message}`,
-          );
-
-          // Log to monitoring system
-          analytics.track('guardrail_blocked', {
-            guardrail: result.context?.guardrailName,
-            severity: result.severity,
-            suggestion: result.suggestion,
-          });
-
-          // Notify user with helpful message
-          notifyUser(
-            result.suggestion || 'Please refine your request and try again',
-          );
-        });
-      },
-    }),
-  ],
-});
+    App --> Config
+    Config --> InputMW
+    InputMW --> Length
+    InputMW --> Spam
+    InputMW --> PII
+    InputMW --> Business
+    InputMW --> Custom1
 
-try {
-  const result = await generateText({
-    model: protectedModel,
-    prompt: userInput,
-  });
+    InputMW -->|Valid Request| Wrapper
+    InputMW -->|Blocked Request| Log
 
-  // Handle successful response
-  if (result.text) {
-    return result.text;
-  } else {
-    // Request was blocked but handled gracefully
-    return "I'm sorry, I couldn't process that request. Please try rephrasing.";
-  }
-} catch (error) {
-  // Handle any unexpected errors
-  console.error('Unexpected error:', error);
-  return "I'm experiencing technical difficulties. Please try again later.";
-}
-```
+    Wrapper --> Generator
+    Generator --> AI
+    AI --> OutputMW
 
-### Output Guardrail Handling
+    OutputMW --> Quality
+    OutputMW --> Sensitive
+    OutputMW --> Professional
+    OutputMW --> Factual
+    OutputMW --> Custom2
 
-Output guardrails typically filter or modify responses rather than throwing errors:
+    OutputMW -->|Clean Response| App
+    OutputMW -->|Quality Issues| Log
 
-```typescript
-const qualityModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createOutputGuardrailsMiddleware({
-      outputGuardrails: [sensitiveInfoDetector, professionalToneChecker],
-      throwOnBlocked: false, // Usually false for output guardrails
-      onOutputBlocked: (results) => {
-        results.forEach((result) => {
-          // Log quality issues for continuous improvement
-          console.log(`Quality issue: ${result.message}`);
-
-          // Track metrics
-          metrics.increment('output_filtered', {
-            guardrail: result.context?.guardrailName,
-            severity: result.severity,
-          });
-
-          // Optionally regenerate with stronger guidance
-          if (result.severity === 'high') {
-            scheduleRegeneration(result.suggestion);
-          }
-        });
-      },
-    }),
-  ],
-});
+    style InputMW fill:#e1f5fe
+    style OutputMW fill:#f3e5f5
+    style AI fill:#fff3e0
+    style App fill:#e8f5e8
 ```
 
-### User-Friendly Error Messages
-
-Transform technical guardrail messages into user-friendly guidance:
-
-```typescript
-function createUserFriendlyMessage(guardrailResult: GuardrailResult): string {
-  const guardrailName = guardrailResult.context?.guardrailName;
+## 🍳 Recipes & Use Cases
 
-  switch (guardrailName) {
-    case 'content-length-limit':
-      return 'Your message is too long. Please keep it under 500 characters for the best response.';
+Guardrails can enforce any custom logic. Here are a few common patterns.
 
-    case 'blocked-keywords':
-      return "I can't help with that topic. Try asking about something else I can assist with.";
+### Rate Limiting
 
-    case 'rate-limit':
-      return "You're sending requests too quickly. Please wait a moment before trying again.";
+Pass a userId in the metadata of your generateText call to enforce per-user rate limits.
 
-    case 'math-homework-detector':
-      return "I'm designed to help you understand concepts, not solve homework directly. Ask me to explain the topic instead!";
-
-    default:
-      return (
-        guardrailResult.suggestion ||
-        'Please refine your request and try again.'
-      );
-  }
-}
+```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}`,
+        };
+  },
+});
 ```
 
-### Best Practices for Error Handling
+### LLM-as-Judge for Quality Scoring
 
-1. **Use callbacks over exceptions** for better user experience
-2. **Log guardrail events** for monitoring and improvement
-3. **Provide helpful suggestions** rather than just blocking
-4. **Track metrics** to understand usage patterns
-5. **Implement fallback responses** for graceful degradation
-6. **Consider retry logic** with exponential backoff for rate limits
+Use a cheaper, faster model to "judge" the output of a more powerful one.
 
-## Understanding the Benefits
-
-### Resource Optimization Through Input Validation
+```typescript
+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}"`,
+    });
+
+    const isSafe = judgement.text.includes('YES');
+    return isSafe
+      ? { tripwireTriggered: false }
+      : {
+          tripwireTriggered: true,
+          message: `Output failed LLM-as-judge quality check.`,
+          metadata: { originalText: result.text },
+        };
+  },
+});
+```
 
-Input guardrails act as intelligent gatekeepers that prevent inefficient API calls that would likely fail or provide little value:
+### Advanced Input Validation
 
 ```typescript
-import { defineInputGuardrail } from 'ai-sdk-guardrails';
 import { extractTextContent } from 'ai-sdk-guardrails/guardrails/input';
 
-// Prevent inefficient calls for common time-wasters
-const resourceOptimizationGuardrail = defineInputGuardrail({
-  name: 'resource-optimization',
-  description: 'Prevents inefficient API calls that provide little value',
+const comprehensiveInputGuard = defineInputGuardrail({
+  name: 'comprehensive-input-validation',
   execute: async (context) => {
     const { prompt } = extractTextContent(context);
 
-    // Block requests that typically result in low-value responses
-    const timeWasters = [
-      /^(hi|hello|hey|test)$/i,
-      /^.{1,5}$/, // Too short
-      /just testing/i,
-      /can you hear me/i,
-    ];
-
-    const foundWaste = timeWasters.find((pattern) =>
-      pattern.test(prompt || ''),
-    );
-    if (foundWaste) {
+    // Length validation
+    if (prompt.length < 10) {
       return {
         tripwireTriggered: true,
-        message: `Blocked time-wasting request - prevented unnecessary API call`,
+        message: 'Input too short - likely to produce low-value response',
         severity: 'medium',
-        metadata: {
-          pattern: foundWaste.source,
-          api_calls_prevented: 1,
-        },
+        suggestion: 'Please provide more detailed input for better results',
       };
     }
 
-    // Block requests that often exceed token limits
-    if (prompt && prompt.length > 12000) {
+    if (prompt.length > 4000) {
       return {
         tripwireTriggered: true,
-        message:
-          'Request likely to exceed token limits - preventing API failure',
+        message: 'Input too long - may exceed token limits',
+        severity: 'high',
+        suggestion: 'Break your request into smaller, focused parts',
+      };
+    }
+
+    // Content quality checks
+    const spamPatterns = [
+      /^(.)\1{10,}$/, // Repeated characters
+      /^(test|hello|hi|hey)$/i, // Common spam words
+    ];
+
+    const foundSpam = spamPatterns.find((pattern) => pattern.test(prompt));
+    if (foundSpam) {
+      return {
+        tripwireTriggered: true,
+        message: 'Low-quality input detected',
         severity: 'high',
-        suggestion:
-          'Break into smaller, focused requests for better results and efficiency',
       };
     }
 
@@ -534,18 +432,13 @@ const resourceOptimizationGuardrail = defineInputGuardrail({
 });
 ```
 
-### Quality Assurance Through Output Validation
-
-Output guardrails ensure every response meets your quality standards before reaching users:
+### Professional Output Quality Control
 
 ```typescript
-import { defineOutputGuardrail } from 'ai-sdk-guardrails';
 import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
 
-// Ensure responses are professional and useful
-const professionalQualityGuardrail = defineOutputGuardrail({
+const professionalQualityGuard = defineOutputGuardrail({
   name: 'professional-quality-control',
-  description: 'Ensures responses meet professional standards',
   execute: async (context) => {
     const { text } = extractContent(context.result);
 
@@ -561,7 +454,7 @@ const professionalQualityGuardrail = defineOutputGuardrail({
       qualityIssues.push('Contains unprofessional language');
     }
 
-    // Check for placeholder text that indicates incomplete response
+    // Check for placeholder text
     const placeholders = ['[insert', '[add', '[your', 'TODO:', 'FIXME:'];
     const hasPlaceholders = placeholders.some((placeholder) =>
       text.includes(placeholder),
@@ -600,263 +493,115 @@ const professionalQualityGuardrail = defineOutputGuardrail({
 });
 ```
 
-### Streaming Intelligence: Real-Time Quality Control
+## 🔄 Streaming Support
 
-For streaming responses, maintain quality while preserving the real-time experience:
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant I as Input Guardrails
-    participant A as AI Model
-    participant S as Stream
-    participant O as Output Guardrails
-
-    U->>I: Request
-    I->>I: ✅ Validate & Approve
-    I->>A: Start Stream
-    A->>S: Stream chunks
-    loop Real-time streaming
-        S-->>U: Chunk 1, 2, 3...
-    end
-    S->>O: Complete response
-    O->>O: 🛡️ Quality check
-    Note over O: Post-completion validation
-    O-->>U: Quality feedback (if needed)
-```
+Guardrails work with streams out-of-the-box. Output guardrails will run after the complete response has been streamed and generated.
 
 ```typescript
-import { streamText, wrapLanguageModel } from 'ai';
-import {
-  createOutputGuardrailsMiddleware,
-  defineOutputGuardrail,
-} from 'ai-sdk-guardrails';
-import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
-
-// Monitor streaming quality without interrupting the experience
-const streamingQualityGuardrail = defineOutputGuardrail({
-  name: 'streaming-quality-monitor',
-  description: 'Monitors streaming content for quality and appropriateness',
-  execute: async (context) => {
-    const { text } = extractContent(context.result);
+import { streamText } from 'ai';
 
-    // Quality checks that run after streaming completes
-    const qualityMetrics = {
-      coherence: calculateCoherence(text),
-      completeness:
-        text.endsWith('.') || text.endsWith('!') || text.endsWith('?'),
-      appropriateness: !containsInappropriateContent(text),
-      value: text.length > 50 && !isGenericResponse(text),
-    };
-
-    const issues = Object.entries(qualityMetrics)
-      .filter(([_, passed]) => !passed)
-      .map(([metric, _]) => metric);
-
-    if (issues.length > 0) {
-      return {
-        tripwireTriggered: true,
-        message: `Streaming quality issues: ${issues.join(', ')}`,
-        severity: 'low', // Don't break user experience, just log
-        metadata: {
-          quality_metrics: qualityMetrics,
-          stream_complete: true,
-        },
-      };
-    }
+const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
+  outputGuardrails: [qualityJudge],
+});
 
-    return { tripwireTriggered: false };
-  },
+const { textStream } = await streamText({
+  model: guardedModel,
+  prompt: 'Tell me a short story about a robot.',
 });
 
-// Helper functions for quality assessment
-function calculateCoherence(text: string): boolean {
-  // Simple coherence check - more sophisticated versions could use embeddings
-  const sentences = text.split(/[.!?]+/).filter((s) => s.trim());
-  return sentences.length > 1 && sentences.every((s) => s.trim().length > 10);
+// Stream the response to the client
+for await (const delta of textStream) {
+  process.stdout.write(delta);
 }
 
-function containsInappropriateContent(text: string): boolean {
-  const inappropriate = ['inappropriate', 'offensive', 'harmful'];
-  return inappropriate.some((term) => text.toLowerCase().includes(term));
-}
+// The qualityJudge guardrail will run after the stream is complete.
+```
 
-function isGenericResponse(text: string): boolean {
-  const genericPhrases = [
-    'I cannot help',
-    "I don't have information",
-    'I cannot provide',
-    "Sorry, I can't",
-  ];
-  return genericPhrases.some((phrase) => text.includes(phrase));
-}
+## 🛠️ Error Handling
 
-const qualityStreamingModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createOutputGuardrailsMiddleware({
-      outputGuardrails: [streamingQualityGuardrail],
-      throwOnBlocked: false, // Log issues but don't interrupt streaming
-      onOutputBlocked: (results) => {
-        // Log for continuous improvement
-        console.log('Stream quality feedback:', results[0]?.metadata);
-      },
-    }),
-  ],
-});
+When `throwOnBlocked: true` (the default), you can catch structured errors to handle blocks gracefully.
 
-// Stream with quality monitoring
-const enhancedStream = await streamText({
-  model: qualityStreamingModel,
-  prompt: 'Explain the benefits of automated testing',
-  maxTokens: 1000,
-});
+```typescript
+import { generateText } from 'ai';
+import { isGuardrailsError } from 'ai-sdk-guardrails';
 
-// Users see real-time streaming
-for await (const chunk of enhancedStream.textStream) {
-  process.stdout.write(chunk);
+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);
+  }
 }
-
-// Quality analysis happens post-stream for continuous improvement
-console.log('\nStream completed with quality monitoring');
 ```
 
-## Production-Ready Performance and Quality Controls
-
-### Smart Input Filtering
+### User-Friendly Error Messages
 
-Access comprehensive input validation that optimizes performance while maintaining user experience:
+Transform technical guardrail messages into user-friendly guidance:
 
 ```typescript
-import {
-  lengthLimit,
-  rateLimitGuardrail,
-  piiDetector,
-  spamFilter,
-} from 'ai-sdk-guardrails/guardrails/input';
-
-const optimizedInputs = [
-  // Prevent resource waste
-  lengthLimit({
-    minLength: 10, // Block "hi", "test", etc.
-    maxLength: 4000, // Prevent token limit overruns
-    encoding: 'tiktoken',
-  }),
-
-  spamFilter({
-    detectRepetition: true,
-    blockCommonWaste: ['test', 'hello', 'hi'],
-    sensitivity: 'medium',
-  }),
-
-  // Smart rate limiting that adapts to user behavior
-  rateLimitGuardrail({
-    requestsPerMinute: 30,
-    burstAllowance: 5,
-    adaptiveThrottling: true, // Reduces limits for low-quality requests
-  }),
-
-  // Block requests containing sensitive data (often leads to refusals)
-  piiDetector({
-    redactionMode: 'block', // Stop the request entirely
-    includeFinancial: true,
-    strictMode: true,
-  }),
-];
-```
+function createUserFriendlyMessage(guardrailResult): string {
+  const guardrailName = guardrailResult.context?.guardrailName;
+
+  switch (guardrailName) {
+    case 'content-length-limit':
+      return 'Your message is too long. Please keep it under 500 characters for the best response.';
 
-### Advanced Output Quality Assurance
+    case 'blocked-keywords':
+      return "I can't help with that topic. Try asking about something else I can assist with.";
 
-Choose from sophisticated output validation that ensures professional results:
+    case 'user-rate-limit':
+      return "You're sending requests too quickly. Please wait a moment before trying again.";
 
-```typescript
-import {
-  sensitiveInfoDetector,
-  qualityAssurance,
-  professionalToneChecker,
-  factualnessValidator,
-} from 'ai-sdk-guardrails/guardrails/output';
-
-const qualityOutputs = [
-  // Prevent embarrassing information leaks
-  sensitiveInfoDetector({
-    strictMode: true,
-    blockOnDetection: true,
-    customPatterns: ['internal-', 'confidential'],
-  }),
-
-  // Ensure responses meet quality standards
-  qualityAssurance({
-    minHelpfulness: 0.7,
-    maxRepetition: 0.3,
-    requireCompleteness: true,
-    blockGenericResponses: true,
-  }),
-
-  // Maintain professional tone
-  professionalToneChecker({
-    blockUnprofessional: true,
-    requireCourteousLanguage: true,
-    forbidSlang: true,
-  }),
-
-  // Validate factual accuracy (uses AI-powered checking)
-  factualnessValidator({
-    confidence: 0.8,
-    checkCitations: true,
-    blockUncertain: false, // Log but don't block uncertain claims
-  }),
-];
+    default:
+      return (
+        guardrailResult.suggestion ||
+        'Please refine your request and try again.'
+      );
+  }
+}
 ```
 
 ## Complete AI SDK Integration
 
-The library seamlessly integrates with all AI SDK functions through the middleware architecture:
+The library seamlessly integrates with all AI SDK functions:
 
 ```typescript
-// Create your performance-optimized, quality-assured model once
-const productionModel = wrapLanguageModel({
-  model: openai('gpt-4'),
-  middleware: [
-    createInputGuardrailsMiddleware({
-      inputGuardrails: optimizedInputs,
-    }),
-    createOutputGuardrailsMiddleware({
-      outputGuardrails: qualityOutputs,
-    }),
-  ],
+// 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);
+  },
+  onOutputBlocked: (results) => {
+    console.log('Output filtered:', results[0]?.message);
+  },
 });
 
-// Use with any AI SDK function - same optimization and quality everywhere
+// Use with any AI SDK function
 const textResult = await generateText({
   model: productionModel,
   prompt: 'Write a professional email response',
-  experimental_telemetry: {
-    isEnabled: true,
-    functionId: 'performance-optimized-text',
-    metadata: { optimization: 'performance+quality' },
-  },
 });
 
 const objectResult = await generateObject({
   model: productionModel,
   prompt: 'Create a user profile',
   schema: userProfileSchema,
-  experimental_telemetry: {
-    isEnabled: true,
-    functionId: 'performance-optimized-object',
-    metadata: { optimization: 'performance+quality' },
-  },
 });
 
 const textStream = await streamText({
   model: productionModel,
   prompt: 'Explain our product features',
-  experimental_telemetry: {
-    isEnabled: true,
-    functionId: 'performance-optimized-stream',
-    metadata: { optimization: 'performance+quality' },
-  },
 });
 ```
 
@@ -895,124 +640,12 @@ tsx examples/basic-guardrails.ts 1    # Run first example only
 tsx examples/streaming-guardrails.ts 3 # Run third streaming example
 ```
 
-All examples feature interactive menus with arrow key navigation, multi-selection with checkboxes, and automatic return to the main menu. They demonstrate practical performance optimization and quality assurance patterns.
-
-## Architecture Overview
-
-The library leverages the Vercel AI SDK's middleware architecture to provide composable guardrails that integrate seamlessly with your existing AI applications:
-
-```mermaid
-graph TB
-    subgraph "Your Application"
-        App[Your App Code]
-        Config[Guardrail Configuration]
-    end
-
-    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
-```
-
-### Middleware Execution Flow
-
-The guardrails execute in a specific order to maximize efficiency and ensure quality:
-
-```mermaid
-sequenceDiagram
-    participant App as Your Application
-    participant IM as Input Middleware
-    participant SDK as AI SDK Core
-    participant AI as AI Model
-    participant OM as Output Middleware
-    participant Log as Telemetry
-
-    App->>IM: User Request
-    IM->>IM: ⚡ Resource Validation
-    alt Request Blocked
-        IM->>Log: 📊 Log Blocked Request
-        IM->>App: ❌ GuardrailError
-    else Request Approved
-        IM->>SDK: ✅ Validated Request
-        SDK->>AI: API Call
-        AI->>SDK: Raw Response
-        SDK->>OM: Process Response
-        OM->>OM: 🛡️ Quality Validation
-        alt Quality Issues
-            OM->>Log: 📊 Log Quality Issues
-            OM->>App: ⚠️ Filtered Response
-        else High Quality
-            OM->>App: ✅ Clean Response
-        end
-    end
-```
-
-This architecture ensures that:
-
-- **Resource optimization** happens first to prevent unnecessary API calls
-- **Quality assurance** happens last to ensure professional responses
-- **Telemetry** captures both blocked requests and quality metrics
-- **Composability** allows mixing and matching guardrails as needed
+All examples feature interactive menus with arrow key navigation, multi-selection with checkboxes, and automatic return to the main menu.
 
-## Contributing
+## 🤝 Contributing
 
-We welcome contributions! Please open issues and pull requests on [GitHub](https://github.com/jagreehal/ai-sdk-guardrails).
+Contributions of all sizes are welcome! Please open issues and pull requests on [GitHub](https://github.com/jagreehal/ai-sdk-guardrails).
 
-## License
+## 📄 License
 
-MIT © [Jag Reehal](https://github.com/jagreehal)
+MIT © [Jag Reehal](https://github.com/jagreehal) – See LICENSE for full details.