llmjs2 0.0.2 → 1.0.0

package/src/providers/openai.ts

@@ -0,0 +1,485 @@
+/**
+ * OpenAI provider implementation
+ */
+
+import https from 'https';
+import http from 'http';
+import { URL } from 'url';
+
+import {
+  CompletionRequest,
+  CompletionResponse,
+  CompletionChunk,
+  ProviderConfig,
+} from '../types.js';
+import {
+  BaseProvider,
+  validateCompletionRequest,
+  withRetry,
+  LLMError,
+} from './base.js';
+
+/**
+ * OpenAI API request format
+ */
+interface OpenAIRequest {
+  model: string;
+  messages: Array<{
+    role: string;
+    content: string;
+  }>;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  stop?: string[];
+  tools?: Array<{
+    type: 'function';
+    function: {
+      name: string;
+      description?: string;
+      parameters?: Record<string, unknown>;
+    };
+  }>;
+  tool_choice?: 'auto' | 'required' | string;
+  stream?: boolean;
+}
+
+/**
+ * OpenAI API response format
+ */
+interface OpenAIChoice {
+  message?: {
+    content: string | null;
+    tool_calls?: Array<{
+      id: string;
+      type: string;
+      function: {
+        name: string;
+        arguments: string;
+      };
+    }>;
+  };
+  delta?: {
+    content?: string;
+    tool_calls?: Array<{
+      index: number;
+      id?: string;
+      type?: string;
+      function?: {
+        name?: string;
+        arguments?: string;
+      };
+    }>;
+  };
+  finish_reason?: string;
+}
+
+interface OpenAIStreamResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: OpenAIChoice[];
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * OpenAI Provider implementation
+ */
+export class OpenAIProvider extends BaseProvider {
+  private apiKey: string;
+  private baseUrl: string = 'https://api.openai.com/v1';
+
+  constructor(config: ProviderConfig) {
+    super(config);
+
+    if (!config.apiKey) {
+      throw new Error('OpenAI API key is required');
+    }
+
+    this.apiKey = config.apiKey;
+
+    if (config.baseUrl) {
+      this.baseUrl = config.baseUrl;
+    }
+  }
+
+  /**
+   * Parse model string (e.g., 'openai/gpt-4' -> 'gpt-4')
+   */
+  parseModel(model: string): string {
+    if (model.startsWith('openai/')) {
+      return model.slice(7); // Remove 'openai/' prefix
+    }
+    return model;
+  }
+
+  /**
+   * Validate configuration
+   */
+  async validate(): Promise<void> {
+    try {
+      // Make a simple request to verify API key
+      await this.makeRequest('/models', 'GET');
+      this.logger('info', 'OpenAI API validation successful');
+    } catch (error) {
+      throw new LLMError(
+        `OpenAI validation failed: ${error instanceof Error ? error.message : String(error)}`,
+        'VALIDATION_FAILED'
+      );
+    }
+  }
+
+  /**
+   * Create a completion
+   */
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    validateCompletionRequest(request);
+
+    const model = this.parseModel(request.model);
+
+    return withRetry(
+      async () => {
+        const openaiRequest: OpenAIRequest = {
+          model,
+          messages: request.messages.map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+          })),
+        };
+
+        // Add optional parameters
+        if (request.maxTokens) openaiRequest.max_tokens = request.maxTokens;
+        if (request.temperature !== undefined)
+          openaiRequest.temperature = request.temperature;
+        if (request.topP !== undefined) openaiRequest.top_p = request.topP;
+        if (request.frequencyPenalty !== undefined)
+          openaiRequest.frequency_penalty = request.frequencyPenalty;
+        if (request.presencePenalty !== undefined)
+          openaiRequest.presence_penalty = request.presencePenalty;
+        if (request.stop) openaiRequest.stop = request.stop;
+        if (request.tools) openaiRequest.tools = request.tools;
+        if (request.toolChoice) openaiRequest.tool_choice = request.toolChoice;
+
+        this.logger('debug', 'OpenAI completion request', {
+          model,
+          messageCount: request.messages.length,
+        });
+
+        const response = await this.makeRequest<OpenAIStreamResponse>(
+          '/chat/completions',
+          'POST',
+          openaiRequest,
+          request
+        );
+
+        if (!response.choices || response.choices.length === 0) {
+          throw new LLMError('No choices in OpenAI response', 'NO_CHOICES');
+        }
+
+        const choice = response.choices[0];
+        const message = choice.message;
+
+        if (!message) {
+          throw new LLMError('No message in OpenAI response choice', 'NO_MESSAGE');
+        }
+
+        const result: CompletionResponse = {
+          content: message.content || '',
+          model: response.model,
+          stopReason: choice.finish_reason,
+          raw: response,
+        };
+
+        if (response.usage) {
+          result.usage = {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          };
+        }
+
+        if (message.tool_calls && message.tool_calls.length > 0) {
+          result.toolCalls = message.tool_calls.map((call) => ({
+            id: call.id,
+            name: call.function.name,
+            arguments: JSON.parse(call.function.arguments),
+          }));
+        }
+
+        this.logger('debug', 'OpenAI completion response', {
+          model: response.model,
+          tokens: response.usage?.total_tokens,
+        });
+
+        return result;
+      },
+      this.getRetryConfig(request)
+    );
+  }
+
+  /**
+   * Stream completion
+   */
+  async *completeStream(
+    request: CompletionRequest
+  ): AsyncIterable<CompletionChunk> {
+    validateCompletionRequest(request);
+
+    const model = this.parseModel(request.model);
+
+    const openaiRequest: OpenAIRequest = {
+      model,
+      stream: true,
+      messages: request.messages.map((msg) => ({
+        role: msg.role,
+        content: msg.content,
+      })),
+    };
+
+    if (request.maxTokens) openaiRequest.max_tokens = request.maxTokens;
+    if (request.temperature !== undefined)
+      openaiRequest.temperature = request.temperature;
+    if (request.topP !== undefined) openaiRequest.top_p = request.topP;
+    if (request.frequencyPenalty !== undefined)
+      openaiRequest.frequency_penalty = request.frequencyPenalty;
+    if (request.presencePenalty !== undefined)
+      openaiRequest.presence_penalty = request.presencePenalty;
+    if (request.stop) openaiRequest.stop = request.stop;
+    if (request.tools) openaiRequest.tools = request.tools;
+    if (request.toolChoice) openaiRequest.tool_choice = request.toolChoice;
+
+    this.logger('debug', 'OpenAI stream request', { model });
+
+    const stream = await this.makeStreamRequest(
+      '/chat/completions',
+      'POST',
+      openaiRequest,
+      request
+    );
+
+    for await (const chunk of stream) {
+      if (chunk.choices && chunk.choices.length > 0) {
+        const choice = chunk.choices[0];
+
+        if (choice.delta?.content) {
+          yield {
+            delta: choice.delta.content,
+            stopReason: choice.finish_reason,
+          };
+        }
+      }
+    }
+  }
+
+  /**
+   * Make HTTP request to OpenAI API
+   */
+  private makeRequest<T>(
+    path: string,
+    method: string = 'POST',
+    body?: unknown,
+    request?: CompletionRequest
+  ): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.baseUrl);
+      const timeout = this.getTimeout(request);
+
+      const requestOptions = {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.apiKey}`,
+          ...this.getHeaders(request),
+        },
+        timeout,
+      };
+
+      const protocol = this.baseUrl.startsWith('https') ? https : http;
+
+      const req = protocol.request(url, requestOptions, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          if (!res.statusCode || res.statusCode >= 400) {
+            try {
+              const errorData = JSON.parse(data);
+              reject(
+                new LLMError(
+                  errorData.error?.message || 'OpenAI API error',
+                  errorData.error?.code,
+                  res.statusCode,
+                  errorData,
+                  res.statusCode === 429 ||
+                    res.statusCode === 502 ||
+                    res.statusCode === 503
+                )
+              );
+            } catch {
+              reject(
+                new LLMError(`OpenAI API error: ${data}`, 'API_ERROR', res.statusCode, null, false)
+              );
+            }
+          } else {
+            try {
+              resolve(JSON.parse(data) as T);
+            } catch (error) {
+              reject(
+                new LLMError(
+                  'Failed to parse OpenAI response',
+                  'PARSE_ERROR',
+                  undefined,
+                  { data }
+                )
+              );
+            }
+          }
+        });
+      });
+
+      req.on('error', (error) => {
+        reject(
+          new LLMError(
+            `OpenAI request failed: ${error.message}`,
+            'REQUEST_FAILED',
+            undefined,
+            { error: error.message },
+            true
+          )
+        );
+      });
+
+      if (body) {
+        req.write(JSON.stringify(body));
+      }
+
+      req.end();
+    });
+  }
+
+  /**
+   * Stream HTTP request
+   */
+  private makeStreamRequest(
+    path: string,
+    method: string = 'POST',
+    body?: unknown,
+    request?: CompletionRequest
+  ): AsyncIterable<OpenAIStreamResponse> {
+    const self = this;
+
+    return {
+      async *[Symbol.asyncIterator]() {
+        const url = new URL(path, self.baseUrl);
+        const timeout = self.getTimeout(request);
+
+        const requestOptions = {
+          method,
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${self.apiKey}`,
+            ...self.getHeaders(request),
+          },
+          timeout,
+        };
+
+        const protocol = self.baseUrl.startsWith('https') ? https : http;
+        const chunks: OpenAIStreamResponse[] = [];
+
+        await new Promise<void>((resolve, reject) => {
+          const req = protocol.request(url, requestOptions, (res) => {
+            if (!res.statusCode || res.statusCode >= 400) {
+              let errorData = '';
+              res.on('data', (chunk) => {
+                errorData += chunk;
+              });
+              res.on('end', () => {
+                reject(
+                  new LLMError(
+                    `OpenAI stream error: ${errorData}`,
+                    'STREAM_ERROR',
+                    res.statusCode
+                  )
+                );
+              });
+              return;
+            }
+
+            let buffer = '';
+
+            res.on('data', (chunk) => {
+              buffer += chunk.toString();
+              const lines = buffer.split('\n');
+              buffer = lines[lines.length - 1];
+
+              for (let i = 0; i < lines.length - 1; i++) {
+                const line = lines[i].trim();
+
+                if (!line || line === '[DONE]') continue;
+
+                if (line.startsWith('data: ')) {
+                  try {
+                    const data = JSON.parse(line.slice(6)) as OpenAIStreamResponse;
+                    chunks.push(data);
+                  } catch (error) {
+                    // Ignore parse errors in stream
+                  }
+                }
+              }
+            });
+
+            res.on('end', () => {
+              resolve();
+            });
+          });
+
+          req.on('error', (error) => {
+            reject(
+              new LLMError(
+                `OpenAI stream request failed: ${error.message}`,
+                'REQUEST_FAILED',
+                undefined,
+                { error: error.message },
+                true
+              )
+            );
+          });
+
+          req.on('timeout', () => {
+            req.destroy();
+            reject(
+              new LLMError(
+                'OpenAI stream request timeout',
+                'TIMEOUT',
+                undefined,
+                null,
+                true
+              )
+            );
+          });
+
+          if (body) {
+            req.write(JSON.stringify(body));
+          }
+
+          req.end();
+        });
+
+        // Yield collected chunks
+        for (const chunk of chunks) {
+          yield chunk;
+        }
+      },
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,231 @@
+/**
+ * Unified type definitions for llmjs2
+ * Enterprise-grade LLM abstraction layer supporting OpenAI and Ollama
+ */
+
+/**
+ * Supported LLM providers
+ */
+export type ProviderType = 'openai' | 'ollama';
+
+/**
+ * Role of a message in a conversation
+ */
+export type MessageRole = 'system' | 'user' | 'assistant';
+
+/**
+ * A single message in a conversation
+ */
+export interface Message {
+  role: MessageRole;
+  content: string;
+}
+
+/**
+ * Tool/function definition for function calling
+ */
+export interface Tool {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Configuration for a completion request
+ */
+export interface CompletionRequest {
+  /** Model identifier (e.g., 'openai/gpt-4', 'ollama/mistral') */
+  model: string;
+
+  /** API key or authentication token */
+  apiKey?: string;
+
+  /** Base URL for the API (mainly for Ollama) */
+  baseUrl?: string;
+
+  /** Messages for the completion */
+  messages: Message[];
+
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+
+  /** Sampling temperature (0-2 for OpenAI, typically 0-1) */
+  temperature?: number;
+
+  /** Top-p (nucleus sampling) */
+  topP?: number;
+
+  /** Top-k sampling parameter */
+  topK?: number;
+
+  /** Frequency penalty (-2 to 2 for OpenAI) */
+  frequencyPenalty?: number;
+
+  /** Presence penalty (-2 to 2 for OpenAI) */
+  presencePenalty?: number;
+
+  /** Stop sequences */
+  stop?: string[];
+
+  /** Available tools for function calling */
+  tools?: Tool[];
+
+  /** Force tool usage */
+  toolChoice?: 'auto' | 'required' | string;
+
+  /** Custom headers to send with requests */
+  headers?: Record<string, string>;
+
+  /** Request timeout in milliseconds */
+  timeout?: number;
+
+  /** Retry configuration */
+  retry?: {
+    maxRetries?: number;
+    backoffMultiplier?: number;
+    initialDelayMs?: number;
+  };
+}
+
+/**
+ * Completion response
+ */
+export interface CompletionResponse {
+  /** Generated text content */
+  content: string;
+
+  /** The model used */
+  model: string;
+
+  /** Stop reason */
+  stopReason?: 'stop_sequence' | 'length' | 'tool_calls' | 'end_turn' | string;
+
+  /** Total tokens used (if available) */
+  usage?: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+  };
+
+  /** Raw provider response for advanced use cases */
+  raw?: unknown;
+
+  /** Finish reason from provider */
+  finishReason?: string;
+
+  /** Tool calls if function calling was used */
+  toolCalls?: Array<{
+    id?: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+}
+
+/**
+ * Streaming completion chunk
+ */
+export interface CompletionChunk {
+  /** Delta content */
+  delta: string;
+
+  /** Stop reason if stream ended */
+  stopReason?: string;
+
+  /** Usage at end of stream */
+  usage?: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+  };
+}
+
+/**
+ * Provider configuration options
+ */
+export interface ProviderConfig {
+  /** Provider type */
+  type: ProviderType;
+
+  /** API key */
+  apiKey?: string;
+
+  /** Base URL for API */
+  baseUrl?: string;
+
+  /** Default model */
+  model?: string;
+
+  /** Request timeout */
+  timeout?: number;
+
+  /** Retry configuration */
+  retry?: {
+    maxRetries?: number;
+    backoffMultiplier?: number;
+    initialDelayMs?: number;
+  };
+
+  /** Custom headers */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Error response from provider
+ */
+export interface ProviderError extends Error {
+  name: string;
+  message: string;
+  code?: string;
+  statusCode?: number;
+  details?: unknown;
+  retryable?: boolean;
+}
+
+/**
+ * Provider interface that all providers must implement
+ */
+export interface IProvider {
+  /** Create a completion request */
+  complete(request: CompletionRequest): Promise<CompletionResponse>;
+
+  /** Stream a completion request */
+  completeStream(
+    request: CompletionRequest
+  ): AsyncIterable<CompletionChunk>;
+
+  /** Validate that the configuration is correct */
+  validate(): Promise<void>;
+
+  /** Parse model string (e.g., 'openai/gpt-4' -> 'gpt-4') */
+  parseModel(model: string): string;
+
+  /** Enable or disable debug mode */
+  setDebug(debug: boolean): void;
+
+  /** Set custom logger function */
+  setLogger(logger: (level: string, message: string, data?: unknown) => void): void;
+}
+
+/**
+ * Global completion options
+ */
+export interface CompletionOptions {
+  /** Enable request logging for debugging */
+  debug?: boolean;
+
+  /** Custom logger function */
+  logger?: (level: string, message: string, data?: unknown) => void;
+
+  /** Global timeout override */
+  globalTimeout?: number;
+
+  /** Retry configuration override */
+  globalRetry?: {
+    maxRetries?: number;
+    backoffMultiplier?: number;
+    initialDelayMs?: number;
+  };
+}