genai-lite 0.1.0

package/dist/llm/clients/adapterErrorUtils.js

@@ -0,0 +1,107 @@
+"use strict";
+// AI Summary: Centralized error mapping utility for LLM client adapters.
+// Maps common HTTP status codes and network errors to standardized AdapterErrorCode and errorType.
+// Reduces duplication across OpenAI, Anthropic and other provider adapters.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommonMappedErrorDetails = getCommonMappedErrorDetails;
+const types_1 = require("./types");
+/**
+ * Maps common error patterns to standardized error codes and types
+ *
+ * This utility handles:
+ * - Common HTTP status codes (401, 402, 404, 429, 4xx, 5xx)
+ * - Network connection errors (ENOTFOUND, ECONNREFUSED, timeouts)
+ * - Generic JavaScript errors
+ *
+ * Individual adapters can further refine the mappings for provider-specific cases,
+ * particularly for 400 errors where message content determines the specific error type.
+ *
+ * @param error - The error object from the provider SDK or network layer
+ * @param providerMessageOverride - Optional override for the error message (e.g., from provider SDK)
+ * @returns Mapped error details with standardized codes and types
+ */
+function getCommonMappedErrorDetails(error, providerMessageOverride) {
+    let errorCode = types_1.ADAPTER_ERROR_CODES.UNKNOWN_ERROR;
+    let errorMessage = providerMessageOverride || error?.message || 'Unknown error occurred';
+    let errorType = 'server_error';
+    let status;
+    // Handle API errors with HTTP status codes
+    if (error && typeof error.status === 'number') {
+        const httpStatus = error.status;
+        status = httpStatus;
+        errorMessage = providerMessageOverride || error.message || `HTTP ${httpStatus} error`;
+        // Map common HTTP status codes
+        // TypeScript knows httpStatus is defined here due to the typeof check above
+        switch (httpStatus) {
+            case 400:
+                // Default mapping for 400 errors - adapters should refine based on message content
+                errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                errorType = 'invalid_request_error';
+                break;
+            case 401:
+                errorCode = types_1.ADAPTER_ERROR_CODES.INVALID_API_KEY;
+                errorType = 'authentication_error';
+                break;
+            case 402:
+                errorCode = types_1.ADAPTER_ERROR_CODES.INSUFFICIENT_CREDITS;
+                errorType = 'rate_limit_error';
+                break;
+            case 404:
+                errorCode = types_1.ADAPTER_ERROR_CODES.MODEL_NOT_FOUND;
+                errorType = 'invalid_request_error';
+                break;
+            case 429:
+                errorCode = types_1.ADAPTER_ERROR_CODES.RATE_LIMIT_EXCEEDED;
+                errorType = 'rate_limit_error';
+                break;
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                errorType = 'server_error';
+                break;
+            default:
+                if (httpStatus >= 400 && httpStatus < 500) {
+                    errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                    errorType = 'invalid_request_error';
+                }
+                else if (httpStatus >= 500) {
+                    errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                    errorType = 'server_error';
+                }
+                else {
+                    errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                    errorType = 'server_error';
+                }
+        }
+    }
+    // Handle network connection errors
+    else if (error && (error.code === 'ENOTFOUND' ||
+        error.code === 'ECONNREFUSED' ||
+        error.code === 'ETIMEDOUT' ||
+        error.name === 'ConnectTimeoutError' ||
+        (error.type && error.type.includes('timeout')))) {
+        errorCode = types_1.ADAPTER_ERROR_CODES.NETWORK_ERROR;
+        errorType = 'connection_error';
+        errorMessage = providerMessageOverride || error.message || 'Network connection failed';
+    }
+    // Handle generic JavaScript errors
+    else if (error instanceof Error) {
+        errorMessage = providerMessageOverride || error.message || 'Client error occurred';
+        errorCode = types_1.ADAPTER_ERROR_CODES.UNKNOWN_ERROR;
+        errorType = 'client_error';
+    }
+    // Handle unknown error types
+    else {
+        errorMessage = providerMessageOverride || 'Unknown error occurred';
+        errorCode = types_1.ADAPTER_ERROR_CODES.UNKNOWN_ERROR;
+        errorType = 'server_error';
+    }
+    return {
+        errorCode,
+        errorMessage,
+        errorType,
+        status
+    };
+}

package/dist/llm/clients/types.d.ts

@@ -0,0 +1,65 @@
+import type { LLMChatRequest, LLMResponse, LLMFailureResponse, LLMSettings } from "../types";
+/**
+ * Internal request structure used by client adapters with applied defaults
+ * This ensures all settings have values and adapters don't need to handle undefined values
+ */
+export interface InternalLLMChatRequest extends Omit<LLMChatRequest, "settings"> {
+    settings: Required<LLMSettings>;
+}
+/**
+ * Interface that all LLM client adapters must implement
+ *
+ * Client adapters handle the provider-specific logic for:
+ * - Formatting requests according to provider API requirements
+ * - Making HTTP calls to provider endpoints
+ * - Parsing responses into standardized format
+ * - Handling provider-specific errors
+ * - Managing provider-specific authentication
+ */
+export interface ILLMClientAdapter {
+    /**
+     * Sends a chat message to the LLM provider
+     *
+     * @param request - The LLM request with applied default settings
+     * @param apiKey - The decrypted API key for the provider
+     * @returns Promise resolving to either a successful response or failure response
+     *
+     * @throws Should not throw - all errors should be caught and returned as LLMFailureResponse
+     */
+    sendMessage(request: InternalLLMChatRequest, apiKey: string): Promise<LLMResponse | LLMFailureResponse>;
+    /**
+     * Optional method to validate API key format before making requests
+     *
+     * @param apiKey - The API key to validate
+     * @returns True if the key format appears valid for this provider
+     */
+    validateApiKey?(apiKey: string): boolean;
+    /**
+     * Optional method to get provider-specific information
+     *
+     * @returns Information about this adapter's capabilities or configuration
+     */
+    getAdapterInfo?(): {
+        providerId: string;
+        name: string;
+        version?: string;
+    };
+}
+/**
+ * Base error codes that adapters should use for consistency
+ */
+export declare const ADAPTER_ERROR_CODES: {
+    readonly INVALID_API_KEY: "INVALID_API_KEY";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS";
+    readonly MODEL_NOT_FOUND: "MODEL_NOT_FOUND";
+    readonly CONTEXT_LENGTH_EXCEEDED: "CONTEXT_LENGTH_EXCEEDED";
+    readonly CONTENT_FILTER: "CONTENT_FILTER";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly PROVIDER_ERROR: "PROVIDER_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+/**
+ * Helper type for adapter error codes
+ */
+export type AdapterErrorCode = (typeof ADAPTER_ERROR_CODES)[keyof typeof ADAPTER_ERROR_CODES];

package/dist/llm/clients/types.js

@@ -0,0 +1,19 @@
+"use strict";
+// AI Summary: Interface definition for LLM client adapters that handle provider-specific API calls.
+// Defines the contract that all LLM provider clients must implement with enhanced type safety.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_ERROR_CODES = void 0;
+/**
+ * Base error codes that adapters should use for consistency
+ */
+exports.ADAPTER_ERROR_CODES = {
+    INVALID_API_KEY: "INVALID_API_KEY",
+    RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED",
+    INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
+    MODEL_NOT_FOUND: "MODEL_NOT_FOUND",
+    CONTEXT_LENGTH_EXCEEDED: "CONTEXT_LENGTH_EXCEEDED",
+    CONTENT_FILTER: "CONTENT_FILTER",
+    NETWORK_ERROR: "NETWORK_ERROR",
+    PROVIDER_ERROR: "PROVIDER_ERROR",
+    UNKNOWN_ERROR: "UNKNOWN_ERROR",
+};

package/dist/llm/config.d.ts

@@ -0,0 +1,90 @@
+import type { LLMSettings, ProviderInfo, ModelInfo, ApiProviderId } from "./types";
+import type { ILLMClientAdapter } from "./clients/types";
+/**
+ * Mapping from provider IDs to their corresponding adapter constructor classes
+ * This enables dynamic registration of client adapters in LLMServiceMain
+ */
+export declare const ADAPTER_CONSTRUCTORS: Partial<Record<ApiProviderId, new (config?: {
+    baseURL?: string;
+}) => ILLMClientAdapter>>;
+/**
+ * Optional configuration objects for each adapter
+ * Allows passing parameters like baseURL during instantiation
+ */
+export declare const ADAPTER_CONFIGS: Partial<Record<ApiProviderId, {
+    baseURL?: string;
+}>>;
+/**
+ * Default settings applied to all LLM requests unless overridden
+ */
+export declare const DEFAULT_LLM_SETTINGS: Required<LLMSettings>;
+/**
+ * Per-provider default setting overrides
+ */
+export declare const PROVIDER_DEFAULT_SETTINGS: Partial<Record<ApiProviderId, Partial<LLMSettings>>>;
+/**
+ * Per-model default setting overrides (takes precedence over provider defaults)
+ */
+export declare const MODEL_DEFAULT_SETTINGS: Record<string, Partial<LLMSettings>>;
+/**
+ * Supported LLM providers
+ */
+export declare const SUPPORTED_PROVIDERS: ProviderInfo[];
+/**
+ * Supported LLM models with their configurations
+ * ModelInfo is similar to Cline model info
+ * See: https://github.com/cline/cline/blob/main/src/shared/api.ts
+ */
+export declare const SUPPORTED_MODELS: ModelInfo[];
+/**
+ * Gets provider information by ID
+ *
+ * @param providerId - The provider ID to look up
+ * @returns The provider info or undefined if not found
+ */
+export declare function getProviderById(providerId: string): ProviderInfo | undefined;
+/**
+ * Gets model information by ID and provider
+ *
+ * @param modelId - The model ID to look up
+ * @param providerId - The provider ID to filter by
+ * @returns The model info or undefined if not found
+ */
+export declare function getModelById(modelId: string, providerId?: string): ModelInfo | undefined;
+/**
+ * Gets all models for a specific provider
+ *
+ * @param providerId - The provider ID to filter by
+ * @returns Array of model info for the provider
+ */
+export declare function getModelsByProvider(providerId: string): ModelInfo[];
+/**
+ * Validates if a provider is supported
+ *
+ * @param providerId - The provider ID to validate
+ * @returns True if the provider is supported
+ */
+export declare function isProviderSupported(providerId: string): boolean;
+/**
+ * Validates if a model is supported for a given provider
+ *
+ * @param modelId - The model ID to validate
+ * @param providerId - The provider ID to validate against
+ * @returns True if the model is supported for the provider
+ */
+export declare function isModelSupported(modelId: string, providerId: string): boolean;
+/**
+ * Gets merged default settings for a specific model and provider
+ *
+ * @param modelId - The model ID
+ * @param providerId - The provider ID
+ * @returns Merged default settings with model-specific overrides applied
+ */
+export declare function getDefaultSettingsForModel(modelId: string, providerId: ApiProviderId): Required<LLMSettings>;
+/**
+ * Validates LLM settings values
+ *
+ * @param settings - The settings to validate
+ * @returns Array of validation error messages, empty if valid
+ */
+export declare function validateLLMSettings(settings: Partial<LLMSettings>): string[];