ai-sdk-guardrails 5.0.1 → 5.1.0

package/README.md

@@ -1,6 +1,6 @@
 # AI SDK Guardrails
 
-**Safety and quality controls for Vercel AI SDK**
+## Safety and quality controls for Vercel AI SDK
 
 Add guardrails to your AI applications in one line of code. Block PII, prevent prompt injection, enforce output quality - while keeping your existing telemetry and observability stack intact.
 
@@ -35,6 +35,25 @@ await generateText({ model: safeModel, prompt: '...' });
 npm install ai-sdk-guardrails
 ```
 
+## 🧙‍♂️ No-Code Wizard (New!)
+
+**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)
+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
+5. **Copy generated code**: Get production-ready TypeScript code instantly
+
+**Perfect for:**
+
+- 🎯 **Non-technical users** who need AI safety
+- 🚀 **Quick prototyping** of guardrail configurations
+- 📚 **Learning** how to use the library
+- 👥 **Team onboarding** and training
+
+The wizard generates code that works out of the box - just copy, paste, and run!
+
 ## Why Guardrails Matter
 
 Real problems that guardrails solve:
@@ -367,6 +386,191 @@ const agent = withAgentGuardrails(
 const result = await agent.generate({ prompt: '...' });
 ```
 
+## Advanced Stopping Mechanisms
+
+Control exactly **when and how** guardrails stop execution with powerful, composable stopping mechanisms:
+
+### 1. AbortSignal-Based Stopping
+
+Clean, standard API for canceling AI operations:
+
+```ts
+import { createGuardrailAbortController } from 'ai-sdk-guardrails';
+
+const { signal, abortOnViolation } = createGuardrailAbortController();
+
+const model = withGuardrails(openai('gpt-4o'), {
+  outputGuardrails: [toxicityFilter()],
+  onOutputBlocked: abortOnViolation('critical'), // Abort on critical violations
+});
+
+// Signal will be aborted if critical violation detected
+await streamText({ model, prompt: '...', abortSignal: signal });
+```
+
+**Features:**
+
+- Standard AbortController API
+- Severity-based abortion (`'low' | 'medium' | 'high' | 'critical'`)
+- Custom abort conditions
+- Manual abortion support
+
+### 2. Stream Transform with Source-Level Stopping
+
+Stop streaming at the **source** (most efficient):
+
+```ts
+import { createGuardrailStreamTransform } from 'ai-sdk-guardrails';
+
+const result = streamText({
+  model,
+  prompt: 'Tell me a story',
+  experimental_transform: createGuardrailStreamTransform(
+    [toxicityFilter(), piiDetector()],
+    {
+      stopOnSeverity: 'high', // Stop on high/critical
+      checkInterval: 1, // Check every chunk
+      onViolation: (summary) => {
+        // Violation callback
+        console.log('Stopped:', summary);
+      },
+    },
+  ),
+});
+```
+
+**Modes:**
+
+- `createGuardrailStreamTransform` - Progressive checking (each chunk)
+- `createGuardrailStreamTransformBuffered` - Buffered checking (on flush)
+
+### 3. Token-Level Control
+
+Reduce overhead with smart token-based checking:
+
+```ts
+import {
+  createTokenBudgetTransform,
+  createTokenAwareGuardrailTransform,
+} from 'ai-sdk-guardrails';
+
+experimental_transform: [
+  // Hard token limit
+  createTokenBudgetTransform({
+    maxTokens: 1000,
+    onBudgetExceeded: (info) => console.log(info),
+  }),
+
+  // Check guardrails every N tokens (not every chunk!)
+  createTokenAwareGuardrailTransform([toxicityFilter()], {
+    checkEveryTokens: 50, // Check every 50 tokens
+    maxTokens: 1000, // Combined with budget
+    stopOnSeverity: 'high',
+  }),
+];
+```
+
+**Benefits:**
+
+- Reduce guardrail overhead by 80%+
+- Cost control with token budgets
+- Custom tokenizer support
+
+### 4. Adaptive Multi-Step Execution
+
+Self-correcting behavior across multi-step agent execution:
+
+```ts
+import {
+  createAdaptivePrepareStep,
+  type GuardrailViolation,
+} from 'ai-sdk-guardrails';
+
+const violations: GuardrailViolation[] = [];
+
+const agent = new Agent({
+  model,
+  tools: { search: searchTool },
+  prepareStep: createAdaptivePrepareStep({
+    violations,
+    escalateAfter: 3, // Stop after 3 violations
+    strategy: (violations) => ({
+      temperature: Math.max(0.1, 0.7 - violations.length * 0.1),
+      system: `${violations.length} violations detected. Be careful.`,
+    }),
+  }),
+});
+
+// Track violations
+withAgentGuardrails(agent, {
+  outputGuardrails: [toxicityFilter()],
+  onOutputBlocked: (summary, context, step) => {
+    violations.push({ step, summary });
+  },
+});
+```
+
+**Features:**
+
+- Progressive temperature reduction
+- Custom adaptive strategies
+- Escalation to auto-stop
+- Lookback window configuration
+
+### 5. Tool Execution Abortion
+
+Prevent dangerous tool execution before or during execution:
+
+```ts
+import { wrapToolWithAbortion } from 'ai-sdk-guardrails';
+
+const safeTool = wrapToolWithAbortion(
+  dangerousApiTool,
+  [urlValidator, paramValidator],
+  {
+    checkBefore: true, // Validate before execution
+    monitorDuring: true, // Monitor during execution
+    monitorInterval: 1000, // Check every second
+    checkInputDelta: true, // Monitor streaming inputs
+    abortOnSeverity: 'critical',
+  },
+);
+```
+
+**Protection:**
+
+- Pre-execution validation
+- Real-time monitoring
+- Streaming input checking
+- Manual abortion control
+
+### 6. Finish Reason & Metadata
+
+Better observability with proper finish reasons and metadata:
+
+```ts
+import { createFinishReasonEnhancement } from 'ai-sdk-guardrails';
+
+// Automatically set in middleware, or manually:
+const enhanced = createFinishReasonEnhancement(summary, result);
+
+console.log(enhanced.finishReason); // 'content_filter' for blocks
+console.log(enhanced.providerMetadata.guardrails);
+// {
+//   blocked: true,
+//   violations: [{ message: '...', severity: 'high', ... }],
+//   executionTime: 50,
+//   stats: { passed: 2, blocked: 1, failed: 0 }
+// }
+```
+
+**Features:**
+
+- Standard `content_filter` finish reason
+- Structured violation metadata
+- Execution statistics
+- Custom metadata preservation
+
 ## MCP Security Guardrails (Advanced)
 
 **Production-Ready**: Protect against the ["lethal trifecta" vulnerability](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) when using Model Context Protocol (MCP) tools.
@@ -540,7 +744,7 @@ 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
 
@@ -623,6 +827,10 @@ Changes:
 
 **Type-safe**: Rich TypeScript types and inference throughout.
 
+**Comprehensive**: 40+ built-in guardrails covering security, quality, compliance, and performance.
+
+**Advanced features**: Early detection, parallel execution, enhanced prompt injection detection, MCP security, and more.
+
 ## Contributing
 
 Issues and PRs are welcome.

package/dist/chunk-CB2WX5S7.js

@@ -0,0 +1,393 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/errors.ts
+var GuardrailsError = class extends Error {
+  timestamp;
+  metadata;
+  constructor(message, metadata = {}) {
+    super(message);
+    this.timestamp = /* @__PURE__ */ new Date();
+    this.metadata = metadata;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /**
+   * Convert the error to a serializable object for logging/reporting
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      timestamp: this.timestamp.toISOString(),
+      metadata: this.metadata,
+      stack: this.stack
+    };
+  }
+  /**
+   * Check if this error is of a specific type
+   */
+  is(errorClass) {
+    return this instanceof errorClass;
+  }
+};
+var GuardrailValidationError = class extends GuardrailsError {
+  name = "GuardrailValidationError";
+  code = "GUARDRAIL_VALIDATION_FAILED";
+  guardrailName;
+  validationErrors;
+  constructor(guardrailName, validationErrors, metadata = {}) {
+    const message = `Guardrail "${guardrailName}" validation failed: ${validationErrors.map((e) => e.message).join(", ")}`;
+    super(message, { ...metadata, guardrailName, validationErrors });
+    this.guardrailName = guardrailName;
+    this.validationErrors = validationErrors;
+  }
+};
+var GuardrailExecutionError = class extends GuardrailsError {
+  name = "GuardrailExecutionError";
+  code = "GUARDRAIL_EXECUTION_FAILED";
+  guardrailName;
+  originalError;
+  constructor(guardrailName, originalError, metadata = {}) {
+    const message = originalError ? `Guardrail "${guardrailName}" execution failed: ${originalError.message}` : `Guardrail "${guardrailName}" execution failed`;
+    super(message, {
+      ...metadata,
+      guardrailName,
+      originalError: originalError?.message
+    });
+    this.guardrailName = guardrailName;
+    this.originalError = originalError;
+  }
+};
+var GuardrailTimeoutError = class extends GuardrailsError {
+  name = "GuardrailTimeoutError";
+  code = "GUARDRAIL_TIMEOUT";
+  guardrailName;
+  timeoutMs;
+  constructor(guardrailName, timeoutMs, metadata = {}) {
+    const message = `Guardrail "${guardrailName}" timed out after ${timeoutMs}ms`;
+    super(message, { ...metadata, guardrailName, timeoutMs });
+    this.guardrailName = guardrailName;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var GuardrailConfigurationError = class extends GuardrailsError {
+  name = "GuardrailConfigurationError";
+  code = "GUARDRAIL_CONFIG_INVALID";
+  configPath;
+  configErrors;
+  constructor(configErrors, configPath, metadata = {}) {
+    const message = `Guardrail configuration error${configPath ? ` in ${configPath}` : ""}: ${configErrors.join(", ")}`;
+    super(message, { ...metadata, configPath, configErrors });
+    this.configPath = configPath;
+    this.configErrors = configErrors;
+  }
+};
+var GuardrailsInputError = class extends GuardrailsError {
+  name = "GuardrailsInputError";
+  code = "INPUT_BLOCKED";
+  blockedGuardrails;
+  constructor(blockedGuardrails, metadata = {}) {
+    const guardrailNames = blockedGuardrails.map((g) => g.name).join(", ");
+    const message = `Input blocked by guardrail${blockedGuardrails.length > 1 ? "s" : ""}: ${guardrailNames}`;
+    super(message, { ...metadata, blockedGuardrails });
+    this.blockedGuardrails = blockedGuardrails;
+  }
+};
+var GuardrailsOutputError = class extends GuardrailsError {
+  name = "GuardrailsOutputError";
+  code = "OUTPUT_BLOCKED";
+  blockedGuardrails;
+  constructor(blockedGuardrails, metadata = {}) {
+    const guardrailNames = blockedGuardrails.map((g) => g.name).join(", ");
+    const message = `Output blocked by guardrail${blockedGuardrails.length > 1 ? "s" : ""}: ${guardrailNames}`;
+    super(message, { ...metadata, blockedGuardrails });
+    this.blockedGuardrails = blockedGuardrails;
+  }
+};
+var MiddlewareError = class extends GuardrailsError {
+  name = "MiddlewareError";
+  code = "MIDDLEWARE_ERROR";
+  middlewareType;
+  phase;
+  originalError;
+  constructor(middlewareType, phase, originalError, metadata = {}) {
+    const message = originalError ? `${middlewareType} middleware ${phase} error: ${originalError.message}` : `${middlewareType} middleware ${phase} error`;
+    super(message, {
+      ...metadata,
+      middlewareType,
+      phase,
+      originalError: originalError?.message
+    });
+    this.middlewareType = middlewareType;
+    this.phase = phase;
+    this.originalError = originalError;
+  }
+};
+function isGuardrailsError(error) {
+  return error instanceof GuardrailsError;
+}
+function extractErrorInfo(error) {
+  if (isGuardrailsError(error)) {
+    return {
+      name: error.name,
+      message: error.message,
+      code: error.code,
+      metadata: error.metadata
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message
+    };
+  }
+  return {
+    name: "UnknownError",
+    message: String(error)
+  };
+}
+
+// src/core.ts
+function createInputGuardrail(name, description, execute) {
+  return { name, description, execute };
+}
+function createOutputGuardrail(name, execute) {
+  return { name, execute };
+}
+function createGenerateWithErrorHandling(generate, signal, onError, retryOnError, maxRetries) {
+  return async (params, attemptNum) => {
+    try {
+      return signal ? await generate(params, signal) : await generate(params);
+    } catch (error) {
+      onError?.(error, attemptNum);
+      if (retryOnError?.(error, attemptNum) && attemptNum <= maxRetries) {
+        throw error;
+      }
+      throw error;
+    }
+  };
+}
+function buildRetrySummary(attemptHistory, validationResult, isUsingEnhancedFeatures, maxRetries) {
+  const blockedResults = attemptHistory.filter((historyAttempt) => historyAttempt.blocked).map(() => ({
+    message: validationResult.message,
+    metadata: validationResult.metadata
+  }));
+  const summary = { blockedResults };
+  if (isUsingEnhancedFeatures) {
+    summary.totalAttempts = maxRetries + 1;
+    summary.attempts = [...attemptHistory];
+  }
+  return summary;
+}
+async function performInitialAttempt(params, generateFn, validate, onAttempt, maxRetries, retryOnError) {
+  const attemptHistory = [];
+  onAttempt?.({
+    attempt: 0,
+    totalAttempts: maxRetries + 1,
+    isRetry: false
+  });
+  try {
+    const result = await generateFn(params, 0);
+    const validationResult = await Promise.resolve(validate(result));
+    attemptHistory.push({
+      attempt: 0,
+      result,
+      blocked: validationResult.blocked
+    });
+    return { result, validationResult, attemptHistory };
+  } catch (error) {
+    if (!retryOnError?.(error, 0)) {
+      throw error;
+    }
+    return {
+      result: void 0,
+      validationResult: {
+        blocked: true,
+        message: `Generation error: ${error}`
+      },
+      attemptHistory
+    };
+  }
+}
+async function performBackoffWait(backoffMs, attempt, signal) {
+  const wait = typeof backoffMs === "function" ? backoffMs(attempt) : backoffMs ?? 0;
+  if (wait && wait > 0) {
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(resolve, wait);
+      signal?.addEventListener("abort", () => {
+        clearTimeout(timeout);
+        reject(new Error("Aborted during retry backoff"));
+      });
+    });
+  }
+  return;
+}
+async function retry(options) {
+  const {
+    generate,
+    params,
+    validate,
+    buildRetryParams,
+    maxRetries = 1,
+    backoffMs,
+    signal,
+    onAttempt,
+    retryOnError,
+    onError,
+    onExhausted = "return-last"
+  } = options;
+  signal?.throwIfAborted();
+  const generateFn = createGenerateWithErrorHandling(
+    generate,
+    signal,
+    onError,
+    retryOnError,
+    maxRetries
+  );
+  const {
+    result: initialResult,
+    validationResult,
+    attemptHistory
+  } = await performInitialAttempt(
+    params,
+    generateFn,
+    validate,
+    onAttempt,
+    maxRetries,
+    retryOnError
+  );
+  let result = initialResult;
+  let v = validationResult;
+  let lastParams = params;
+  let attempt = 0;
+  while (v.blocked && attempt < maxRetries) {
+    attempt++;
+    signal?.throwIfAborted();
+    const enhancedFeatures = !!(signal || onAttempt || retryOnError || onError || onExhausted !== "return-last");
+    const summary = buildRetrySummary(
+      attemptHistory,
+      v,
+      enhancedFeatures,
+      maxRetries
+    );
+    const nextParams = buildRetryParams({
+      summary,
+      originalParams: params,
+      lastParams,
+      lastResult: result
+    });
+    const wait = typeof backoffMs === "function" ? backoffMs(attempt) : backoffMs ?? 0;
+    onAttempt?.({
+      attempt,
+      totalAttempts: maxRetries + 1,
+      lastResult: result,
+      waitMs: wait,
+      isRetry: true
+    });
+    await performBackoffWait(backoffMs, attempt, signal);
+    lastParams = nextParams;
+    try {
+      result = await generateFn(lastParams, attempt);
+      v = await Promise.resolve(validate(result));
+      attemptHistory.push({
+        attempt,
+        result,
+        blocked: v.blocked,
+        waitMs: wait
+      });
+    } catch (error) {
+      if (!retryOnError?.(error, attempt)) {
+        throw error;
+      }
+      v = { blocked: true, message: `Generation error: ${error}` };
+    }
+  }
+  if (v.blocked && onExhausted === "throw") {
+    throw new Error(
+      `Retry exhausted after ${maxRetries} attempts: ${v.message}`
+    );
+  }
+  return result;
+}
+var retryHelpers = {
+  /**
+   * Increases max output tokens for retry attempts
+   */
+  increaseTokens: (increase = 200) => ({
+    lastParams
+  }) => ({
+    ...lastParams,
+    maxOutputTokens: Math.max(
+      400,
+      (lastParams.maxOutputTokens ?? 400) + increase
+    )
+  }),
+  /**
+   * Adds encouraging prompt for retry attempts
+   */
+  addEncouragingPrompt: (encouragement = "Please provide a more detailed and comprehensive response.") => ({
+    lastParams,
+    summary
+  }) => {
+    const basePrompt = Array.isArray(lastParams.prompt) ? lastParams.prompt : [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: String(lastParams.prompt || "") }
+        ]
+      }
+    ];
+    return {
+      ...lastParams,
+      prompt: [
+        ...basePrompt,
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: `${summary.blockedResults[0]?.message ? `Note: ${summary.blockedResults[0].message}.` : ""} ${encouragement}`
+            }
+          ]
+        }
+      ]
+    };
+  },
+  /**
+   * Combines token increase with encouraging prompt
+   */
+  improveResponse: (tokenIncrease = 200, encouragement) => (args) => {
+    const withTokens = retryHelpers.increaseTokens(tokenIncrease)(args);
+    const withEncouragement = retryHelpers.addEncouragingPrompt(
+      encouragement
+    )({ ...args, lastParams: withTokens });
+    return { ...withTokens, ...withEncouragement };
+  },
+  /**
+   * Simple parameter passthrough (no changes)
+   */
+  noChange: () => ({ lastParams }) => lastParams
+};
+
+export {
+  __require,
+  GuardrailsError,
+  GuardrailValidationError,
+  GuardrailExecutionError,
+  GuardrailTimeoutError,
+  GuardrailConfigurationError,
+  GuardrailsInputError,
+  GuardrailsOutputError,
+  MiddlewareError,
+  isGuardrailsError,
+  extractErrorInfo,
+  createInputGuardrail,
+  createOutputGuardrail,
+  retry,
+  retryHelpers
+};