@contentgrowth/llm-service 0.8.3 → 0.8.5

package/dist/index.d.ts

@@ -0,0 +1,529 @@
+import OpenAI from 'openai';
+import * as _google_genai from '@google/genai';
+import { GoogleGenAI } from '@google/genai';
+
+declare namespace FINISH_REASONS {
+    let COMPLETED: string;
+    let TRUNCATED: string;
+    let CONTENT_FILTER: string;
+    let TOOL_CALL: string;
+    let UNKNOWN: string;
+}
+/**
+ * Abstract base class for LLM Providers.
+ * Defines the standard interface that all providers must implement.
+ */
+declare class BaseLLMProvider {
+    constructor(config: any);
+    config: any;
+    /**
+     * Normalize provider-specific finish reason to standard value.
+     * Override in subclass if provider uses different values.
+     * @param {string} providerReason - The provider's native finish reason
+     * @returns {string} Standardized finish reason from FINISH_REASONS
+     */
+    normalizeFinishReason(providerReason: string): string;
+    /**
+     * Simple chat interface for single-turn conversations
+     * @param {string} userMessage
+     * @param {string} systemPrompt
+     * @param {Object} options
+     */
+    chat(userMessage: string, systemPrompt: string, options: any): Promise<void>;
+    /**
+     * Advanced chat completion with tool support
+     * @param {Array} messages
+     * @param {string} systemPrompt
+     * @param {Array} tools
+     * @param {Object} options - Generation options (responseFormat, temperature, etc.)
+     */
+    chatCompletion(messages: any[], systemPrompt: string, tools: any[], options?: any): Promise<void>;
+    /**
+     * Execute tools requested by the LLM
+     * @param {Array} toolCalls
+     * @param {Array} messages
+     * @param {string} tenantId
+     * @param {Object} toolImplementations
+     * @param {Object} env
+     */
+    executeTools(toolCalls: any[], messages: any[], tenantId: string, toolImplementations: any, env: any): Promise<void>;
+    /**
+     * Generate image
+     * Subclasses should override this method.
+     * Model can be overridden via options.model, otherwise uses config.models.image
+     * @param {string} prompt - Text description of the image
+     * @param {string} systemPrompt - System instructions for generation
+     * @param {Object} options - Generation options (aspectRatio, images, model, etc.)
+     * @returns {Promise<{imageData: string, mimeType: string}>}
+     */
+    imageGeneration(prompt: string, systemPrompt: string, options?: any): Promise<{
+        imageData: string;
+        mimeType: string;
+    }>;
+    /**
+     * Start video generation (returns operation name for polling)
+     * @param {string} prompt
+     * @param {Array} images
+     * @param {string} modelName
+     * @param {string} systemPrompt
+     * @param {Object} options
+     * @returns {Promise<{operationName: string}>}
+     */
+    startVideoGeneration(prompt: string, images: any[], modelName: string, systemPrompt: string, options: any): Promise<{
+        operationName: string;
+    }>;
+    /**
+     * Get video generation status (poll operation)
+     * @param {string} operationName
+     * @returns {Promise<{done: boolean, progress: number, state: string, videoUri?: string, error?: object}>}
+     */
+    getVideoGenerationStatus(operationName: string): Promise<{
+        done: boolean;
+        progress: number;
+        state: string;
+        videoUri?: string;
+        error?: object;
+    }>;
+    /**
+     * Helper to get the last 6 digits of the API key for logging.
+     * @returns {string} "..." + last 6 chars, or "not_set"
+     */
+    _getMaskedApiKey(): string;
+}
+
+declare class OpenAIProvider extends BaseLLMProvider {
+    client: OpenAI;
+    models: any;
+    defaultModel: any;
+    chat(userMessage: any, systemPrompt?: string, options?: {}): Promise<{
+        text: string;
+    }>;
+    chatCompletion(messages: any, systemPrompt: any, tools?: any, options?: {}): Promise<{
+        parsedContent?: any;
+        content: string;
+        tool_calls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[];
+        finishReason: string;
+        _rawFinishReason: "content_filter" | "stop" | "length" | "tool_calls" | "function_call";
+        _responseFormat: any;
+    }>;
+    _chatCompletionWithModel(messages: any, systemPrompt: any, tools: any, modelName: any, maxTokens: any, temperature: any, options?: {}): Promise<{
+        parsedContent?: any;
+        content: string;
+        tool_calls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[];
+        finishReason: string;
+        _rawFinishReason: "content_filter" | "stop" | "length" | "tool_calls" | "function_call";
+        _responseFormat: any;
+    }>;
+    _buildResponseFormat(options: any): {
+        type: string;
+        json_schema: {
+            name: any;
+            strict: any;
+            schema: any;
+        };
+    } | {
+        type: string;
+        json_schema?: undefined;
+    };
+    _shouldAutoParse(options: any): boolean;
+    _safeJsonParse(content: any): any;
+    executeTools(tool_calls: any, messages: any, tenantId: any, toolImplementations: any, env: any): Promise<void>;
+    _getModelForTier(tier: any): any;
+    videoGeneration(prompt: any, images: any, modelName: any, systemPrompt: any, options?: {}): Promise<void>;
+    startDeepResearch(prompt: any, options?: {}): Promise<void>;
+    getDeepResearchStatus(operationId: any): Promise<void>;
+}
+
+declare class GeminiProvider extends BaseLLMProvider {
+    client: GoogleGenAI;
+    models: any;
+    defaultModel: any;
+    _pendingOperations: Map<any, any>;
+    chat(userMessage: any, systemPrompt?: string, options?: {}): Promise<{
+        text: string;
+    }>;
+    chatCompletion(messages: any, systemPrompt: any, tools?: any, options?: {}): Promise<{
+        parsedContent?: any;
+        content: string;
+        thought_signature: any;
+        tool_calls: {
+            type: string;
+            function: _google_genai.FunctionCall;
+            thought_signature: any;
+        }[];
+        finishReason: string;
+        _rawFinishReason: _google_genai.FinishReason;
+        _responseFormat: any;
+    }>;
+    _chatCompletionWithModel(messages: any, systemPrompt: any, tools: any, modelName: any, maxTokens: any, temperature: any, options?: {}): Promise<{
+        parsedContent?: any;
+        content: string;
+        thought_signature: any;
+        tool_calls: {
+            type: string;
+            function: _google_genai.FunctionCall;
+            thought_signature: any;
+        }[];
+        finishReason: string;
+        _rawFinishReason: _google_genai.FinishReason;
+        _responseFormat: any;
+    }>;
+    _buildGenerationConfig(options: any, maxTokens: any, temperature: any): {
+        temperature: any;
+        maxOutputTokens: any;
+    };
+    _convertToGeminiSchema(jsonSchema: any): {
+        type: string;
+    };
+    _shouldAutoParse(options: any): boolean;
+    _safeJsonParse(content: any): any;
+    executeTools(tool_calls: any, messages: any, tenantId: any, toolImplementations: any, env: any): Promise<void>;
+    imageGeneration(prompt: any, systemPrompt: any, options?: {}): Promise<{
+        imageData: string;
+        mimeType: string;
+        thought_signature: any;
+    }>;
+    _getModelForTier(tier: any): any;
+    startVideoGeneration(prompt: any, images: any, modelName: any, systemPrompt: any, options?: {}): Promise<{
+        operationName: string;
+    }>;
+    getVideoGenerationStatus(operationName: any): Promise<{
+        done: any;
+        progress: any;
+        state: any;
+    }>;
+    startDeepResearch(prompt: any, options?: {}): Promise<{
+        operationId: string;
+    }>;
+    getDeepResearchStatus(operationId: any): Promise<{
+        state: any;
+        done: boolean;
+        error: any;
+    }>;
+}
+
+/**
+ * Create a Hono handler for speech transcription.
+ *
+ * @param {Hono} app - Hono app or router instance to attach the endpoint to
+ * @param {Function} getConfig - Async function that returns transcription config from context
+ *   Should return: { provider: 'openai'|'generic', apiKey: string, endpoint?: string, model?: string }
+ *
+ * @example
+ * // Mount in your Hono app:
+ * import { Hono } from 'hono';
+ * import { createSpeechHandler } from '@contentgrowth/llm-service';
+ *
+ * const speechHandler = new Hono();
+ * createSpeechHandler(speechHandler, async (c) => ({
+ *     provider: 'openai',
+ *     apiKey: c.env.OPENAI_API_KEY,
+ * }));
+ *
+ * app.route('/api/speech', speechHandler);
+ */
+declare function createSpeechHandler(app: Hono, getConfig: Function): Hono;
+
+/**
+ * LLM Service Module
+ *
+ * This module provides a unified interface for interacting with different LLM providers.
+ * It now supports BYOK (Bring Your Own Key) via Tenant Configuration.
+ */
+declare class LLMService {
+    constructor(env: any, toolImplementations?: {});
+    env: any;
+    toolImplementations: {};
+    providerCache: Map<any, any>;
+    _getProvider(tenantId: any): Promise<any>;
+    /**
+     * Check if LLM service is configured for a tenant (or system default)
+     */
+    isConfigured(tenantId: any): Promise<boolean>;
+    /**
+     * Simple chat interface for single-turn conversations
+     */
+    chat(userMessage: any, tenantId: any, systemPrompt?: string, options?: {}): Promise<any>;
+    /**
+     * Interact with LLM for generation
+     *
+     * Intelligent signature detection supports:
+     * - chatCompletion(messages, tenantId, systemPrompt)
+     * - chatCompletion(messages, tenantId, systemPrompt, tools)
+     * - chatCompletion(messages, tenantId, systemPrompt, options)
+     * - chatCompletion(messages, tenantId, systemPrompt, tools, options)
+     *
+     * @param {Array} messages - Conversation messages
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions
+     * @param {Array|Object} toolsOrOptions - Tools array or options object
+     * @param {Object} optionsParam - Options object (if tools provided)
+     * @returns {Object} Response with content, tool_calls, and optionally parsedContent
+     */
+    chatCompletion(messages: any[], tenantId: string, systemPrompt: string, toolsOrOptions?: any[] | any, optionsParam?: any): any;
+    /**
+     * Helper to intelligently detect tools vs options parameters
+     * @private
+     */
+    private _parseToolsAndOptions;
+    /**
+     * Convenience method for JSON-only responses
+     * Automatically enables JSON mode and returns parsed object
+     *
+     * @param {Array} messages - Conversation messages
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions
+     * @param {Object} schema - Optional JSON schema for validation
+     * @param {Array} tools - Optional tools array
+     * @returns {Object} Parsed JSON object
+     * @throws {LLMServiceException} If JSON parsing fails
+     */
+    chatCompletionJson(messages: any[], tenantId: string, systemPrompt: string, schema?: any, tools?: any[]): any;
+    chatWithTools(messages: any, tenantId: any, systemPrompt: any, tools?: any[], options?: {}): Promise<{
+        content: any;
+        parsedContent: any;
+        toolCalls: any;
+        finishReason: any;
+        _rawFinishReason: any;
+    }>;
+    /**
+     * Generate a video (async wrapper with polling - backward compatibility)
+     */
+    videoGeneration(prompt: any, images: any, tenantId: any, modelName: any, systemPrompt: any, options?: {}): Promise<{
+        content: any;
+        videoUri: any;
+    }>;
+    /**
+     * Start video generation (returns operation name for polling)
+     */
+    startVideoGeneration(prompt: any, images: any, tenantId: any, modelName: any, systemPrompt: any, options?: {}): Promise<any>;
+    /**
+     * Get video generation status
+     */
+    getVideoGenerationStatus(operationName: any, tenantId: any): Promise<any>;
+    /**
+     * Generate an image
+     * Falls back to system keys if tenant doesn't have image capability enabled
+     * @param {string} prompt - Text description of the image
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions for generation
+     * @param {Object} options - Generation options (aspectRatio, images, etc.)
+     */
+    imageGeneration(prompt: string, tenantId: string, systemPrompt: string, options?: any): Promise<any>;
+    /**
+     * Start a Deep Research task
+     * @param {string} prompt - Research prompt/query
+     * @param {string} tenantId - Tenant identifier
+     * @param {Object} options - Options (agentId, etc.)
+     * @returns {Promise<{operationId: string}>}
+     */
+    startDeepResearch(prompt: string, tenantId: string, options?: any): Promise<{
+        operationId: string;
+    }>;
+    /**
+     * Get status of a Deep Research task
+     * @param {string} operationId - ID returned from startDeepResearch
+     * @param {string} tenantId - Tenant identifier
+     * @returns {Promise<{state: string, content?: string, citations?: any[]}>}
+     */
+    getDeepResearchStatus(operationId: string, tenantId: string): Promise<{
+        state: string;
+        content?: string;
+        citations?: any[];
+    }>;
+}
+declare class LLMServiceException extends Error {
+    constructor(message: any, statusCode?: number, details?: any);
+    statusCode: number;
+    details: any;
+}
+
+/**
+ * Abstract base class for Config Providers.
+ */
+declare class BaseConfigProvider$1 {
+    /**
+     * Retrieve configuration for a specific tenant.
+     * @param {string} tenantId
+     * @param {Object} env
+     * @returns {Promise<Object>} Configuration object
+     */
+    getConfig(tenantId: string, env: any): Promise<any>;
+}
+/**
+ * Default implementation using Cloudflare KV and Durable Objects.
+ */
+declare class DefaultConfigProvider extends BaseConfigProvider$1 {
+    getConfig(tenantId: any, env: any): Promise<{
+        provider: any;
+        apiKey: any;
+        models: any;
+        temperature: number;
+        maxTokens: number;
+    }>;
+    _loadFromTenantDO(tenantId: any, env: any): Promise<any>;
+    _buildTenantConfig(tenantConfig: any, env: any): {
+        provider: any;
+        apiKey: any;
+        models: any;
+        temperature: number;
+        maxTokens: number;
+        capabilities: any;
+        isTenantOwned: boolean;
+    };
+    _getSystemConfig(env: any): {
+        provider: any;
+        apiKey: any;
+        models: any;
+        temperature: number;
+        maxTokens: number;
+    };
+}
+
+declare namespace MODEL_CONFIGS {
+    namespace openai {
+        let _default: string;
+        export { _default as default };
+        export let edge: string;
+        export let fast: string;
+        export let cost: string;
+        export let free: string;
+    }
+    namespace gemini {
+        let _default_1: string;
+        export { _default_1 as default };
+        let edge_1: string;
+        export { edge_1 as edge };
+        let fast_1: string;
+        export { fast_1 as fast };
+        let cost_1: string;
+        export { cost_1 as cost };
+        let free_1: string;
+        export { free_1 as free };
+        export let video: string;
+        export let image: string;
+    }
+}
+declare class ConfigManager {
+    static _provider: DefaultConfigProvider;
+    /**
+     * Set a custom configuration provider.
+     * @param {BaseConfigProvider} provider
+     */
+    static setConfigProvider(provider: BaseConfigProvider): void;
+    static getConfig(tenantId: any, env: any): Promise<{
+        provider: any;
+        apiKey: any;
+        models: any;
+        temperature: number;
+        maxTokens: number;
+    }>;
+}
+
+/**
+ * Extracts and parses JSON from a text response (e.g., from an LLM).
+ * Handles JSON in markdown code blocks or plain JSON objects.
+ *
+ * TODO: improveme for better performance
+ *
+ * @param {string} text - The text containing JSON
+ * @returns {object|null} - The parsed JSON object, or null if no valid JSON found
+ */
+declare function extractJsonFromResponse(text: string): object | null;
+/**
+ * Generic helper to separate conversational text from a structured JSON payload.
+ * Supports both "Text + JSON" and "JSON + Text" patterns.
+ *
+ * @param {string} input - The full response string
+ * @returns {{text: string, json: object|null}}
+ */
+declare function extractTextAndJson(input: string): {
+    text: string;
+    json: object | null;
+};
+
+/**
+ * Error Handling Utility for LLM Service
+ * Provides centralized error parsing and user-friendly message generation.
+ * Returns plain objects - framework-specific response handling is done by consumers.
+ */
+/**
+ * Parse an error and return a standardized error response object.
+ * Detects specific error types like service overload, rate limits, and input issues.
+ *
+ * @param {Error} error - The caught error
+ * @param {string} operation - The operation being performed (e.g., 'generate image', 'edit article')
+ * @param {string} context - Context for logging (e.g., 'image_generation', 'ai_edit')
+ * @returns {{ message: string, error: string, retryable: boolean, statusCode: number }}
+ */
+declare function handleApiError(error: Error, operation?: string, context?: string): {
+    message: string;
+    error: string;
+    retryable: boolean;
+    statusCode: number;
+};
+/**
+ * Sanitize error messages to prevent leaking technical details.
+ * Returns an Error with a clean error code that can be handled by the API layer.
+ * Use this when you want to throw an error rather than return a JSON response.
+ *
+ * @param {Error} error - The original error
+ * @param {string} context - Context of where error occurred (e.g., 'image_generation', 'ai_edit')
+ * @returns {Error} - Sanitized error with clean message code
+ */
+declare function sanitizeError(error: Error, context?: string): Error;
+
+/**
+ * Transcription Service - Separate from LLM Service
+ * Handles audio-to-text transcription using various providers.
+ *
+ * Supported providers:
+ * - 'openai': OpenAI Whisper API
+ * - 'generic': Any Whisper-compatible endpoint (Grok, self-hosted, etc.)
+ */
+declare class TranscriptionService {
+    /**
+     * @param {Object} config
+     * @param {string} config.provider - 'openai' | 'generic'
+     * @param {string} config.apiKey - API key for the provider
+     * @param {string} [config.endpoint] - Custom endpoint URL (required for 'generic')
+     * @param {string} [config.model] - Model to use (default: 'whisper-1')
+     */
+    constructor(config: {
+        provider: string;
+        apiKey: string;
+        endpoint?: string;
+        model?: string;
+    });
+    provider: string;
+    apiKey: string;
+    endpoint: string;
+    model: string;
+    client: OpenAI;
+    /**
+     * Transcribe audio to text
+     * @param {File|Blob} audioFile - Audio file to transcribe
+     * @param {Object} options - Transcription options
+     * @param {string} [options.language] - Language hint (ISO-639-1 code)
+     * @param {string} [options.model] - Override default model
+     * @returns {Promise<{text: string}>}
+     */
+    transcribe(audioFile: File | Blob, options?: {
+        language?: string;
+        model?: string;
+    }): Promise<{
+        text: string;
+    }>;
+    _transcribeOpenAI(audioFile: any, model: any, language: any): Promise<{
+        text: string;
+    }>;
+    _transcribeGeneric(audioFile: any, model: any, language: any): Promise<{
+        text: any;
+    }>;
+}
+declare class TranscriptionServiceException extends Error {
+    constructor(message: any, statusCode?: number);
+    statusCode: number;
+}
+
+export { BaseConfigProvider$1 as BaseConfigProvider, ConfigManager, DefaultConfigProvider, FINISH_REASONS, GeminiProvider, LLMService, LLMServiceException, MODEL_CONFIGS, OpenAIProvider, TranscriptionService, TranscriptionServiceException, createSpeechHandler, extractJsonFromResponse, extractTextAndJson, handleApiError, sanitizeError };