openguardrails/dist/client.d.ts

An LLM-based context-aware AI guardrail capable of understanding conversation context for security, safety and data leakage detection.

import { OpenGuardrailsConfig, GuardrailResponse } from './types';
/**
 * OpenGuardrails Client - Context-aware AI Guardrails based on LLM
 *
 * This client provides a simple interface for interacting with the OpenGuardrails API.
 * The guardrails use context-aware technology to understand the conversation context and perform security checks.
 *
 * @example
 *
 * ```typescript
 * const client = new OpenGuardrails({ apiKey: "your-api-key" });
 *
 * // Detect user input
 * const result = await client.checkPrompt("User question");
 *
 * // Detect output content (based on context)
 * const result = await client.checkResponseCtx("User question", "Assistant answer");
 *
 * // Detect conversation context
 * const messages = [
 *   { role: "user", content: "Question" },
 *   { role: "assistant", content: "Answer" }
 * ];
 * const result = await client.checkConversation(messages);
 * console.log(result.overall_risk_level); // "high_risk/medium_risk/low_risk/no_risk"s
 * console.log(result.suggest_action); // "pass/reject/replace"
 * ```
 */
export declare class OpenGuardrails {
    private client;
    private maxRetries;
    constructor(config: OpenGuardrailsConfig);
    /**
     * Create a default response with no risk
     */
    private createSafeResponse;
    /**
     * 检测用户输入的安全性
     *
     * @param content The user input content to be detected
     * @param userId 可选，租户AI应用的用户ID，用于用户级别的风险控制和审计追踪
     * @returns 检测结果，格式为：
     * ```
     * {
     *   "id": "guardrails-xxx",
     *   "result": {
     *     "compliance": {
     *       "risk_level": "high_risk/medium_risk/low_risk/no_risk",
     *       "categories": ["violent crime", "sensitive political topics"]
     *     },
     *     "security": {
     *       "risk_level": "high_risk/medium_risk/low_risk/no_risk",
     *       "categories": ["prompt injection"]
     *     }
     *   },
     *   "overall_risk_level": "high_risk/medium_risk/low_risk/no_risk",
     *   "suggest_action": "pass/reject/replace",
     *   "suggest_answer": "Suggested answer content"
     * }
     * ```
     *
     * @throws {ValidationError} Invalid input parameters
     * @throws {AuthenticationError} Authentication failed
     * @throws {RateLimitError} Exceeded rate limit
     * @throws {OpenGuardrailsError} Other API errors
     *
     * @example
     * ```typescript
     * const result = await client.checkPrompt("I want to learn programming");
     * console.log(result.overall_risk_level); // "no_risk"
     * console.log(result.suggest_action); // "pass"
     * console.log(result.result.compliance.risk_level); // "no_risk"
     *
     * // Pass user ID for tracking
     * const result = await client.checkPrompt("我想学习编程", "user-123");
     * ```
     */
    checkPrompt(content: string, userId?: string): Promise<GuardrailResponse>;
    /**
     * Detect conversation context security - context-aware detection
     *
     * This is the core function of the guardrails, which can understand the complete conversation context for security detection.
     * Instead of detecting each message separately, it analyzes the security of the entire conversation.
     *
     * @param messages Conversation message list, containing the complete conversation between user and assistant, each message contains role('user' or 'assistant') and content
     * @param model The model name used
     * @param userId Optional, the user ID of the tenant AI application, used for user-level risk control and audit tracking
     * @returns The detection result based on the conversation context, the format is the same as checkPrompt
     *
     * @example
     * ```typescript
     * // Detect the security of the conversation between user and assistant
     * const messages = [
     *   { role: "user", content: "User question" },
     *   { role: "assistant", content: "Assistant answer" }
     * ];
     * const result = await client.checkConversation(messages);
     * console.log(result.overall_risk_level); // "no_risk"
     * console.log(result.suggest_action); // The suggestion based on the conversation context
     *
     * // Pass user ID for tracking
     * const result = await client.checkConversation(messages, 'OpenGuardrails-Text', "user-123");
     * ```
     */
    checkConversation(messages: Array<{
        role: string;
        content: string;
    }>, model?: string, userId?: string): Promise<GuardrailResponse>;
    /**
     * Detect the security of user input and model output - context-aware detection
     *
     * This is the core function of the guardrails, which can understand the complete conversation context for security detection.
     * The guardrails will detect whether the model output is safe and compliant based on the context of the user question.
     *
     * @param prompt The user input text content, used to make the guardrails understand the context semantic
     * @param response The model output text content, the actual detection object
     * @param userId Optional, the user ID of the tenant AI application, used for user-level risk control and audit tracking
     * @returns The detection result based on the context, the format is the same as checkPrompt
     *
     * @throws {ValidationError} Invalid input parameters
     * @throws {AuthenticationError} Authentication failed
     * @throws {RateLimitError} Exceeded rate limit
     * @throws {OpenGuardrailsError} Other API errors
     *
     * @example
     * ```typescript
     * const result = await client.checkResponseCtx(
     *   "Cooking",
     *   "I can teach you how to cook simple home-cooked meals"
     * );
     * console.log(result.overall_risk_level); // "no_risk"
     * console.log(result.suggest_action); // "pass"
     *
     * // 传递用户ID用于追踪
     * const result = await client.checkResponseCtx(
     *   "Cooking",
     *   "I can teach you how to cook simple home-cooked meals",
     *   "user-123"
     * );
     * ```
     */
    checkResponseCtx(prompt: string, response: string, userId?: string): Promise<GuardrailResponse>;
    /**
     * Encode the image to base64 format
     */
    private encodeBase64FromPath;
    /**
     * Detect the security of text prompt and image - multi-modal detection
     *
     * Combine the text semantic and image content for security detection.
     *
     * @param prompt Text prompt (can be empty)
     * @param image The local path or HTTP(S) link of the image file (cannot be empty)
     * @param model The model name used, default is the multi-modal model
     * @param userId Optional, the user ID of the tenant AI application, used for user-level risk control and audit tracking
     * @returns The detection result
     *
     * @throws {ValidationError} Invalid input parameters
     * @throws {AuthenticationError} Authentication failed
     * @throws {RateLimitError} Exceeded rate limit
     * @throws {OpenGuardrailsError} Other API errors
     *
     * @example
     * ```typescript
     * // Detect the local image
     * const result = await client.checkPromptImage("Is this image safe?", "/path/to/image.jpg");
     * // Detect the network image
     * const result = await client.checkPromptImage("", "https://example.com/image.jpg");
     * console.log(result.overall_risk_level);
     *
     * // Pass user ID for tracking
     * const result = await client.checkPromptImage("这个图片安全吗？", "/path/to/image.jpg", 'OpenGuardrails-VL', "user-123");
     * ```
     */
    checkPromptImage(prompt: string, image: string, model?: string, userId?: string): Promise<GuardrailResponse>;
    /**
     * Detect the security of text prompt and multiple images - multi-modal detection
     *
     * Combine the text semantic and multiple image content for security detection.
     *
     * @param prompt Text prompt (can be empty)
     * @param images The local path or HTTP(S) link list of the image file (cannot be empty)
     * @param model The model name used, default is the multi-modal model
     * @param userId Optional, the user ID of the tenant AI application, used for user-level risk control and audit tracking
     * @returns The detection result
     *
     * @throws {ValidationError} Invalid input parameters
     * @throws {AuthenticationError} Authentication failed
     * @throws {RateLimitError} Exceeded rate limit
     * @throws {OpenGuardrailsError} Other API errors
     *
     * @example
     * ```typescript
     * const images = ["/path/to/image1.jpg", "https://example.com/image2.jpg"];
     * const result = await client.checkPromptImages("Are these images safe?", images);
     * console.log(result.overall_risk_level);
     *
     * // Pass user ID for tracking
     * const result = await client.checkPromptImages("这些图片安全吗？", images, 'OpenGuardrails-VL', "user-123");
     * ```
     */
    checkPromptImages(prompt: string, images: string[], model?: string, userId?: string): Promise<GuardrailResponse>;
    /**
     * Check the health status of the API service
     */
    healthCheck(): Promise<Record<string, any>>;
    /**
     * Get the list of available models
     */
    getModels(): Promise<Record<string, any>>;
    /**
     * Send HTTP request
     */
    private makeRequest;
    /**
     * Sleep function
     */
    private sleep;
}
/**
 * Extended methods for GuardrailResponse
 */
export declare class GuardrailResponseHelper {
    /**
     * Check if the content is safe
     */
    static isSafe(response: GuardrailResponse): boolean;
    /**
     * Check if the content is blocked
     */
    static isBlocked(response: GuardrailResponse): boolean;
    /**
     * Check if there is a substitute
     */
    static hasSubstitute(response: GuardrailResponse): boolean;
    /**
     * Get all risk categories
     */
    static getAllCategories(response: GuardrailResponse): string[];
}
//# sourceMappingURL=client.d.ts.map