ai-sdk-guardrails 2.0.0 → 4.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.
+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**
-
-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.
+Quickly add input and output validation to any AI SDK-compatible model.
 
-### 🎯 **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,75 @@ 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
+## 🔄 Migration Guide
+
+For breaking changes from v3 to v4 (including the new analytics-rich callbacks), see [v3-v4-MIGRATION.md](./v3-v4-MIGRATION.md).
+
+## 🚀 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 +161,53 @@ 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: (executionSummary) => {
+    console.log(
+      'Prevented sensitive data leak:',
+      executionSummary.blockedResults[0]?.message,
+    );
+
+    // Access comprehensive analytics (New in v4.0.0)
+    console.log(
+      `Blocked ${executionSummary.stats.blocked} of ${executionSummary.guardrailsExecuted} guardrails`,
+    );
+  },
 });
 
 const result = await generateText({
@@ -144,388 +215,305 @@ 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.
+### 4. Type-Safe Metadata (TypeScript)
 
-### Smart API Optimization Strategy
-
-Build intelligent resource management by combining multiple validation layers:
+The library automatically infers metadata types from your guardrail definitions - no manual type annotations needed!
 
 ```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',
-        };
-      }
+// Define metadata interface for your guardrail
+interface PIIMetadata extends Record<string, unknown> {
+  detectedTypes: Array<{ type: string; description: string }>;
+  count: number;
+}
 
-      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,
-        );
+// Create guardrail with typed metadata
+const piiDetectionGuardrail = defineInputGuardrail({
+  name: 'pii-detection',
+  execute: async (context) => {
+    const { prompt } = extractTextContent(context);
+
+    const patterns = [
+      {
+        name: 'SSN',
+        regex: /\b\d{3}-\d{2}-\d{4}\b/,
+        description: 'Social Security Number',
       },
-    }),
-  ],
+      {
+        name: 'Email',
+        regex: /\b[\w\.-]+@[\w\.-]+\.\w+\b/,
+        description: 'Email address',
+      },
+    ];
+
+    const detected = patterns.filter((p) => p.regex.test(prompt));
+
+    if (detected.length > 0) {
+      // TypeScript knows this metadata matches PIIMetadata
+      const metadata: PIIMetadata = {
+        detectedTypes: detected.map((p) => ({
+          type: p.name,
+          description: p.description,
+        })),
+        count: detected.length,
+      };
+
+      return {
+        tripwireTriggered: true,
+        message: `PII detected: ${detected.map((p) => p.name).join(', ')}`,
+        severity: 'high',
+        metadata, // Type is automatically inferred!
+      };
+    }
+
+    return { tripwireTriggered: false };
+  },
 });
 
-// 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,
-    },
+// Use the guardrail - types flow through automatically!
+const protectedModel = wrapWithInputGuardrails(model, [piiDetectionGuardrail], {
+  onInputBlocked: (summary) => {
+    // TypeScript knows the metadata type - no casting needed!
+    const metadata = summary.blockedResults[0]?.metadata;
+    if (metadata?.detectedTypes) {
+      // Full type safety and autocomplete for metadata.detectedTypes
+      for (const type of metadata.detectedTypes) {
+        console.log(`Detected: ${type.type} - ${type.description}`);
+      }
+    }
   },
 });
 ```
 
-## Error Handling and Response Strategies
+**That's it!** Your AI application now optimizes resource usage, ensures quality, prevents inappropriate responses, and provides full type safety automatically.
+
+## ✨ Features
+
+- 🛡️ **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.
+- 🔒 **Security Protection**: Built-in defenses against prompt injection, jailbreak attempts, PII leakage, secret exposure, and tool call validation.
+- 🏛️ **Compliance & Governance**: Enforce regulatory guidelines and business rules for enterprise applications with jurisdiction-specific compliance.
+- 🔄 **Streaming Support**: Works seamlessly with both streaming (streamText) and standard (generateText) API responses with real-time content monitoring.
+- 📊 **Observability Hooks**: Built-in callbacks (onInputBlocked, onOutputBlocked, etc.) for logging and monitoring with comprehensive execution analytics.
+- ⚙️ **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.
+- 🧠 **AI-Powered Verification**: LLM-as-judge capabilities for hallucination detection and quality assessment.
+- 🌍 **Global Compliance**: Support for multiple jurisdictions (US, EU, UK, CA, AU, JP, CN, IN) with region-specific policies.
+- 📝 **Content Protection**: Copyright and IP protection with originality scoring and verbatim passage detection.
+- 🔐 **Data Integrity**: Comprehensive table validation, SQL code safety, and schema enforcement.
+- 🌐 **Network Security**: Domain allowlisting, URL sanitization, and external access controls.
+- 🔒 **Privacy & Memory**: PII redaction, memory minimization, and secure logging practices.
+- 🛡️ **Safety & Escalation**: Toxicity de-escalation, human review workflows, and streaming early termination.
+
+## 📚 API Overview
+
+| 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.                                   |
+| `isGuardrailsError()`, etc.  | Error handling utilities and structured error types.                          |
+
+## 🧠 Design Philosophy
+
+- ✅ **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 automatic type inference for guardrail metadata - no manual type annotations needed!
+- 🧪 **Sensible Defaults**: Get started quickly with zero-config default behaviors that can be easily overridden.
 
-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:
+## Architecture Overview
 
-### Middleware Flow and Decision Points
+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;
-
-  switch (guardrailName) {
-    case 'content-length-limit':
-      return 'Your message is too long. Please keep it under 500 characters for the best response.';
+## 🍳 Recipes & Use Cases
 
-    case 'blocked-keywords':
-      return "I can't help with that topic. Try asking about something else I can assist with.";
+Guardrails can enforce any custom logic. Here are a few common patterns.
 
-    case 'rate-limit':
-      return "You're sending requests too quickly. Please wait a moment before trying again.";
+### Rate Limiting
 
-    case 'math-homework-detector':
-      return "I'm designed to help you understand concepts, not solve homework directly. Ask me to explain the topic instead!";
+Pass a userId in the metadata of your generateText call to enforce per-user rate limits.
 
-    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
-
-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
+### LLM-as-Judge for Quality Scoring
 
-## Understanding the Benefits
+Use a cheaper, faster model to "judge" the output of a more powerful one.
 
-### 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 +522,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 +544,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,419 +583,313 @@ const professionalQualityGuardrail = defineOutputGuardrail({
 });
 ```
 
-### Streaming Intelligence: Real-Time Quality Control
-
-For streaming responses, maintain quality while preserving the real-time experience:
+## 🔄 Streaming Support
 
-```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. By default, output guardrails run after the complete response has been streamed (buffer mode).
 
 ```typescript
-import { streamText, wrapLanguageModel } from 'ai';
-import {
-  createOutputGuardrailsMiddleware,
-  defineOutputGuardrail,
-} from 'ai-sdk-guardrails';
-import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
+import { streamText } from 'ai';
 
-// 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);
+const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
+  outputGuardrails: [qualityJudge],
+});
 
-    // 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 { textStream } = await streamText({
+  model: guardedModel,
+  prompt: 'Tell me a short story about a robot.',
+});
 
-    const issues = Object.entries(qualityMetrics)
-      .filter(([_, passed]) => !passed)
-      .map(([metric, _]) => metric);
+// Stream the response to the client
+for await (const delta of textStream) {
+  process.stdout.write(delta);
+}
 
-    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,
-        },
-      };
-    }
+// The qualityJudge guardrail will run after the stream is complete.
+```
 
-    return { tripwireTriggered: false };
-  },
+### Progressive Streaming (opt-in)
+
+For early blocking, enable progressive evaluation:
+
+```ts
+const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
+  outputGuardrails: [qualityJudge],
+  // Evaluate on the fly and stop early when blocked
+  streamMode: 'progressive',
+  // Replace blocked output with a placeholder (default: true)
+  replaceOnBlocked: true,
 });
+```
 
-// 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);
-}
+In progressive mode, guardrails evaluate text as it arrives. If blocked:
 
-function containsInappropriateContent(text: string): boolean {
-  const inappropriate = ['inappropriate', 'offensive', 'harmful'];
-  return inappropriate.some((term) => text.toLowerCase().includes(term));
-}
+- with `throwOnBlocked: true`, the stream errors.
+- with `replaceOnBlocked: true`, a placeholder message is streamed and the stream ends.
+- otherwise, the original chunks continue (with a callback via `onOutputBlocked`).
 
-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));
-}
+Note: Progressive mode runs guardrails more frequently and may increase overhead for long streams.
 
-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);
-      },
-    }),
-  ],
-});
+### Configuration Highlights
 
-// Stream with quality monitoring
-const enhancedStream = await streamText({
-  model: qualityStreamingModel,
-  prompt: 'Explain the benefits of automated testing',
-  maxTokens: 1000,
-});
+- `replaceOnBlocked` (output): defaults to `true` for safer behavior.
+- `executionOptions.logLevel`: defaults to `'warn'` (respects `'none' | 'error' | 'warn' | 'info' | 'debug'`).
+- `onInputBlocked` / `onOutputBlocked`: receive a `GuardrailExecutionSummary` with analytics.
 
-// Users see real-time streaming
-for await (const chunk of enhancedStream.textStream) {
-  process.stdout.write(chunk);
-}
+### Cancellation Support
 
-// Quality analysis happens post-stream for continuous improvement
-console.log('\nStream completed with quality monitoring');
-```
+Guardrails can receive an `AbortSignal` and should abort work on timeout or caller-initiated cancel:
+
+```ts
+const guard = defineInputGuardrail({
+  name: 'long-check',
+  async execute(context, { signal }) {
+    await doWork({ signal }); // Pass signal to your async ops
+    return { tripwireTriggered: false };
+  },
+});
 
-## Production-Ready Performance and Quality Controls
+// Timeouts are enforced by guardrail execution; if it times out, you'll get a GuardrailTimeoutError.
+```
 
-### Smart Input Filtering
+## 🛠️ Error Handling
 
-Access comprehensive input validation that optimizes performance while maintaining user experience:
+When `throwOnBlocked: true` (the default), you can catch structured errors to handle blocks gracefully.
 
 ```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,
-  }),
-];
+import { generateText } from 'ai';
+import { isGuardrailsError } from '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);
+  }
+}
 ```
 
-### Advanced Output Quality Assurance
+### User-Friendly Error Messages
 
-Choose from sophisticated output validation that ensures professional results:
+Transform technical guardrail messages into user-friendly guidance:
 
 ```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
-  }),
-];
+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.';
+
+    case 'blocked-keywords':
+      return "I can't help with that topic. Try asking about something else I can assist with.";
+
+    case 'user-rate-limit':
+      return "You're sending requests too quickly. Please wait a moment before trying again.";
+
+    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: (executionSummary) => {
+    console.log('Input blocked:', executionSummary.blockedResults[0]?.message);
+
+    // Enhanced analytics available in v4.0.0
+    console.log(`Execution time: ${executionSummary.totalExecutionTime}ms`);
+    console.log(
+      `Guardrails: ${executionSummary.stats.blocked} blocked, ${executionSummary.stats.passed} passed`,
+    );
+  },
+  onOutputBlocked: (executionSummary) => {
+    console.log(
+      'Output filtered:',
+      executionSummary.blockedResults[0]?.message,
+    );
+
+    // Track comprehensive metrics
+    analytics.track('output_blocked', {
+      severity: executionSummary.blockedResults[0]?.severity,
+      totalGuardrails: executionSummary.guardrailsExecuted,
+      executionTime: executionSummary.totalExecutionTime,
+    });
+  },
 });
 
-// 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' },
-  },
 });
 ```
 
 ## Examples
 
-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
-
-### Additional Examples
+Explore **30 comprehensive examples** that demonstrate practical performance optimization, security protection, quality assurance, and enterprise-grade safety patterns:
 
-- **[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
+### Core Foundation Examples
 
-### Running Examples
+- **[Input Length Limits](examples/01-input-length-limit.ts)** - Foundation patterns for input validation
+- **[Blocked Keywords](examples/02-blocked-keywords.ts)** - Block prompts with specific keywords and content filtering
+- **[Output Length Check](examples/04-output-length-check.ts)** - Ensure minimum output length and quality control
+- **[Quality Assessment](examples/06-quality-assessment.ts)** - Assess response quality and content analysis
+- **[Combined Protection](examples/07-combined-protection.ts)** - Simple input/output validation for efficiency and quality
+- **[Simple Combined Protection](examples/07a-simple-combined-protection.ts)** - Simplified combined guardrails example
+- **[Blocking vs Warning](examples/08-blocking-vs-warning.ts)** - Compare blocking and warning modes with error handling
 
-```bash
-# Install dependencies
-pnpm install
+### Security & Protection Examples
 
-# 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
+- **[PII Detection](examples/03-pii-detection.ts)** - Detect and block personal information in inputs
+- **[Sensitive Output Filter](examples/05-sensitive-output-filter.ts)** - Filter sensitive data from responses
+- **[Prompt Injection Detection](examples/16-prompt-injection-detection.ts)** - Comprehensive prompt injection detection with pattern matching and heuristic scoring
+- **[Tool Call Validation](examples/17-tool-call-validation.ts)** - Tool call validation with security patterns and dangerous operation detection
+- **[Basic Tool Allowlist](examples/17a-basic-tool-allowlist.ts)** - Basic tool allowlisting for secure tool usage
+- **[Tool Parameter Validation](examples/17b-tool-parameter-validation.ts)** - Validate tool parameters for security
+- **[Secret Leakage Scan](examples/18-secret-leakage-scan.ts)** - Secret leakage scanning with automatic redaction and entropy calculation
+- **[Jailbreak Detection](examples/30-jailbreak-detection.ts)** - Jailbreak detection with safe response templates and pattern recognition
 
-# 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
-```
+### Content Quality & Validation Examples
 
-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.
+- **[Autoevals Guardrails](examples/31-autoevals-guardrails.ts)** - AI-powered quality evaluation using Autoevals library for factuality checking
+- **[Business Logic](examples/14-business-logic.ts)** - Custom business rules, work hours, and professional standards
+- **[LLM-as-Judge](examples/15-llm-as-judge.ts)** - AI-powered quality evaluation and scoring
+- **[Simple Quality Judge](examples/15a-simple-quality-judge.ts)** - Simplified quality assessment example
+- **[Hallucination Detection](examples/19-hallucination-detection.ts)** - Hallucination detection with LLM-as-judge verification and fact-checking
+- **[Response Consistency](examples/22-response-consistency.ts)** - Response consistency validation and coherence checking
 
-## Architecture Overview
+### Compliance & Regulation Examples
 
-The library leverages the Vercel AI SDK's middleware architecture to provide composable guardrails that integrate seamlessly with your existing AI applications:
+- **[Regulated Advice Compliance](examples/21-regulated-advice-compliance.ts)** - Regulated advice compliance with jurisdiction-specific rules (US, EU, UK, CA, AU, JP, CN, IN)
+- **[Role Hierarchy Enforcement](examples/23-role-hierarchy-enforcement.ts)** - Role hierarchy enforcement with multi-layered violation detection
 
-```mermaid
-graph TB
-    subgraph "Your Application"
-        App[Your App Code]
-        Config[Guardrail Configuration]
-    end
+### Data Integrity & Code Safety Examples
 
-    subgraph "AI SDK Guardrails Middleware"
-        InputMW[Input Guardrails Middleware]
-        OutputMW[Output Guardrails Middleware]
+- **[Schema Validation](examples/09-schema-validation.ts)** - Schema validation and structured output quality
+- **[Object Content Filter](examples/10-object-content-filter.ts)** - Filter inappropriate content in generated objects
+- **[SQL Code Safety](examples/24-sql-code-safety.ts)** - SQL code safety with dangerous operation blocking and injection detection
 
-        subgraph "Input Guardrails Layer"
-            Length[Length Validation]
-            Spam[Spam Detection]
-            PII[PII Detection]
-            Business[Business Rules]
-            Custom1[Custom Guards]
-        end
+### Network & External Access Examples
 
-        subgraph "Output Guardrails Layer"
-            Quality[Quality Assurance]
-            Sensitive[Sensitive Info Filter]
-            Professional[Professional Tone]
-            Factual[Factual Validation]
-            Custom2[Custom Guards]
-        end
-    end
+- **[Domain Allowlisting](examples/25-browsing-domain-allowlist.ts)** - Domain allowlisting with URL sanitization and security validation
 
-    subgraph "AI SDK Core"
-        Wrapper[wrapLanguageModel]
-        Generator[generateText/Object/Stream]
-    end
+### Privacy & Memory Management Examples
 
-    subgraph "External Services"
-        AI[AI Model Provider]
-        Log[Logging & Telemetry]
-    end
+- **[Memory Minimization](examples/26-memory-minimization.ts)** - Memory minimization with PII redaction and multiple redaction strategies
+- **[Logging Redaction](examples/27-logging-redaction.ts)** - Logging redaction with secure logging practices and compliance frameworks
 
-    App --> Config
-    Config --> InputMW
-    InputMW --> Length
-    InputMW --> Spam
-    InputMW --> PII
-    InputMW --> Business
-    InputMW --> Custom1
+### Safety & Escalation Examples
 
-    InputMW -->|Valid Request| Wrapper
-    InputMW -->|Blocked Request| Log
+- **[Human Review Escalation](examples/20-human-review-escalation.ts)** - Human review escalation with content flagging, review routing, and quality control workflows
+- **[Toxicity & Harassment De-escalation](examples/29-toxicity-harassment-deescalation.ts)** - Toxicity and harassment de-escalation with safe response generation and user escalation tracking
 
-    Wrapper --> Generator
-    Generator --> AI
-    AI --> OutputMW
+### Streaming Examples
 
-    OutputMW --> Quality
-    OutputMW --> Sensitive
-    OutputMW --> Professional
-    OutputMW --> Factual
-    OutputMW --> Custom2
+- **[Streaming Limits](examples/11-streaming-limits.ts)** - Apply guardrails to streaming responses with real-time validation
+- **[Streaming Quality](examples/12-streaming-quality.ts)** - Real-time quality monitoring for streams
+- **[Streaming Early Termination](examples/28-streaming-early-termination.ts)** - Streaming early termination with real-time content monitoring and session state management
 
-    OutputMW -->|Clean Response| App
-    OutputMW -->|Quality Issues| Log
+### Resource Management Examples
 
-    style InputMW fill:#e1f5fe
-    style OutputMW fill:#f3e5f5
-    style AI fill:#fff3e0
-    style App fill:#e8f5e8
-```
+- **[Rate Limiting](examples/13-rate-limiting.ts)** - Smart rate limiting that prevents resource overuse
 
-### Middleware Execution Flow
+### Running Examples
 
-The guardrails execute in a specific order to maximize efficiency and ensure quality:
+```bash
+# Install dependencies
+pnpm install
 
-```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
+# Run core foundation examples
+tsx examples/01-input-length-limit.ts      # Basic input validation
+tsx examples/02-blocked-keywords.ts        # Keyword blocking
+tsx examples/04-output-length-check.ts     # Output length validation
+tsx examples/06-quality-assessment.ts      # Quality assessment
+tsx examples/07-combined-protection.ts     # Combined input/output protection
+tsx examples/07a-simple-combined-protection.ts # Simplified combined protection
+tsx examples/08-blocking-vs-warning.ts     # Blocking vs warning modes
+
+# Run security examples
+tsx examples/03-pii-detection.ts           # PII protection
+tsx examples/05-sensitive-output-filter.ts # Sensitive output filtering
+tsx examples/16-prompt-injection-detection.ts # Prompt injection protection
+tsx examples/17-tool-call-validation.ts    # Tool call validation
+tsx examples/17a-basic-tool-allowlist.ts   # Basic tool allowlisting
+tsx examples/17b-tool-parameter-validation.ts # Tool parameter validation
+tsx examples/18-secret-leakage-scan.ts     # Secret leakage prevention
+tsx examples/30-jailbreak-detection.ts     # Jailbreak detection
+
+# Run content quality examples
+tsx examples/31-autoevals-guardrails.ts    # AI-powered quality evaluation with Autoevals
+tsx examples/14-business-logic.ts          # Business-specific rules
+tsx examples/15-llm-as-judge.ts            # AI-powered quality control
+tsx examples/15a-simple-quality-judge.ts   # Simplified quality assessment
+tsx examples/19-hallucination-detection.ts # Hallucination detection
+tsx examples/22-response-consistency.ts    # Response consistency
+
+# Run compliance examples
+tsx examples/21-regulated-advice-compliance.ts # Regulatory compliance
+tsx examples/23-role-hierarchy-enforcement.ts # Role hierarchy enforcement
+
+# Run data integrity examples
+tsx examples/09-schema-validation.ts       # Schema validation
+tsx examples/10-object-content-filter.ts   # Object content filtering
+tsx examples/24-sql-code-safety.ts         # SQL code safety
+
+# Run network security examples
+tsx examples/25-browsing-domain-allowlist.ts # Domain allowlisting
+
+# Run privacy examples
+tsx examples/26-memory-minimization.ts     # Memory minimization
+tsx examples/27-logging-redaction.ts       # Logging redaction
+
+# Run safety examples
+tsx examples/20-human-review-escalation.ts # Human review escalation
+tsx examples/29-toxicity-harassment-deescalation.ts # Toxicity de-escalation
+
+# Run streaming examples
+tsx examples/11-streaming-limits.ts        # Streaming limits
+tsx examples/12-streaming-quality.ts       # Streaming quality monitoring
+tsx examples/28-streaming-early-termination.ts # Streaming early termination
+
+# Run resource management examples
+tsx examples/13-rate-limiting.ts           # Rate limiting
 ```
 
-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
-
-## 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.