hazo_llm_api 1.0.4 → 1.0.6

package/dist/lib/prompts/prompt_cache.js

@@ -0,0 +1,276 @@
+/**
+ * Prompt Cache Module
+ *
+ * Simple LRU cache for frequently accessed prompts.
+ * Reduces database queries for repeated prompt lookups.
+ */
+// =============================================================================
+// Cache Configuration
+// =============================================================================
+/** Default cache TTL in milliseconds (5 minutes) */
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Default maximum cache size */
+const DEFAULT_MAX_CACHE_SIZE = 100;
+// =============================================================================
+// Prompt Cache Implementation
+// =============================================================================
+/**
+ * Simple LRU cache for prompts
+ *
+ * @example
+ * ```typescript
+ * const cache = new PromptCache({ ttl_ms: 60000, max_size: 50 });
+ *
+ * // Check cache first
+ * const cached = cache.get('marketing', 'greeting');
+ * if (cached) {
+ *   return cached;
+ * }
+ *
+ * // Fetch from database and cache
+ * const prompt = get_prompt_by_area_and_key(db, 'marketing', 'greeting', logger);
+ * if (prompt) {
+ *   cache.set(prompt);
+ * }
+ * ```
+ */
+export class PromptCache {
+    constructor(config = {}) {
+        this.cache = new Map();
+        this.ttl_ms = config.ttl_ms ?? DEFAULT_CACHE_TTL_MS;
+        this.max_size = config.max_size ?? DEFAULT_MAX_CACHE_SIZE;
+        this.enabled = config.enabled ?? true;
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Generate cache key from area and key
+     */
+    make_key(area, key) {
+        return `${area}:${key}`;
+    }
+    /**
+     * Check if an entry is expired
+     */
+    is_expired(entry) {
+        return Date.now() - entry.timestamp > this.ttl_ms;
+    }
+    /**
+     * Evict least recently used entries if cache is full
+     */
+    evict_if_needed() {
+        if (this.cache.size < this.max_size) {
+            return;
+        }
+        // Find entry with oldest timestamp
+        let oldest_key = null;
+        let oldest_time = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldest_time) {
+                oldest_time = entry.timestamp;
+                oldest_key = key;
+            }
+        }
+        if (oldest_key) {
+            this.cache.delete(oldest_key);
+        }
+    }
+    /**
+     * Get a prompt from the cache
+     *
+     * @param area - Prompt area
+     * @param key - Prompt key
+     * @returns Cached prompt or null if not found/expired
+     */
+    get(area, key) {
+        if (!this.enabled) {
+            return null;
+        }
+        const cache_key = this.make_key(area, key);
+        const entry = this.cache.get(cache_key);
+        if (!entry) {
+            this.misses++;
+            return null;
+        }
+        if (this.is_expired(entry)) {
+            this.cache.delete(cache_key);
+            this.misses++;
+            return null;
+        }
+        // Update access metadata
+        entry.access_count++;
+        entry.timestamp = Date.now();
+        this.hits++;
+        return entry.prompt;
+    }
+    /**
+     * Get a prompt by UUID from the cache
+     *
+     * @param uuid - Prompt UUID
+     * @returns Cached prompt or null if not found/expired
+     */
+    get_by_uuid(uuid) {
+        if (!this.enabled) {
+            return null;
+        }
+        // Linear search through cache (UUID lookups are less common)
+        for (const entry of this.cache.values()) {
+            if (entry.prompt.uuid === uuid) {
+                if (this.is_expired(entry)) {
+                    // Let the area:key lookup handle deletion
+                    this.misses++;
+                    return null;
+                }
+                entry.access_count++;
+                entry.timestamp = Date.now();
+                this.hits++;
+                return entry.prompt;
+            }
+        }
+        this.misses++;
+        return null;
+    }
+    /**
+     * Add a prompt to the cache
+     *
+     * @param prompt - Prompt record to cache
+     */
+    set(prompt) {
+        if (!this.enabled) {
+            return;
+        }
+        this.evict_if_needed();
+        const cache_key = this.make_key(prompt.prompt_area, prompt.prompt_key);
+        this.cache.set(cache_key, {
+            prompt,
+            timestamp: Date.now(),
+            access_count: 1,
+        });
+    }
+    /**
+     * Remove a prompt from the cache
+     *
+     * @param area - Prompt area
+     * @param key - Prompt key
+     */
+    invalidate(area, key) {
+        const cache_key = this.make_key(area, key);
+        this.cache.delete(cache_key);
+    }
+    /**
+     * Remove a prompt by UUID from the cache
+     *
+     * @param uuid - Prompt UUID
+     */
+    invalidate_by_uuid(uuid) {
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.prompt.uuid === uuid) {
+                this.cache.delete(key);
+                break;
+            }
+        }
+    }
+    /**
+     * Invalidate all prompts in an area
+     *
+     * @param area - Prompt area to invalidate
+     */
+    invalidate_area(area) {
+        const prefix = `${area}:`;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear all cached entries
+     */
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Remove all expired entries
+     *
+     * @returns Number of entries removed
+     */
+    cleanup() {
+        let removed = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (this.is_expired(entry)) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Get cache statistics
+     */
+    get_stats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            size: this.cache.size,
+            max_size: this.max_size,
+            hit_rate: total > 0 ? this.hits / total : 0,
+        };
+    }
+    /**
+     * Enable or disable the cache
+     *
+     * @param enabled - Whether to enable caching
+     */
+    set_enabled(enabled) {
+        this.enabled = enabled;
+        if (!enabled) {
+            this.clear();
+        }
+    }
+    /**
+     * Check if caching is enabled
+     */
+    is_enabled() {
+        return this.enabled;
+    }
+}
+// =============================================================================
+// Global Cache Instance
+// =============================================================================
+/**
+ * Global prompt cache instance
+ * Can be configured via configure_prompt_cache()
+ */
+let global_cache = null;
+/**
+ * Get the global prompt cache instance
+ * Creates one with default settings if not configured
+ *
+ * @returns Global prompt cache
+ */
+export function get_prompt_cache() {
+    if (!global_cache) {
+        global_cache = new PromptCache();
+    }
+    return global_cache;
+}
+/**
+ * Configure the global prompt cache
+ *
+ * @param config - Cache configuration options
+ */
+export function configure_prompt_cache(config) {
+    global_cache = new PromptCache(config);
+}
+/**
+ * Clear the global prompt cache
+ */
+export function clear_prompt_cache() {
+    if (global_cache) {
+        global_cache.clear();
+    }
+}
+//# sourceMappingURL=prompt_cache.js.map

package/dist/lib/prompts/prompt_cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt_cache.js","sourceRoot":"","sources":["../../../src/lib/prompts/prompt_cache.ts"],"names":[],"mappings":"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"}

package/dist/lib/prompts/substitute_variables.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Variable Substitution Module
+ *
+ * Functions to replace variables in prompt text.
+ * Variables use double curly brace syntax: {{variable_name}}
+ * Values come from the prompt_variables JSON array.
+ */
+import type { Logger, PromptVariables } from '../llm_api/types.js';
+/**
+ * Substitute variables in prompt text with values from prompt_variables
+ * Variables are identified by double curly braces (e.g., {{location}} becomes "Tokyo")
+ *
+ * @param prompt_text - The prompt text containing variables to replace
+ * @param prompt_variables - Array of key-value objects with variable values
+ *                           Format: [{ "variable1": "value1", "variable2": "value2" }]
+ * @param logger - Logger instance
+ * @returns The prompt text with all variables substituted
+ */
+export declare function substitute_variables(prompt_text: string, prompt_variables: PromptVariables | undefined, logger: Logger): string;
+/**
+ * Parse prompt_variables from JSON string
+ * @param json_string - JSON string containing prompt variables
+ * @param logger - Logger instance
+ * @returns Parsed prompt variables array, or empty array if parsing fails
+ */
+export declare function parse_prompt_variables(json_string: string | undefined | null, logger: Logger): PromptVariables;
+/**
+ * Validate that all required variables are present
+ * @param prompt_text - The prompt text containing variables
+ * @param prompt_variables - The variables provided for substitution
+ * @param logger - Logger instance
+ * @returns Object with validation result and any missing variables
+ */
+export declare function validate_variables(prompt_text: string, prompt_variables: PromptVariables | undefined, logger: Logger): {
+    valid: boolean;
+    missing_variables: string[];
+};
+//# sourceMappingURL=substitute_variables.d.ts.map

package/dist/lib/prompts/substitute_variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"substitute_variables.d.ts","sourceRoot":"","sources":["../../../src/lib/prompts/substitute_variables.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAMnE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,eAAe,GAAG,SAAS,EAC7C,MAAM,EAAE,MAAM,GACb,MAAM,CA8DR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACtC,MAAM,EAAE,MAAM,GACb,eAAe,CAuCjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,eAAe,GAAG,SAAS,EAC7C,MAAM,EAAE,MAAM,GACb;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAqDjD"}

package/dist/lib/prompts/substitute_variables.js

@@ -0,0 +1,171 @@
+/**
+ * Variable Substitution Module
+ *
+ * Functions to replace variables in prompt text.
+ * Variables use double curly brace syntax: {{variable_name}}
+ * Values come from the prompt_variables JSON array.
+ */
+// =============================================================================
+// Variable Substitution Functions
+// =============================================================================
+/**
+ * Substitute variables in prompt text with values from prompt_variables
+ * Variables are identified by double curly braces (e.g., {{location}} becomes "Tokyo")
+ *
+ * @param prompt_text - The prompt text containing variables to replace
+ * @param prompt_variables - Array of key-value objects with variable values
+ *                           Format: [{ "variable1": "value1", "variable2": "value2" }]
+ * @param logger - Logger instance
+ * @returns The prompt text with all variables substituted
+ */
+export function substitute_variables(prompt_text, prompt_variables, logger) {
+    const file_name = 'substitute_variables.ts';
+    // If no variables provided, return original text
+    if (!prompt_variables || prompt_variables.length === 0) {
+        return prompt_text;
+    }
+    let result_text = prompt_text;
+    const substitutions_made = {};
+    const missing_variables = [];
+    // Flatten all variables from the array into a single object
+    const all_variables = {};
+    for (const var_obj of prompt_variables) {
+        for (const [key, value] of Object.entries(var_obj)) {
+            all_variables[key] = value;
+        }
+    }
+    // Find all {{variable}} patterns in the text
+    const variable_pattern = /\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+    const found_variables = [];
+    let match;
+    while ((match = variable_pattern.exec(prompt_text)) !== null) {
+        const var_name = match[1];
+        if (!found_variables.includes(var_name)) {
+            found_variables.push(var_name);
+        }
+    }
+    // Substitute each found variable
+    for (const var_name of found_variables) {
+        const var_pattern = new RegExp(`\\{\\{${var_name}\\}\\}`, 'g');
+        if (var_name in all_variables) {
+            const value = all_variables[var_name];
+            result_text = result_text.replace(var_pattern, value);
+            substitutions_made[`{{${var_name}}}`] = value;
+        }
+        else {
+            missing_variables.push(var_name);
+            logger.warn(`Variable not found in prompt_variables: {{${var_name}}}`, {
+                file: file_name,
+                data: { variable: var_name, available_variables: Object.keys(all_variables) },
+            });
+        }
+    }
+    // Log variable substitution with before and after in one message
+    if (Object.keys(substitutions_made).length > 0) {
+        logger.info('Variable substitution', {
+            file: file_name,
+            data: {
+                before: prompt_text,
+                after: result_text,
+                substitutions: substitutions_made,
+            },
+        });
+    }
+    return result_text;
+}
+/**
+ * Parse prompt_variables from JSON string
+ * @param json_string - JSON string containing prompt variables
+ * @param logger - Logger instance
+ * @returns Parsed prompt variables array, or empty array if parsing fails
+ */
+export function parse_prompt_variables(json_string, logger) {
+    const file_name = 'substitute_variables.ts';
+    if (!json_string || json_string.trim() === '') {
+        logger.debug('Empty or null prompt_variables string', {
+            file: file_name,
+            line: 118,
+        });
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(json_string);
+        // Ensure it's an array
+        if (!Array.isArray(parsed)) {
+            logger.warn('prompt_variables is not an array, wrapping in array', {
+                file: file_name,
+                line: 129,
+            });
+            return [parsed];
+        }
+        logger.debug('Parsed prompt_variables successfully', {
+            file: file_name,
+            line: 135,
+            data: { count: parsed.length },
+        });
+        return parsed;
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : String(error);
+        logger.error('Failed to parse prompt_variables JSON', {
+            file: file_name,
+            line: 143,
+            data: { error: error_message },
+        });
+        return [];
+    }
+}
+/**
+ * Validate that all required variables are present
+ * @param prompt_text - The prompt text containing variables
+ * @param prompt_variables - The variables provided for substitution
+ * @param logger - Logger instance
+ * @returns Object with validation result and any missing variables
+ */
+export function validate_variables(prompt_text, prompt_variables, logger) {
+    const file_name = 'substitute_variables.ts';
+    // Find all {{variable}} patterns in the prompt text
+    const variable_pattern = /\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+    const found_variables = [];
+    let match;
+    while ((match = variable_pattern.exec(prompt_text)) !== null) {
+        const var_name = match[1];
+        if (!found_variables.includes(var_name)) {
+            found_variables.push(var_name);
+        }
+    }
+    // If no variables in text, validation passes
+    if (found_variables.length === 0) {
+        logger.debug('No variables found in prompt text', {
+            file: file_name,
+        });
+        return { valid: true, missing_variables: [] };
+    }
+    // Flatten provided variables
+    const all_variables = {};
+    if (prompt_variables) {
+        for (const var_obj of prompt_variables) {
+            for (const [key, value] of Object.entries(var_obj)) {
+                all_variables[key] = value;
+            }
+        }
+    }
+    // Check for missing variables
+    const missing_variables = [];
+    for (const var_name of found_variables) {
+        if (!(var_name in all_variables)) {
+            missing_variables.push(var_name);
+        }
+    }
+    const valid = missing_variables.length === 0;
+    logger.debug('Variable validation completed', {
+        file: file_name,
+        data: {
+            valid,
+            found_variables,
+            missing_variables,
+        },
+    });
+    return { valid, missing_variables };
+}
+//# sourceMappingURL=substitute_variables.js.map

package/dist/lib/prompts/substitute_variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"substitute_variables.js","sourceRoot":"","sources":["../../../src/lib/prompts/substitute_variables.ts"],"names":[],"mappings":"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"}

package/dist/lib/providers/gemini/gemini_client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Gemini API Client Module
+ *
+ * Handles communication with the Google Gemini API.
+ * Formats requests according to Gemini API specification and parses responses.
+ */
+import type { Logger, Base64Data, LLMResponse, GeminiGenerationConfig } from '../../llm_api/types.js';
+/**
+ * Call the Gemini API with the given prompt and optional image data
+ * @param api_url - The Gemini API endpoint URL
+ * @param api_key - The API key for authentication
+ * @param prompt_text - The text prompt to send
+ * @param b64_data - Optional array of base64 encoded images
+ * @param logger - Logger instance
+ * @param generation_config - Optional generation configuration parameters
+ * @returns LLM response with generated text or error
+ */
+export declare function call_gemini_api(api_url: string, api_key: string, prompt_text: string, b64_data: Base64Data[] | undefined, logger: Logger, generation_config?: GeminiGenerationConfig): Promise<LLMResponse>;
+/**
+ * Get the default Gemini API URL
+ * @param model - The model name (default: gemini-2.5-flash)
+ * @returns The API URL
+ */
+export declare function get_gemini_api_url(model?: string): string;
+//# sourceMappingURL=gemini_client.d.ts.map

package/dist/lib/providers/gemini/gemini_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini_client.d.ts","sourceRoot":"","sources":["../../../../src/lib/providers/gemini/gemini_client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,WAAW,EAIX,sBAAsB,EAEvB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,UAAU,EAAE,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,EACd,iBAAiB,CAAC,EAAE,sBAAsB,GACzC,OAAO,CAAC,WAAW,CAAC,CA0FtB;AA2JD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,MAA2B,GAAG,MAAM,CAE7E"}