cyber-mysql-openai/dist/agent/cyberMySQLOpenAI.d.ts

Intelligent natural language to SQL translator with self-correction capabilities using OpenAI and MySQL

import { CyberMySQLOpenAIConfig, TranslationResult, SQLResult, NaturalResponseOptions, CacheStats, QueryStreamChunk } from "../types";
import { SupportedLanguage } from "../utils/i18n";
import { QueryRecord } from "../utils/queryHistory";
/**
 * Clase principal que proporciona la funcionalidad para traducir
 * lenguaje natural a SQL y ejecutar consultas
 */
export declare class CyberMySQLOpenAI {
    private openai;
    private dbManager;
    private logger;
    private responseFormatter;
    private maxReflections;
    private openaiModel;
    private lightModel;
    private i18n;
    private cache;
    private cacheEnabled;
    private schemaContext;
    private mode;
    private cachedSchema;
    private schemaCachedAt;
    private schemaTTL;
    private queryHistory;
    /**
     * Constructor de la clase CyberMySQLOpenAI
     * @param config - Configuración de la librería
     */
    constructor(config?: Partial<CyberMySQLOpenAIConfig>);
    /**
     * Procesa una consulta en lenguaje natural, la traduce a SQL y la ejecuta
     * @param prompt - Consulta en lenguaje natural
     * @param options - Opciones adicionales
     * @returns Resultado de la consulta
     */
    query(prompt: string, options?: NaturalResponseOptions): Promise<TranslationResult>;
    /**
     * Procesa una consulta en lenguaje natural devolviendo un generador asíncrono
     * para consumo de eventos y texto en tiempo real (streaming)
     * @param prompt - Consulta en lenguaje natural
     * @param options - Opciones adicionales
     * @returns Generador asíncrono de eventos de consulta
     */
    queryStream(prompt: string, options?: NaturalResponseOptions): AsyncGenerator<QueryStreamChunk, TranslationResult, unknown>;
    /**
     * Ejecuta una consulta SQL directamente
     * @param sql - Consulta SQL
     * @param options - Opciones adicionales
     * @returns Resultado de la consulta
     */
    executeSQL(sql: string, options?: NaturalResponseOptions): Promise<SQLResult>;
    /**
     * Cierra la conexión a la base de datos
     */
    close(): Promise<void>;
    /**
     * Cambia el idioma de las respuestas
     * @param language - Idioma a establecer ('es' | 'en')
     */
    setLanguage(language: SupportedLanguage): void;
    /**
     * Obtiene el idioma actual
     * @returns Idioma actual
     */
    getLanguage(): SupportedLanguage;
    /**
     * Genera SQL a partir de lenguaje natural usando OpenAI
     * Intenta usar function calling para respuestas estructuradas;
     * si el modelo no lo soporta, cae al modo texto con sqlCleaner.
     */
    private generateSQL;
    /**
     * Construye la descripción comprimida del schema.
     * Formato: "tabla: col1* col2 col3→ref_tabla" (~20 tokens/tabla vs ~60 antes)
     * donde * = PRIMARY KEY, →ref = FK a otra tabla
     */
    private buildSchemaDescription;
    /**
     * Construye la sección de relaciones FK para el prompt
     */
    private buildRelationshipsSection;
    /**
     * Construye la sección de ejemplos few-shot para el prompt
     */
    private buildExamplesSection;
    /**
     * Intenta corregir una consulta SQL fallida mediante reflexión
     * @param prompt - Consulta original en lenguaje natural
     * @param sql - Consulta SQL que falló
     * @param errorMessage - Mensaje de error
     * @param schema - Esquema de la base de datos
     * @param requestId - ID de la solicitud para logging
     * @returns Resultado después de intentar corregir
     */
    /**
     * Extrae los nombres de tablas mencionados en una consulta SQL.
     * Se usa para filtrar el schema y no re-enviarlo completo en la reflexión.
     */
    private extractTablesFromSQL;
    private levenshtein;
    private reflectAndFix;
    /**
     * Genera una reflexión sobre un error en una consulta SQL.
     * Usa function calling cuando está disponible, con fallback a texto.
     */
    private generateReflection;
    /**
     * Genera un hash del esquema de la base de datos para usar como clave de cache
     * @param schema - Esquema de la base de datos
     * @returns Hash del esquema
     */
    private generateSchemaHash;
    /**
     * Obtiene estadísticas del cache
     * @returns Estadísticas del cache o null si está deshabilitado
     */
    getCacheStats(): CacheStats | null;
    /**
     * Limpia el cache completamente
     */
    clearCache(): void;
    /**
     * Invalida entradas del cache relacionadas con una tabla específica
     * @param tableName - Nombre de la tabla
     * @returns Número de entradas invalidadas
     */
    invalidateCacheByTable(tableName: string): number;
    /**
     * Habilita o deshabilita el cache dinámicamente
     * @param enabled - Estado del cache
     */
    setCacheEnabled(enabled: boolean): void;
    /**
     * Verifica si el cache está habilitado
     * @returns Estado del cache
     */
    isCacheEnabled(): boolean;
    /**
     * Obtiene el esquema de la base de datos con cache TTL
     */
    private getSchemaWithCache;
    /**
     * Fuerza el refresco del schema cacheado
     */
    refreshSchema(): void;
    /**
     * Construye la sección de instrucciones personalizadas para los prompts
     */
    private buildCustomInstructionsSection;
    /**
     * Construye la instrucción de estilo de respuesta para los prompts
     */
    private buildResponseStyleInstruction;
    /**
     * Acumula el uso de tokens de una respuesta de OpenAI
     */
    private accumulateTokens;
    /**
     * Estima el costo en USD basado en el modelo y la cantidad de tokens.
     * Precios por 1M de tokens (actualizados a Feb 2025).
     */
    private estimateTokenCost;
    /**
     * Obtiene el historial de ejecución de consultas
     * @param limit - Número máximo de registros a devolver
     */
    getQueryHistory(limit?: number): QueryRecord[];
    /**
     * Obtiene estadísticas sobre la ejecución de consultas
     */
    getQueryStats(): {
        totalQueries: number;
        successfulQueries: number;
        failedQueries: number;
        averageExecutionTime: number;
        cacheHitRate: number;
        totalTokensUsed: number;
    };
    /**
     * Limpia el historial de consultas
     */
    clearQueryHistory(): void;
    /**
     * Exporta el historial de consultas como JSON
     */
    exportQueryHistory(): string;
}
export default CyberMySQLOpenAI;