ai-sdk-guardrails 5.1.0 → 5.3.0

package/README.md

@@ -7,10 +7,10 @@ Add guardrails to your AI applications in one line of code. Block PII, prevent p
 [![npm version](https://img.shields.io/npm/v/ai-sdk-guardrails.svg?logo=npm&label=npm)](https://www.npmjs.com/package/ai-sdk-guardrails)
 [![downloads](https://img.shields.io/npm/dw/ai-sdk-guardrails.svg?label=downloads)](https://www.npmjs.com/package/ai-sdk-guardrails)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/ai-sdk-guardrails.svg?label=minzipped)](https://bundlephobia.com/package/ai-sdk-guardrails)
-[![license](https://img.shields.io/npm/l/ai-sdk-guardrails.svg?label=license)](./LICENSE)
+[![license](https://img.shields.io/npm/l/ai-sdk-guardrails.svg?label=license)](../../LICENSE)
 ![types](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript&logoColor=white)
 
-![Guardrails Demo](./media/guardrail-example.gif)
+![Guardrails Demo](../../media/guardrail-example.gif)
 
 ## Drop-in Guardrails for any AI model
 
@@ -39,7 +39,7 @@ npm install ai-sdk-guardrails
 
 **Don't want to write code?** Use our visual wizard to configure guardrails:
 
-1. **Open the wizard**: [wizard-prototype/index.html](./wizard-prototype/index.html)
+1. **Open the wizard**: [wizard-prototype/index.html](../../wizard-prototype/index.html)
 2. **Choose your use case**: Content moderation, data protection, quality assurance, or security
 3. **Select guardrails**: Pick from 40+ built-in guardrails
 4. **Configure settings**: Adjust thresholds and parameters with sliders and toggles
@@ -672,9 +672,9 @@ const model = withGuardrails(openai('gpt-4o'), {
 
 See complete examples:
 
-- [Production MCP Configuration](./examples/44-production-mcp-config.ts)
-- [MCP Security Test Suite](./examples/41-mcp-security-test.ts)
-- [Enhanced Security Testing](./examples/43-enhanced-mcp-security-test.ts)
+- [Production MCP Configuration](../examples/44-production-mcp-config.ts)
+- [MCP Security Test Suite](../examples/41-mcp-security-test.ts)
+- [Enhanced Security Testing](../examples/43-enhanced-mcp-security-test.ts)
 
 ## Error Handling
 
@@ -744,50 +744,50 @@ See source for all built-in guardrails:
 
 ## Examples
 
-Browse 48+ runnable examples: [examples/README.md](./examples/README.md) |
+Browse 48+ runnable examples: [examples/README.md](../examples/README.md) |
 
 ### Quick Starts
 
-| Example                    | Description                     | File                                                                              |
-| -------------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
-| Simple combined protection | Minimal input and output setup  | [07a-simple-combined-protection.ts](./examples/07a-simple-combined-protection.ts) |
-| Auto retry on output       | Retry until output meets a rule | [32-auto-retry-output.ts](./examples/32-auto-retry-output.ts)                     |
-| LLM judge auto-retry       | Judge feedback drives retry     | [35-judge-auto-retry.ts](./examples/35-judge-auto-retry.ts)                       |
-| Weather assistant          | End-to-end input/output + retry | [33-blog-post-weather-assistant.ts](./examples/33-blog-post-weather-assistant.ts) |
+| Example                    | Description                     | File                                                                               |
+| -------------------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| Simple combined protection | Minimal input and output setup  | [07a-simple-combined-protection.ts](../examples/07a-simple-combined-protection.ts) |
+| Auto retry on output       | Retry until output meets a rule | [32-auto-retry-output.ts](../examples/32-auto-retry-output.ts)                     |
+| LLM judge auto-retry       | Judge feedback drives retry     | [35-judge-auto-retry.ts](../examples/35-judge-auto-retry.ts)                       |
+| Weather assistant          | End-to-end input/output + retry | [33-blog-post-weather-assistant.ts](../examples/33-blog-post-weather-assistant.ts) |
 
 ### Input Safety
 
-| Example            | Description                         | File                                                            |
-| ------------------ | ----------------------------------- | --------------------------------------------------------------- |
-| Input length limit | Enforce max input length            | [01-input-length-limit.ts](./examples/01-input-length-limit.ts) |
-| Blocked keywords   | Block specific terms                | [02-blocked-keywords.ts](./examples/02-blocked-keywords.ts)     |
-| PII detection      | Detect PII before calling the model | [03-pii-detection.ts](./examples/03-pii-detection.ts)           |
-| Rate limiting      | Simple per-user rate limit          | [13-rate-limiting.ts](./examples/13-rate-limiting.ts)           |
+| Example            | Description                         | File                                                             |
+| ------------------ | ----------------------------------- | ---------------------------------------------------------------- |
+| Input length limit | Enforce max input length            | [01-input-length-limit.ts](../examples/01-input-length-limit.ts) |
+| Blocked keywords   | Block specific terms                | [02-blocked-keywords.ts](../examples/02-blocked-keywords.ts)     |
+| PII detection      | Detect PII before calling the model | [03-pii-detection.ts](../examples/03-pii-detection.ts)           |
+| Rate limiting      | Simple per-user rate limit          | [13-rate-limiting.ts](../examples/13-rate-limiting.ts)           |
 
 ### Output Safety
 
-| Example                 | Description                         | File                                                                      |
-| ----------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
-| Output length check     | Require min/max output length       | [04-output-length-check.ts](./examples/04-output-length-check.ts)         |
-| Sensitive output filter | Filter secrets and PII in responses | [05-sensitive-output-filter.ts](./examples/05-sensitive-output-filter.ts) |
-| Hallucination detection | Flag uncertain factual claims       | [19-hallucination-detection.ts](./examples/19-hallucination-detection.ts) |
+| Example                 | Description                         | File                                                                       |
+| ----------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| Output length check     | Require min/max output length       | [04-output-length-check.ts](../examples/04-output-length-check.ts)         |
+| Sensitive output filter | Filter secrets and PII in responses | [05-sensitive-output-filter.ts](../examples/05-sensitive-output-filter.ts) |
+| Hallucination detection | Flag uncertain factual claims       | [19-hallucination-detection.ts](../examples/19-hallucination-detection.ts) |
 
 ### Streaming
 
-| Example           | Description                        | File                                                                              |
-| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
-| Streaming limits  | Apply limits in buffered streaming | [11-streaming-limits.ts](./examples/11-streaming-limits.ts)                       |
-| Streaming quality | Quality checks with streaming      | [12-streaming-quality.ts](./examples/12-streaming-quality.ts)                     |
-| Early termination | Stop streams early when blocked    | [28-streaming-early-termination.ts](./examples/28-streaming-early-termination.ts) |
+| Example           | Description                        | File                                                                               |
+| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
+| Streaming limits  | Apply limits in buffered streaming | [11-streaming-limits.ts](../examples/11-streaming-limits.ts)                       |
+| Streaming quality | Quality checks with streaming      | [12-streaming-quality.ts](../examples/12-streaming-quality.ts)                     |
+| Early termination | Stop streams early when blocked    | [28-streaming-early-termination.ts](../examples/28-streaming-early-termination.ts) |
 
 ### Advanced
 
-| Example                    | Description                   | File                                                                            |
-| -------------------------- | ----------------------------- | ------------------------------------------------------------------------------- |
-| Simple quality judge       | Cheaper model judges quality  | [15a-simple-quality-judge.ts](./examples/15a-simple-quality-judge.ts)           |
-| Secret leakage scan        | Scan responses for secrets    | [18-secret-leakage-scan.ts](./examples/18-secret-leakage-scan.ts)               |
-| SQL code safety            | Basic SQL safety checks       | [24-sql-code-safety.ts](./examples/24-sql-code-safety.ts)                       |
-| Role hierarchy enforcement | Enforce role rules in prompts | [23-role-hierarchy-enforcement.ts](./examples/23-role-hierarchy-enforcement.ts) |
+| Example                    | Description                   | File                                                                             |
+| -------------------------- | ----------------------------- | -------------------------------------------------------------------------------- |
+| Simple quality judge       | Cheaper model judges quality  | [15a-simple-quality-judge.ts](../examples/15a-simple-quality-judge.ts)           |
+| Secret leakage scan        | Scan responses for secrets    | [18-secret-leakage-scan.ts](../examples/18-secret-leakage-scan.ts)               |
+| SQL code safety            | Basic SQL safety checks       | [24-sql-code-safety.ts](../examples/24-sql-code-safety.ts)                       |
+| Role hierarchy enforcement | Enforce role rules in prompts | [23-role-hierarchy-enforcement.ts](../examples/23-role-hierarchy-enforcement.ts) |
 
 ## Migration from v3.x
 
@@ -837,4 +837,4 @@ Issues and PRs are welcome.
 
 ## License
 
-MIT © Jag Reehal. See [LICENSE](./LICENSE) for details.
+MIT © Jag Reehal. See [LICENSE](../../LICENSE) for details.

package/dist/{chunk-OP5XB2DJ.js → chunk-2QL3CFHU.js}

@@ -141,7 +141,14 @@ var inputLengthLimit = (options) => {
         tripwireTriggered: currentLength > opts.maxLength,
         message: currentLength > opts.maxLength ? `Input ${unit} count ${currentLength} exceeds limit of ${opts.maxLength}` : void 0,
         severity: opts.severity,
-        metadata
+        metadata,
+        info: {
+          guardrailName: "input-length-limit",
+          currentLength,
+          maxLength: opts.maxLength,
+          countMethod: opts.countMethod,
+          unit
+        }
       };
     }
   );
@@ -179,7 +186,12 @@ var blockedWords = (options) => {
             metadata: createStandardMetadata("GR-IN-002", context, {
               allowlistMatched: true,
               blockedWords: opts.words
-            })
+            }),
+            info: {
+              guardrailName: "blocked-words",
+              allowlistMatched: true,
+              blockedWords: opts.words
+            }
           };
         }
       }
@@ -196,7 +208,13 @@ var blockedWords = (options) => {
         tripwireTriggered: !!blockedWord,
         message: blockedWord ? `Blocked word detected: ${blockedWord.word}` : void 0,
         severity: opts.severity,
-        metadata
+        metadata,
+        info: {
+          guardrailName: "blocked-words",
+          blockedWord: blockedWord?.word,
+          allWords: opts.words,
+          allowlist: opts.allowlist
+        }
       };
     }
   );
@@ -278,7 +296,14 @@ var rateLimiting = (options) => {
           ...metadata,
           ...opts.includeServerHints && { serverHints }
         },
-        suggestion: isRateLimited ? `Please wait ${Math.ceil(recommendedBackoff / 1e3)} seconds before making another request` : void 0
+        suggestion: isRateLimited ? `Please wait ${Math.ceil(recommendedBackoff / 1e3)} seconds before making another request` : void 0,
+        info: {
+          guardrailName: "rate-limiting",
+          currentCount: current.count,
+          maxRequests: opts.maxRequestsPerMinute,
+          isRateLimited,
+          timeUntilReset
+        }
       };
     }
   );
@@ -352,7 +377,13 @@ var profanityFilter = (options = {}) => {
         message: detectedProfanity ? `Profanity detected (${detectedProfanity.category}): ${detectedProfanity.word}` : void 0,
         severity: detectedProfanity?.severity || SEVERITY_LEVELS.HIGH,
         metadata,
-        suggestion: "Please use respectful and appropriate language"
+        suggestion: "Please use respectful and appropriate language",
+        info: {
+          guardrailName: "profanity-filter",
+          profaneWord: detectedProfanity?.word,
+          category: detectedProfanity?.category,
+          locale: opts.locale
+        }
       };
     }
   );
@@ -394,7 +425,12 @@ var customValidation = (options) => {
       tripwireTriggered: !isValid,
       message: isValid ? void 0 : opts.message || `Custom validation failed: ${reasonCode || "unknown reason"}`,
       severity: opts.severity,
-      metadata
+      metadata,
+      info: {
+        guardrailName: opts.name,
+        isValid,
+        reasonCode
+      }
     };
   });
 };
@@ -537,7 +573,13 @@ var promptInjectionDetector = (options = {}) => {
         message: confidence > threshold ? `Potential prompt injection detected (confidence: ${(confidence * 100).toFixed(1)}%): ${detectedPatterns.length} suspicious patterns found` : void 0,
         severity: confidence > 0.8 ? SEVERITY_LEVELS.CRITICAL : SEVERITY_LEVELS.HIGH,
         metadata,
-        suggestion: "Please rephrase your request without system instructions or role-playing elements"
+        suggestion: "Please rephrase your request without system instructions or role-playing elements",
+        info: {
+          guardrailName: "prompt-injection-detector",
+          confidence,
+          threshold,
+          detectedPatternsCount: detectedPatterns.length
+        }
       };
     }
   );
@@ -622,7 +664,12 @@ var piiDetector = () => createInputGuardrail(
       message: detectedPII.length > 0 ? `PII detected: ${detectedPII.map((pii) => `${pii.type} (${pii.matches.length})`).join(", ")}` : void 0,
       severity: SEVERITY_LEVELS.CRITICAL,
       metadata,
-      suggestion: "Please remove any personal information (emails, phone numbers, SSNs, etc.) from your input"
+      suggestion: "Please remove any personal information (emails, phone numbers, SSNs, etc.) from your input",
+      info: {
+        guardrailName: "pii-detector",
+        piiTypes: detectedPII.map((pii) => pii.type),
+        totalMatches
+      }
     };
   }
 );
@@ -658,7 +705,14 @@ var toxicityDetector = (threshold = 0.7) => createInputGuardrail(
         detectedWords,
         textLength: allText.length
       },
-      suggestion: "Please use respectful and constructive language"
+      suggestion: "Please use respectful and constructive language",
+      info: {
+        guardrailName: "toxicity-detector",
+        toxicityScore,
+        threshold,
+        detectedWords,
+        textLength: allText.length
+      }
     };
   }
 );
@@ -673,7 +727,12 @@ var mathHomeworkDetector = (options = {}) => {
     return createInputGuardrail(
       "math-homework-detector",
       "Math homework detection (disabled)",
-      () => ({ tripwireTriggered: false })
+      () => ({
+        tripwireTriggered: false,
+        info: {
+          guardrailName: "math-homework-detector"
+        }
+      })
     );
   }
   const mathKeywords = [
@@ -720,7 +779,13 @@ var mathHomeworkDetector = (options = {}) => {
             educationalContext: hasEducationalContext,
             allowedContext: hasAllowedContext,
             policy: "educational-use-allowed"
-          })
+          }),
+          info: {
+            guardrailName: "math-homework-detector",
+            educationalContext: hasEducationalContext,
+            allowedContext: hasAllowedContext,
+            policy: "educational-use-allowed"
+          }
         };
       }
       const keywordMatches = mathKeywords.filter(
@@ -742,6 +807,13 @@ var mathHomeworkDetector = (options = {}) => {
         message: isMathHomework ? "Math homework request detected" : void 0,
         severity,
         metadata,
+        info: {
+          guardrailName: "math-homework-detector",
+          isMathHomework,
+          keywordMatches: keywordMatches.length,
+          patternMatches: patternMatches.length,
+          strictMode
+        },
         suggestion: "Try asking about learning concepts instead of solving specific problems"
       };
     }
@@ -844,7 +916,12 @@ var codeGenerationLimiter = (options = {}) => {
           metadata: createStandardMetadata("GR-IN-008", context, {
             hasCodeRequest: false,
             mode: opts.mode
-          })
+          }),
+          info: {
+            guardrailName: "code-generation-limiter",
+            hasCodeRequest: false,
+            mode: opts.mode
+          }
         };
       }
       const detectedLanguages = [];
@@ -880,6 +957,13 @@ var codeGenerationLimiter = (options = {}) => {
         message: isBlocked ? `Code generation blocked for language(s): ${blockedLanguages.join(", ")}` : void 0,
         severity: opts.severity,
         metadata,
+        info: {
+          guardrailName: "code-generation-blocker",
+          isBlocked,
+          detectedLanguages: uniqueLanguages,
+          blockedLanguages,
+          mode: opts.mode
+        },
         suggestion: opts.mode === "deny" ? `Please avoid requesting code in these languages: ${opts.deniedLanguages?.join(", ")}` : `Please request code only in allowed languages: ${opts.allowedLanguages?.join(", ")}`
       };
     }
@@ -990,6 +1074,11 @@ var allowedToolsGuardrail = (options) => {
             allowedTools,
             deniedTools,
             detectionMethod: "none"
+          },
+          info: {
+            guardrailName: "allowed-tools-guardrail",
+            detectedTools: [],
+            detectionMethod: "none"
           }
         };
       }
@@ -1029,7 +1118,15 @@ var allowedToolsGuardrail = (options) => {
             naturalLanguageTools,
             textLength: allText.length
           },
-          suggestion: "Remove unauthorized tool calls or update the allowed tools configuration"
+          suggestion: "Remove unauthorized tool calls or update the allowed tools configuration",
+          info: {
+            guardrailName: "allowed-tools-guardrail",
+            detectedTools: allDetectedTools,
+            blockedTools,
+            violations,
+            allowedTools,
+            deniedTools
+          }
         };
       }
       return {
@@ -1041,6 +1138,11 @@ var allowedToolsGuardrail = (options) => {
           deniedTools,
           contextToolCalls,
           naturalLanguageTools
+        },
+        info: {
+          guardrailName: "allowed-tools-guardrail",
+          detectedTools: allDetectedTools,
+          allToolsAllowed: true
         }
       };
     }