ai-sdk-guardrails 1.0.0 → 2.0.0

package/README.md

@@ -1,84 +1,74 @@
 # AI SDK Guardrails
 
-The safest way to build production AI applications with the Vercel AI SDK. A comprehensive TypeScript library that protects your AI systems with intelligent input and output validation, streaming safety, and enterprise-grade reliability.
+Stop unnecessary AI calls. Optimize performance, improve quality, and prevent inappropriate AI responses with intelligent middleware for the Vercel AI SDK.
 
 [![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)
 
-## Why AI SDK Guardrails?
+## Requirements
 
-Building AI applications is exciting, but deploying them safely in production requires careful consideration. This library provides the safety net you need without sacrificing developer experience or performance.
+This library requires the Vercel AI SDK (v5 and above) for its composable middleware architecture:
 
-### 🛡️ Complete Protection
+```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:
 
-Validate inputs before they reach your model and outputs before they reach users. Catch harmful content, PII, prompt injections, and more.
+![Guardrails](./media/guardrail-example.gif)
 
-### ⚡ Real-time Streaming Safety
+### ⚡ **Optimize API Usage**
 
-The only guardrails library with true streaming support. Monitor and stop streams in real-time when safety violations occur.
+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.
 
-### 🎯 Built for Vercel AI SDK
+### 🎯 **Improve Response Quality**
 
-First-class support for all AI SDK functions: `generateText`, `generateObject`, `streamText`, `streamObject`, and `embed`.
+Ensure every AI response meets your standards. Filter out hallucinations, check factuality, enforce formatting requirements, and maintain consistent quality across your application.
 
-### 🔧 Developer Friendly
+### 🛡️ **Prevent Embarrassing Responses**
 
-Simple API with TypeScript autocompletion, helpful error messages, and sensible defaults. Start safe in minutes, not hours.
+Stop your AI from saying things you'll regret. Block inappropriate content, filter sensitive information, detect bias, and maintain professional standards in all interactions.
+
+### ⚡ **Focus AI Generations**
+
+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.
 
 ## How It Works
 
+### Without Guardrails (Inefficient, Poor Quality)
+
 ```mermaid
-graph TB
-    A[User Input] --> B{Input Guardrails}
-    B -->|✅ Pass| C[AI Model]
-    B -->|❌ Block| D[GuardrailError]
-
-    C --> E[AI Response]
-    E --> F{Output Guardrails}
-    F -->|✅ Pass| G[Safe Response]
-    F -->|❌ Block| H[GuardrailError]
-
-    subgraph "Input Guardrails"
-        I1[Length Limit]
-        I2[Blocked Keywords]
-        I3[PII Detection]
-        I4[Prompt Injection]
-        I5[Rate Limiting]
-    end
+flowchart LR
+    A[User Input<br/>'hello'] --> B[AI Model] --> C[Response<br/>⚠️ Wastes resources<br/>😞 Often useless]
+```
 
-    subgraph "Output Guardrails"
-        O1[Quality Check]
-        O2[Toxicity Filter]
-        O3[Privacy Leakage]
-        O4[Schema Validation]
-        O5[Confidence Threshold]
-    end
+### With Input Guardrails (Save Resources)
+
+```mermaid
+flowchart LR
+    A[User Input<br/>'hello'] --> B[Input Guardrails] --> C[❌ STOPPED<br/>✅ No API call made]
+```
+
+### With Output Guardrails (Ensure Quality)
 
-    B -.-> I1
-    B -.-> I2
-    B -.-> I3
-    B -.-> I4
-    B -.-> I5
-
-    F -.-> O1
-    F -.-> O2
-    F -.-> O3
-    F -.-> O4
-    F -.-> O5
-
-    classDef inputNode fill:#e1f5fe
-    classDef outputNode fill:#f3e5f5
-    classDef blockNode fill:#ffebee
-    classDef passNode fill:#e8f5e8
-
-    class I1,I2,I3,I4,I5 inputNode
-    class O1,O2,O3,O4,O5 outputNode
-    class D,H blockNode
-    class G passNode
+```mermaid
+flowchart LR
+    A[AI Response<br/>'Here's my SSN: 123-45-6789'] --> B[Output Guardrails] --> C[❌ BLOCKED<br/>🛡️ Privacy protected]
+```
+
+### Complete Protection
+
+```mermaid
+flowchart LR
+    A[User Input] --> B[Input Guardrails] --> C[AI Model] --> D[Output Guardrails] --> E[Clean Response]
 ```
 
+That's it! Input guardrails optimize resource usage by stopping inefficient requests. Output guardrails ensure quality by filtering responses.
+
 ## Installation
 
 ```bash
@@ -91,639 +81,938 @@ yarn add ai-sdk-guardrails
 
 ## Quick Start
 
-Get started with production-ready guardrails in just a few lines:
+Add smart validation to your AI applications in just 3 steps:
+
+### 1. Prevent Unnecessary AI Calls
 
 ```typescript
-import { generateTextWithGuardrails } from 'ai-sdk-guardrails';
-import { blockedKeywords } from 'ai-sdk-guardrails/guardrails/input';
-import { outputLengthLimit } from 'ai-sdk-guardrails/guardrails/output';
+import { generateText, wrapLanguageModel } from 'ai';
 import { openai } from '@ai-sdk/openai';
+import { createInputGuardrailsMiddleware } from 'ai-sdk-guardrails';
+import { blockedKeywords } from 'ai-sdk-guardrails/guardrails/input';
 
-const result = await generateTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Write a helpful response about web security',
-  },
-  {
-    inputGuardrails: [blockedKeywords(['hack', 'exploit', 'vulnerability'])],
-    outputGuardrails: [outputLengthLimit(500)],
-  },
-);
+// Block inefficient requests before calling the AI model
+const optimizedModel = wrapLanguageModel({
+  model: openai('gpt-4'),
+  middleware: [
+    createInputGuardrailsMiddleware({
+      inputGuardrails: [blockedKeywords(['spam', 'test', 'hello'])],
+    }),
+  ],
+});
+
+// This would normally waste an API call for a useless response
+const result = await generateText({
+  model: optimizedModel,
+  prompt: 'hello', // ❌ Blocked - prevents unnecessary API call
+});
+// → Throws GuardrailError: "Blocked keyword detected: hello"
 
-console.log(result.text);
+// This generates valuable content
+const goodResult = await generateText({
+  model: optimizedModel,
+  prompt: 'Write a product description for our new software', // ✅ This creates value
+});
 ```
 
-## Core Concepts
+### 2. Ensure Quality Output
 
-### Input Guardrails
+```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);
+      },
+    }),
+  ],
+});
 
-Input guardrails validate prompts before they reach your AI model. Use them to:
+const result = await generateText({
+  model: qualityModel,
+  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]"
+```
 
-- Block harmful or inappropriate content
-- Enforce length limits
-- Detect prompt injection attempts
-- Remove personally identifiable information (PII)
-- Implement rate limiting
+### 3. Custom Business Logic
 
 ```typescript
-import { createInputGuardrail } from 'ai-sdk-guardrails';
-
-const mathHomeworkDetector = createInputGuardrail(
-  'math-homework-detector',
-  'Prevents direct homework solving requests',
-  (context) => {
-    const { prompt } = context;
-    const homeworkPatterns = [
-      /solve this equation/i,
-      /what is \d+ [\+\-\*\/] \d+/i,
-      /calculate the answer/i,
-    ];
+import { defineInputGuardrail } from 'ai-sdk-guardrails';
+import { extractTextContent } from 'ai-sdk-guardrails/guardrails/input';
 
-    const isHomework = homeworkPatterns.some((pattern) =>
-      pattern.test(prompt || ''),
-    );
+// Prevent inefficient homework help requests
+const homeworkDetector = defineInputGuardrail({
+  name: 'homework-detector',
+  execute: async (context) => {
+    const { prompt } = extractTextContent(context);
 
-    return {
-      tripwireTriggered: isHomework,
-      message: isHomework ? 'Direct homework solving detected' : undefined,
-      suggestion: isHomework
-        ? 'Try asking about the concepts instead'
-        : undefined,
-    };
+    if (prompt.includes('solve this equation') || prompt.includes('homework')) {
+      return {
+        tripwireTriggered: true,
+        message: 'Homework help blocked - prevents inefficient API usage',
+        suggestion: 'Ask about learning concepts instead',
+      };
+    }
+
+    return { tripwireTriggered: false };
   },
-);
+});
+
+const smartEducationModel = wrapLanguageModel({
+  model: openai('gpt-4'),
+  middleware: [
+    createInputGuardrailsMiddleware({
+      inputGuardrails: [homeworkDetector],
+    }),
+  ],
+});
 ```
 
-### Output Guardrails
+**That's it!** Your AI application now optimizes resource usage, ensures quality, and prevents inappropriate responses automatically.
 
-Output guardrails validate AI responses before they reach users. Use them to:
+### Smart API Optimization Strategy
 
-- Ensure response quality
-- Block sensitive information
-- Enforce formatting requirements
-- Validate against schemas
-- Check confidence levels
+Build intelligent resource management by combining multiple validation layers:
 
 ```typescript
-import { createOutputGuardrail } from 'ai-sdk-guardrails';
-
-const sensitiveInfoFilter = createOutputGuardrail(
-  'sensitive-info-filter',
-  (context) => {
-    const { text } = context.result;
-    const sensitivePatterns = [
-      /password:\s*\w+/i,
-      /api[_-]?key:\s*\w+/i,
-      /\b\d{3}-\d{2}-\d{4}\b/, // SSN format
-    ];
-
-    const hasSensitive = sensitivePatterns.some((pattern) =>
-      pattern.test(text || ''),
-    );
-
-    return {
-      tripwireTriggered: hasSensitive,
-      message: hasSensitive
-        ? 'Response contains sensitive information'
-        : undefined,
-      severity: hasSensitive ? 'critical' : 'low',
-    };
-  },
-);
-```
+// 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 };
+    },
+  }),
+];
 
-### Streaming Guardrails
+// 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',
+        };
+      }
 
-Protect streaming responses in real-time. The stream automatically stops if guardrails detect violations:
+      return { tripwireTriggered: false };
+    },
+  }),
+];
 
-```typescript
-import { streamTextWithGuardrails } from 'ai-sdk-guardrails';
+// 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,
+        );
+      },
+    }),
+  ],
+});
 
-const stream = await streamTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Generate a long story...',
-  },
-  {
-    outputGuardrails: [
-      outputLengthLimit(1000),
-      blockedOutputContent(['inappropriate', 'offensive']),
-    ],
-    onOutputBlocked: (error) => {
-      console.error('Stream blocked:', error.reason);
+// 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,
     },
   },
-);
-
-// The stream will automatically stop if guardrails trigger
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
+});
 ```
 
-## Built-in Guardrails
+## Error Handling and Response Strategies
 
-### Input Guardrails
+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:
 
-```typescript
-import {
-  lengthLimit,
-  blockedWords,
-  blockedKeywords,
-  profanityFilter,
-  promptInjectionDetector,
-  piiDetector,
-  toxicityDetector,
-  mathHomeworkDetector,
-  codeGenerationLimiter,
-} from 'ai-sdk-guardrails/guardrails/input';
+### Middleware Flow and Decision Points
 
-// Content filters
-const contentGuardrails = [
-  lengthLimit(1000),
-  blockedWords(['spam', 'hack']),
-  profanityFilter(['custom', 'words']),
-  toxicityDetector(0.7), // threshold
-];
+```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
+```
 
-// Security guardrails
-const securityGuardrails = [promptInjectionDetector(), piiDetector()];
+The diagram shows two key decision points where your error handling strategies activate:
 
-// Educational guardrails
-const educationGuardrails = [
-  mathHomeworkDetector(),
-  codeGenerationLimiter(['javascript', 'python']),
-];
-```
+- **Input validation failures** → Trigger callbacks or throw errors
+- **Output quality issues** → Filter responses and log concerns
 
-### Output Guardrails
+Here's how to implement proper error handling for each scenario:
 
-```typescript
-import {
-  lengthLimit,
-  blockedContent,
-  jsonValidation,
-  confidenceThreshold,
-  toxicityFilter,
-  schemaValidation,
-  tokenUsageLimit,
-  performanceMonitor,
-  hallucinationDetector,
-  biasDetector,
-  factualAccuracyChecker,
-  privacyLeakageDetector,
-  contentConsistencyChecker,
-  complianceChecker,
-} from 'ai-sdk-guardrails/guardrails/output';
+### Input Guardrail Errors
 
-// Quality guardrails
-const qualityGuardrails = [
-  lengthLimit(500),
-  confidenceThreshold(0.8),
-  hallucinationDetector(0.7),
-  factualAccuracyChecker(true), // require sources
-];
+Input guardrails can either throw errors or trigger callbacks, depending on your configuration:
 
-// Safety guardrails
-const safetyGuardrails = [
-  toxicityFilter(0.5),
-  biasDetector(),
-  privacyLeakageDetector(),
-  complianceChecker(['GDPR', 'HIPAA']),
-];
+```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',
+          );
+        });
+      },
+    }),
+  ],
+});
 
-// Performance guardrails
-const performanceGuardrails = [
-  tokenUsageLimit(1000),
-  performanceMonitor(5000), // max 5 seconds
-];
+try {
+  const result = await generateText({
+    model: protectedModel,
+    prompt: userInput,
+  });
+
+  // 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.";
+}
 ```
 
-## Integration with Autoevals
+### Output Guardrail Handling
 
-Use [Autoevals](https://github.com/braintrust-data/autoevals) for sophisticated AI quality evaluation as guardrails:
+Output guardrails typically filter or modify responses rather than throwing errors:
 
 ```typescript
-import { Factuality, init } from 'autoevals';
-import { createOutputGuardrail } from 'ai-sdk-guardrails';
-
-function createFactualityGuardrail({
-  expected,
-  minScore,
-}: {
-  expected: string;
-  minScore: number;
-}) {
-  return createOutputGuardrail('factuality-check', async (context) => {
-    const { text } = extractContent(context.result);
-    const { prompt } = extractTextContent(context.input);
-
-    const evalResult = await Factuality({
-      output: text,
-      expected,
-      input: prompt || '',
-      model: MODEL_NAME,
-    });
-
-    const isFactual = (evalResult.score || 0) >= minScore;
-
-    return {
-      tripwireTriggered: !isFactual,
-      message: isFactual
-        ? `Factual content (score: ${evalResult.score})`
-        : `Factual accuracy too low (score: ${evalResult.score}, required: ${minScore})`,
-      severity: isFactual ? 'low' : 'high',
-      metadata: {
-        factualityScore: evalResult.score,
-        rationale: evalResult.metadata?.rationale,
-        expected,
-        minScore,
+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);
+          }
+        });
       },
-      suggestion: isFactual
-        ? undefined
-        : 'Please provide more accurate information',
-    };
-  });
-}
-
-// Usage
-const result = await generateTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Which country has the highest population?',
-  },
-  {
-    outputGuardrails: [
-      createFactualityGuardrail({
-        expected: 'China',
-        minScore: 0.7,
-      }),
-    ],
-  },
-);
+    }),
+  ],
+});
 ```
 
-## Error Handling
+### User-Friendly Error Messages
 
-Guardrails provide rich error information to help you handle violations gracefully:
+Transform technical guardrail messages into user-friendly guidance:
 
 ```typescript
-import { GuardrailError } from 'ai-sdk-guardrails';
+function createUserFriendlyMessage(guardrailResult: GuardrailResult): string {
+  const guardrailName = guardrailResult.context?.guardrailName;
 
-try {
-  const result = await generateTextWithGuardrails(params, guardrails);
-} catch (error) {
-  if (error instanceof GuardrailError) {
-    // Access detailed error information
-    console.log('Guardrail triggered:', error.guardrailName);
-    console.log('Reason:', error.reason);
-    console.log('Type:', error.type); // 'input' or 'output'
-
-    // Get all issues
-    error.issues.forEach((issue) => {
-      console.log(`${issue.guardrail}: ${issue.message}`);
-      console.log('Severity:', issue.severity);
-      console.log('Suggestion:', issue.suggestion);
-    });
-
-    // Use helper methods
-    const summary = error.getSummary();
-    console.log(`Total issues: ${summary.totalIssues}`);
-    console.log(
-      `Guardrails triggered: ${summary.guardrailsTriggered.join(', ')}`,
-    );
-  }
-}
-```
+  switch (guardrailName) {
+    case 'content-length-limit':
+      return 'Your message is too long. Please keep it under 500 characters for the best response.';
 
-## Advanced Usage
+    case 'blocked-keywords':
+      return "I can't help with that topic. Try asking about something else I can assist with.";
 
-### Custom Validation Logic
+    case 'rate-limit':
+      return "You're sending requests too quickly. Please wait a moment before trying again.";
 
-Create sophisticated guardrails for your specific needs:
+    case 'math-homework-detector':
+      return "I'm designed to help you understand concepts, not solve homework directly. Ask me to explain the topic instead!";
 
-```typescript
-const businessLogicGuardrail = createInputGuardrail(
-  'business-logic-validator',
-  'Ensures requests meet business requirements',
-  async (context) => {
-    const { prompt, messages } = context;
-
-    // Implement your custom logic
-    const validationResult = await validateBusinessRules({
-      content: prompt,
-      history: messages,
-    });
-
-    return {
-      tripwireTriggered: !validationResult.isValid,
-      message: validationResult.error,
-      metadata: validationResult.details,
-      severity: validationResult.severity,
-      suggestion: validationResult.suggestion,
-    };
-  },
-);
+    default:
+      return (
+        guardrailResult.suggestion ||
+        'Please refine your request and try again.'
+      );
+  }
+}
 ```
 
-### Composing Guardrails
+### Best Practices for Error Handling
 
-Combine multiple guardrail configurations for different scenarios:
+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
 
-```typescript
-// Development guardrails (more lenient)
-const devGuardrails = {
-  inputGuardrails: [lengthLimit(2000)],
-  throwOnBlocked: false,
-  onInputBlocked: (error) => console.warn('Dev warning:', error),
-};
-
-// Production guardrails (strict)
-const prodGuardrails = {
-  inputGuardrails: [lengthLimit(500), blockedKeywords(['test', 'debug'])],
-  outputGuardrails: [confidenceThreshold(0.9), complianceChecker(['GDPR'])],
-  throwOnBlocked: true,
-};
-
-// Use based on environment
-const guardrails =
-  process.env.NODE_ENV === 'production' ? prodGuardrails : devGuardrails;
-```
+## Understanding the Benefits
 
-### Object Generation with Schema Validation
+### Resource Optimization Through Input Validation
 
-Validate structured outputs with custom business logic:
+Input guardrails act as intelligent gatekeepers that prevent inefficient API calls that would likely fail or provide little value:
 
 ```typescript
-import { z } from 'zod';
+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',
+  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 userSchema = z.object({
-  name: z.string(),
-  age: z.number().min(0).max(120),
-  email: z.string().email(),
-});
+    const foundWaste = timeWasters.find((pattern) =>
+      pattern.test(prompt || ''),
+    );
+    if (foundWaste) {
+      return {
+        tripwireTriggered: true,
+        message: `Blocked time-wasting request - prevented unnecessary API call`,
+        severity: 'medium',
+        metadata: {
+          pattern: foundWaste.source,
+          api_calls_prevented: 1,
+        },
+      };
+    }
 
-const schemaValidator = createOutputGuardrail(
-  'schema-validator',
-  async (context) => {
-    const { object } = extractContent(context.result);
-    try {
-      userSchema.parse(object);
-      return { tripwireTriggered: false };
-    } catch (error) {
+    // Block requests that often exceed token limits
+    if (prompt && prompt.length > 12000) {
       return {
         tripwireTriggered: true,
-        message: 'Schema validation failed',
+        message:
+          'Request likely to exceed token limits - preventing API failure',
         severity: 'high',
-        metadata: { validationError: error.message },
+        suggestion:
+          'Break into smaller, focused requests for better results and efficiency',
       };
     }
-  },
-);
 
-const result = await generateObjectWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Create a user profile for John Doe, age 30',
-    schema: userSchema,
-  },
-  {
-    outputGuardrails: [schemaValidator],
+    return { tripwireTriggered: false };
   },
-);
+});
 ```
 
-## Best Practices
-
-### 1. Layer Your Defence
+### Quality Assurance Through Output Validation
 
-Use multiple guardrails for comprehensive protection:
+Output guardrails ensure every response meets your quality standards before reaching users:
 
 ```typescript
-const guardrails = {
-  inputGuardrails: [
-    // First line: Block obvious threats
-    promptInjectionDetector(),
-    blockedKeywords(['malicious', 'exploit']),
-
-    // Second line: Quality control
-    lengthLimit(1000),
+import { defineOutputGuardrail } from 'ai-sdk-guardrails';
+import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
+
+// Ensure responses are professional and useful
+const professionalQualityGuardrail = defineOutputGuardrail({
+  name: 'professional-quality-control',
+  description: 'Ensures responses meet professional standards',
+  execute: async (context) => {
+    const { text } = extractContent(context.result);
 
-    // Third line: Business logic
-    customBusinessRules(),
-  ],
-  outputGuardrails: [
-    // Ensure quality
-    confidenceThreshold(0.7),
+    const qualityIssues = [];
 
-    // Ensure safety
-    toxicityFilter(),
-    privacyLeakageDetector(),
-  ],
-};
-```
+    // Check for unprofessional language
+    const unprofessionalTerms = ['lol', 'wtf', 'omg', 'ur', 'u r'];
+    const hasUnprofessional = unprofessionalTerms.some((term) =>
+      text.toLowerCase().includes(term),
+    );
 
-### 2. Handle Errors Gracefully
+    if (hasUnprofessional) {
+      qualityIssues.push('Contains unprofessional language');
+    }
 
-Provide helpful feedback when guardrails trigger:
+    // Check for placeholder text that indicates incomplete response
+    const placeholders = ['[insert', '[add', '[your', 'TODO:', 'FIXME:'];
+    const hasPlaceholders = placeholders.some((placeholder) =>
+      text.includes(placeholder),
+    );
 
-```typescript
-onInputBlocked: (error) => {
-  // Map technical errors to user-friendly messages
-  const userMessage =
-    {
-      'content-length-limit': 'Your message is too long. Please shorten it.',
-      'blocked-keywords': 'Your request contains restricted content.',
-      'pii-detector': 'Please remove personal information from your request.',
-    }[error.guardrailName] || 'Your request could not be processed.';
-
-  return userMessage;
-};
-```
+    if (hasPlaceholders) {
+      qualityIssues.push('Contains placeholder text - incomplete response');
+    }
 
-### 3. **Publishing Process (Using Changesets)**
+    // Check for excessive repetition
+    const sentences = text.split(/[.!?]+/).filter((s) => s.trim());
+    const uniqueSentences = new Set(
+      sentences.map((s) => s.trim().toLowerCase()),
+    );
+    const repetitionRatio = uniqueSentences.size / sentences.length;
 
-You're already set up with **Changesets** which is the recommended approach. Here's the process:
+    if (sentences.length > 3 && repetitionRatio < 0.6) {
+      qualityIssues.push('Excessive repetition detected');
+    }
 
-#### **Step 1: Create a Changeset**
+    if (qualityIssues.length > 0) {
+      return {
+        tripwireTriggered: true,
+        message: `Quality issues found: ${qualityIssues.join(', ')}`,
+        severity: 'medium',
+        suggestion: 'Request a more professional, complete response',
+        metadata: {
+          issues: qualityIssues,
+          quality_score: repetitionRatio,
+        },
+      };
+    }
 
-```bash
-npx changeset
+    return { tripwireTriggered: false };
+  },
+});
 ```
 
-This will:
+### Streaming Intelligence: Real-Time Quality Control
 
-- Ask you what type of change (patch/minor/major)
-- Let you write a summary of changes
-- Create a changeset file
+For streaming responses, maintain quality while preserving the real-time experience:
 
-#### **Step 2: Version and Publish**
+```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)
+```
 
-You have two options:
+```typescript
+import { streamText, wrapLanguageModel } from 'ai';
+import {
+  createOutputGuardrailsMiddleware,
+  defineOutputGuardrail,
+} from 'ai-sdk-guardrails';
+import { extractContent } from 'ai-sdk-guardrails/guardrails/output';
 
-**Option A: Manual Control**
+// 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);
 
-```bash
-# 1. Run CI to ensure everything passes
-npm run ci
+    // 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),
+    };
 
-# 2. Version the package (reads changesets and updates version)
-npx changeset version
+    const issues = Object.entries(qualityMetrics)
+      .filter(([_, passed]) => !passed)
+      .map(([metric, _]) => metric);
 
-# 3. Publish to npm
-npx changeset publish
-```
+    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,
+        },
+      };
+    }
+
+    return { tripwireTriggered: false };
+  },
+});
 
-**Option B: Use Your Local Release Script**
+// 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);
+}
 
-```bash
-npm run local-release
-```
+function containsInappropriateContent(text: string): boolean {
+  const inappropriate = ['inappropriate', 'offensive', 'harmful'];
+  return inappropriate.some((term) => text.toLowerCase().includes(term));
+}
 
-This runs: `npm run ci && changeset version && changeset publish`
+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));
+}
 
-### 4. **First Release Steps**
+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);
+      },
+    }),
+  ],
+});
 
-For your first release, I recommend:
+// Stream with quality monitoring
+const enhancedStream = await streamText({
+  model: qualityStreamingModel,
+  prompt: 'Explain the benefits of automated testing',
+  maxTokens: 1000,
+});
 
-1. **Fix any remaining issues** (like the prettier formatting):
+// Users see real-time streaming
+for await (const chunk of enhancedStream.textStream) {
+  process.stdout.write(chunk);
+}
 
-```bash
-npm run format
+// Quality analysis happens post-stream for continuous improvement
+console.log('\nStream completed with quality monitoring');
 ```
 
-2. **Create your first changeset**:
+## Production-Ready Performance and Quality Controls
 
-```bash
-npx changeset
+### Smart Input Filtering
+
+Access comprehensive input validation that optimizes performance while maintaining user experience:
+
+```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,
+  }),
+];
 ```
 
-- Select "major" (since this is 0.0.1 → 1.0.0)
-- Write: "Initial release of AI SDK Guardrails"
+### Advanced Output Quality Assurance
 
-3. **Release it**:
+Choose from sophisticated output validation that ensures professional results:
 
-```bash
-npm run local-release
+```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
+  }),
+];
 ```
 
-### 5. **Package Name Assessment**
+## Complete AI SDK Integration
 
-**✅ `ai-sdk-guardrails` is excellent because:**
+The library seamlessly integrates with all AI SDK functions through the middleware architecture:
 
-- Available on npm
-- Descriptive and searchable
-- Follows naming conventions
-- Clearly indicates it's for AI SDK
-- Professional sounding
+```typescript
+// Create your performance-optimized, quality-assured model once
+const productionModel = wrapLanguageModel({
+  model: openai('gpt-4'),
+  middleware: [
+    createInputGuardrailsMiddleware({
+      inputGuardrails: optimizedInputs,
+    }),
+    createOutputGuardrailsMiddleware({
+      outputGuardrails: qualityOutputs,
+    }),
+  ],
+});
 
-### 6. **Additional Recommendations**
+// Use with any AI SDK function - same optimization and quality everywhere
+const textResult = await generateText({
+  model: productionModel,
+  prompt: 'Write a professional email response',
+  experimental_telemetry: {
+    isEnabled: true,
+    functionId: 'performance-optimized-text',
+    metadata: { optimization: 'performance+quality' },
+  },
+});
 
-Consider these npm badges for your README:
+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' },
+  },
+});
 
-```markdown
-<code_block_to_apply_changes_from>
-[![npm version](https://badge.fury.io/js/ai-sdk-guardrails.svg)](https://www.npmjs.com/package/ai-sdk-guardrails)
-[![Downloads](https://img.shields.io/npm/dm/ai-sdk-guardrails.svg)](https://www.npmjs.com/package/ai-sdk-guardrails)
+const textStream = await streamText({
+  model: productionModel,
+  prompt: 'Explain our product features',
+  experimental_telemetry: {
+    isEnabled: true,
+    functionId: 'performance-optimized-stream',
+    metadata: { optimization: 'performance+quality' },
+  },
+});
 ```
 
-### 7. **GitHub Release Integration**
+## Examples
 
-After publishing to npm, you might want to:
+Explore focused examples that demonstrate practical performance optimization and quality assurance:
 
-- Create GitHub releases that match your npm versions
-- Set up GitHub Actions for automated publishing (optional)
+### Core Examples
 
-**Would you like me to help you run through the first release process now?**
+- **[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
 
-## All AI SDK Functions Supported
+### Additional Examples
 
-The library provides guarded versions of all AI SDK functions:
+- **[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
 
-```typescript
-import {
-  generateTextWithGuardrails,
-  generateObjectWithGuardrails,
-  streamTextWithGuardrails,
-  streamObjectWithGuardrails,
-  embedWithGuardrails,
-} from 'ai-sdk-guardrails';
+### Running Examples
 
-// Generate text with guardrails
-const textResult = await generateTextWithGuardrails(
-  { model, prompt: 'Hello' },
-  { inputGuardrails: [lengthLimit(100)] },
-);
-
-// Generate structured objects with guardrails
-const objectResult = await generateObjectWithGuardrails(
-  { model, prompt: 'Create user', schema: userSchema },
-  { outputGuardrails: [schemaValidation(userSchema)] },
-);
-
-// Stream text with real-time guardrails
-const textStream = await streamTextWithGuardrails(
-  { model, prompt: 'Long response' },
-  { outputGuardrails: [outputLengthLimit(1000)] },
-);
-
-// Stream objects with guardrails
-const objectStream = await streamObjectWithGuardrails(
-  { model, prompt: 'Stream data', schema: dataSchema },
-  { outputGuardrails: [schemaValidation(dataSchema)] },
-);
-
-// Embed with input validation
-const embedResult = await embedWithGuardrails(
-  { model, value: 'Text to embed' },
-  { inputGuardrails: [piiDetector()] },
-);
+```bash
+# Install dependencies
+pnpm install
+
+# Interactive examples with better UX
+tsx examples/basic-composition.ts     # Start here - simplest example
+tsx examples/basic-guardrails.ts      # Core patterns with 8 examples
+tsx examples/business-logic.ts        # Business-specific rules
+tsx examples/llm-as-judge.ts          # AI-powered quality control
+
+# Or run specific examples directly
+tsx examples/basic-guardrails.ts 1    # Run first example only
+tsx examples/streaming-guardrails.ts 3 # Run third streaming example
 ```
 
-## TypeScript Support
+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.
 
-Full TypeScript support with intelligent type inference:
+## Architecture Overview
 
-```typescript
-// Types are automatically inferred
-const result = await generateTextWithGuardrails(
-  {
-    model: openai('gpt-4-turbo'),
-    prompt: 'Hello',
-  },
-  {
-    inputGuardrails: [
-      /* your guardrails */
-    ],
-  },
-);
+The library leverages the Vercel AI SDK's middleware architecture to provide composable guardrails that integrate seamlessly with your existing AI applications:
 
-// result is fully typed as GenerateTextResult
-console.log(result.text);
-console.log(result.usage);
-console.log(result.finishReason);
+```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
 ```
 
-## Examples
+### Middleware Execution Flow
 
-Explore our comprehensive examples that demonstrate real-world usage patterns:
+The guardrails execute in a specific order to maximize efficiency and ensure quality:
 
-- **[Basic Guardrails](examples/basic-guardrails.ts)** - Simple input/output validation with math homework detection
-- **[Streaming Guardrails](examples/streaming-guardrails.ts)** - Real-time stream protection with content filtering
-- **[Object Guardrails](examples/object-guardrails.ts)** - Schema validation and custom object validation
-- **[Autoevals Integration](examples/autoevals-guardrails.ts)** - AI quality evaluation with factuality checking
-- **[Kitchen Sink](examples/kitchen-sink.ts)** - Advanced patterns, composition, and LLM-as-judge
+```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
+```
 
-Each example is fully functional and demonstrates different aspects of the library with practical use cases.
+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
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! Please open issues and pull requests on [GitHub](https://github.com/jagreehal/ai-sdk-guardrails).
 
 ## License
 
 MIT © [Jag Reehal](https://github.com/jagreehal)
-
----
-
-Built with ❤️ for the AI community. Star the repo if you find it helpful!