ai-sdk-guardrails/dist/index.d.cts

Input and output guardrails middleware for Vercel AI SDK.

import { I as InputGuardrail, O as OutputGuardrail, a as InputGuardrailContext, G as GuardrailResult, b as OutputGuardrailContext, c as InputGuardrailsMiddlewareConfig, d as OutputGuardrailsMiddlewareConfig } from './types-B9h_0Gyl.cjs';
export { e as GuardrailsParams } from './types-B9h_0Gyl.cjs';
import { LanguageModelV2, LanguageModelV2Middleware } from '@ai-sdk/provider';
export { LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Middleware, LanguageModelV2StreamPart } from '@ai-sdk/provider';
import 'ai';

/**
 * Base class for all guardrails-related errors.
 * Provides a foundation for the hierarchical error system.
 */
declare abstract class GuardrailsError extends Error {
    abstract readonly name: string;
    abstract readonly code: string;
    readonly timestamp: Date;
    readonly metadata: Record<string, unknown>;
    constructor(message: string, metadata?: Record<string, unknown>);
    /**
     * Convert the error to a serializable object for logging/reporting
     */
    toJSON(): {
        name: string;
        code: string;
        message: string;
        timestamp: string;
        metadata: Record<string, unknown>;
        stack: string | undefined;
    };
    /**
     * Check if this error is of a specific type
     */
    is<T extends GuardrailsError>(errorClass: new (...args: any[]) => T): this is T;
}
/**
 * Thrown when guardrail validation fails
 */
declare class GuardrailValidationError extends GuardrailsError {
    readonly name = "GuardrailValidationError";
    readonly code = "GUARDRAIL_VALIDATION_FAILED";
    readonly guardrailName: string;
    readonly validationErrors: ValidationError[];
    constructor(guardrailName: string, validationErrors: ValidationError[], metadata?: Record<string, unknown>);
}
/**
 * Thrown when guardrail execution encounters an error
 */
declare class GuardrailExecutionError extends GuardrailsError {
    readonly name = "GuardrailExecutionError";
    readonly code = "GUARDRAIL_EXECUTION_FAILED";
    readonly guardrailName: string;
    readonly originalError?: Error;
    constructor(guardrailName: string, originalError?: Error, metadata?: Record<string, unknown>);
}
/**
 * Thrown when a guardrail times out during execution
 */
declare class GuardrailTimeoutError extends GuardrailsError {
    readonly name = "GuardrailTimeoutError";
    readonly code = "GUARDRAIL_TIMEOUT";
    readonly guardrailName: string;
    readonly timeoutMs: number;
    constructor(guardrailName: string, timeoutMs: number, metadata?: Record<string, unknown>);
}
/**
 * Thrown when guardrail configuration is invalid
 */
declare class GuardrailConfigurationError extends GuardrailsError {
    readonly name = "GuardrailConfigurationError";
    readonly code = "GUARDRAIL_CONFIG_INVALID";
    readonly configPath?: string;
    readonly configErrors: string[];
    constructor(configErrors: string[], configPath?: string, metadata?: Record<string, unknown>);
}
/**
 * Thrown when input to guardrails is blocked/rejected
 */
declare class InputBlockedError extends GuardrailsError {
    readonly name = "InputBlockedError";
    readonly code = "INPUT_BLOCKED";
    readonly blockedGuardrails: Array<{
        name: string;
        message: string;
        severity: 'low' | 'medium' | 'high' | 'critical';
    }>;
    constructor(blockedGuardrails: InputBlockedError['blockedGuardrails'], metadata?: Record<string, unknown>);
}
/**
 * Thrown when output from AI model is blocked/rejected
 */
declare class OutputBlockedError extends GuardrailsError {
    readonly name = "OutputBlockedError";
    readonly code = "OUTPUT_BLOCKED";
    readonly blockedGuardrails: Array<{
        name: string;
        message: string;
        severity: 'low' | 'medium' | 'high' | 'critical';
    }>;
    constructor(blockedGuardrails: OutputBlockedError['blockedGuardrails'], metadata?: Record<string, unknown>);
}
/**
 * Thrown when middleware encounters an error
 */
declare class MiddlewareError extends GuardrailsError {
    readonly name = "MiddlewareError";
    readonly code = "MIDDLEWARE_ERROR";
    readonly middlewareType: 'input' | 'output';
    readonly phase: 'transform' | 'wrap' | 'execute';
    readonly originalError?: Error;
    constructor(middlewareType: 'input' | 'output', phase: 'transform' | 'wrap' | 'execute', originalError?: Error, metadata?: Record<string, unknown>);
}
/**
 * Individual validation error within a guardrail
 */
interface ValidationError {
    field?: string;
    message: string;
    code?: string;
    value?: unknown;
}
/**
 * Utility function to check if an error is a guardrails error
 */
declare function isGuardrailsError(error: unknown): error is GuardrailsError;
/**
 * Utility function to extract error information for logging
 */
declare function extractErrorInfo(error: unknown): {
    name: string;
    message: string;
    code?: string;
    metadata?: Record<string, unknown>;
};

declare function createInputGuardrail(name: string, description: string, execute: InputGuardrail['execute']): InputGuardrail;
declare function createOutputGuardrail(name: string, execute: OutputGuardrail['execute']): OutputGuardrail;

/**
 * Creates a well-structured input guardrail with enhanced metadata
 * @param guardrail - The guardrail configuration
 * @returns Enhanced input guardrail with automatic metadata injection
 */
declare function defineInputGuardrail(guardrail: InputGuardrail): InputGuardrail;
/**
 * Executes input guardrails with enhanced performance monitoring and error handling
 * @param guardrails - Array of input guardrails to execute
 * @param params - Parameters for guardrail execution
 * @param options - Execution options
 * @returns Promise resolving to array of guardrail results
 */
declare function executeInputGuardrails(guardrails: InputGuardrail[], params: InputGuardrailContext, options?: {
    /** Execute guardrails in parallel (default: true) */
    parallel?: boolean;
    /** Maximum execution time in milliseconds */
    timeout?: number;
    /** Whether to continue on first failure */
    continueOnFailure?: boolean;
    /** Logging level */
    logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
}): Promise<GuardrailResult[]>;
/**
 * Creates a well-structured output guardrail with enhanced metadata
 * @param guardrail - The guardrail configuration
 * @returns Enhanced output guardrail with automatic metadata injection
 */
declare function defineOutputGuardrail(guardrail: OutputGuardrail): OutputGuardrail;
/**
 * Executes output guardrails with enhanced performance monitoring and error handling
 * @param guardrails - Array of output guardrails to execute
 * @param params - Parameters for guardrail execution
 * @param options - Execution options
 * @returns Promise resolving to array of guardrail results
 */
declare function executeOutputGuardrails(guardrails: OutputGuardrail[], params: OutputGuardrailContext, options?: {
    /** Execute guardrails in parallel (default: true) */
    parallel?: boolean;
    /** Maximum execution time in milliseconds */
    timeout?: number;
    /** Whether to continue on first failure */
    continueOnFailure?: boolean;
    /** Logging level */
    logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
}): Promise<GuardrailResult[]>;
/**
 * Wraps a language model with input guardrails using AI SDK 5 patterns
 * @param model - The language model to wrap
 * @param guardrails - Array of input guardrails to apply
 * @param options - Optional configuration for guardrail execution
 * @returns Wrapped language model with input guardrails
 *
 * @example
 * ```typescript
 * import { openai } from '@ai-sdk/openai';
 * import { wrapWithInputGuardrails } from 'ai-sdk-guardrails';
 *
 * const guardedModel = wrapWithInputGuardrails(
 *   openai('gpt-4o'),
 *   [myInputGuardrail],
 *   { throwOnBlocked: true }
 * );
 * ```
 */
declare function wrapWithInputGuardrails(model: LanguageModelV2, guardrails: InputGuardrail[], options?: Omit<InputGuardrailsMiddlewareConfig, 'inputGuardrails'>): LanguageModelV2;
/**
 * Wraps a language model with output guardrails using AI SDK 5 patterns
 * @param model - The language model to wrap
 * @param guardrails - Array of output guardrails to apply
 * @param options - Optional configuration for guardrail execution
 * @returns Wrapped language model with output guardrails
 *
 * @example
 * ```typescript
 * import { openai } from '@ai-sdk/openai';
 * import { wrapWithOutputGuardrails } from 'ai-sdk-guardrails';
 *
 * const guardedModel = wrapWithOutputGuardrails(
 *   openai('gpt-4o'),
 *   [myOutputGuardrail],
 *   { throwOnBlocked: true }
 * );
 * ```
 */
declare function wrapWithOutputGuardrails(model: LanguageModelV2, guardrails: OutputGuardrail[], options?: Omit<OutputGuardrailsMiddlewareConfig, 'outputGuardrails'>): LanguageModelV2;
/**
 * Wraps a language model with both input and output guardrails using AI SDK 5 patterns
 * @param model - The language model to wrap
 * @param config - Configuration for both input and output guardrails
 * @returns Wrapped language model with both input and output guardrails
 *
 * @example
 * ```typescript
 * import { openai } from '@ai-sdk/openai';
 * import { wrapWithGuardrails } from 'ai-sdk-guardrails';
 *
 * const guardedModel = wrapWithGuardrails(openai('gpt-4o'), {
 *   inputGuardrails: [myInputGuardrail],
 *   outputGuardrails: [myOutputGuardrail],
 *   throwOnBlocked: true
 * });
 * ```
 */
declare function wrapWithGuardrails(model: LanguageModelV2, config: {
    inputGuardrails?: InputGuardrail[];
    outputGuardrails?: OutputGuardrail[];
    throwOnBlocked?: boolean;
    executionOptions?: {
        parallel?: boolean;
        timeout?: number;
        continueOnFailure?: boolean;
        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
    };
    onInputBlocked?: InputGuardrailsMiddlewareConfig['onInputBlocked'];
    onOutputBlocked?: OutputGuardrailsMiddlewareConfig['onOutputBlocked'];
}): LanguageModelV2;
/**
 * Creates an input guardrails middleware that executes before AI calls
 * Follows AI SDK 5 middleware patterns
 *
 * @internal Advanced API - Use wrapWithInputGuardrails() or wrapWithGuardrails() for simpler usage
 * @param config - Input guardrails configuration
 * @returns AI SDK middleware that executes input guardrails
 */
declare function createInputGuardrailsMiddleware(config: InputGuardrailsMiddlewareConfig): LanguageModelV2Middleware;
/**
 * Creates an output guardrails middleware that executes after AI calls
 * Follows AI SDK 5 middleware patterns
 *
 * @internal Advanced API - Use wrapWithOutputGuardrails() or wrapWithGuardrails() for simpler usage
 * @param config - Output guardrails configuration
 * @returns AI SDK middleware that executes output guardrails
 */
declare function createOutputGuardrailsMiddleware(config: OutputGuardrailsMiddlewareConfig): LanguageModelV2Middleware;

export { GuardrailConfigurationError, GuardrailExecutionError, GuardrailResult, GuardrailTimeoutError, GuardrailValidationError, GuardrailsError, InputBlockedError, InputGuardrail, InputGuardrailsMiddlewareConfig, MiddlewareError, OutputBlockedError, OutputGuardrail, OutputGuardrailsMiddlewareConfig, createInputGuardrail, createInputGuardrailsMiddleware, createOutputGuardrail, createOutputGuardrailsMiddleware, defineInputGuardrail, defineOutputGuardrail, executeInputGuardrails, executeOutputGuardrails, extractErrorInfo, isGuardrailsError, wrapWithGuardrails, wrapWithInputGuardrails, wrapWithOutputGuardrails };