llmjs2 0.0.2 → 1.0.0

package/src/providers/base.ts

@@ -0,0 +1,216 @@
+/**
+ * Base provider class with common functionality
+ */
+
+import {
+  IProvider,
+  CompletionRequest,
+  CompletionResponse,
+  CompletionChunk,
+  ProviderConfig,
+  ProviderError,
+} from '../types.js';
+
+/**
+ * Validation helper for requests
+ */
+export function validateCompletionRequest(request: CompletionRequest): void {
+  if (!request.model) {
+    throw new Error('Model is required');
+  }
+
+  if (!Array.isArray(request.messages) || request.messages.length === 0) {
+    throw new Error('Messages array is required and must not be empty');
+  }
+
+  // Validate message structure
+  for (const msg of request.messages) {
+    if (!msg.role || msg.content === undefined || msg.content === null) {
+      throw new Error('Each message must have role and content');
+    }
+    if (!['system', 'user', 'assistant'].includes(msg.role)) {
+      throw new Error(`Invalid role: ${msg.role}`);
+    }
+    if (typeof msg.content !== 'string') {
+      throw new Error('Message content must be a string');
+    }
+  }
+
+  // Validate numeric ranges
+  if (request.temperature !== undefined && request.temperature !== null) {
+    if (typeof request.temperature !== 'number' || request.temperature < 0 || request.temperature > 2) {
+      throw new Error('Temperature must be a number between 0 and 2');
+    }
+  }
+
+  if (request.topP !== undefined && request.topP !== null) {
+    if (typeof request.topP !== 'number' || request.topP < 0 || request.topP > 1) {
+      throw new Error('topP must be a number between 0 and 1');
+    }
+  }
+
+  if (request.maxTokens !== undefined && request.maxTokens !== null) {
+    if (typeof request.maxTokens !== 'number' || request.maxTokens < 1) {
+      throw new Error('maxTokens must be a number greater than 0');
+    }
+  }
+
+  if (request.frequencyPenalty !== undefined && request.frequencyPenalty !== null) {
+    if (typeof request.frequencyPenalty !== 'number' || request.frequencyPenalty < -2 || request.frequencyPenalty > 2) {
+      throw new Error('frequencyPenalty must be a number between -2 and 2');
+    }
+  }
+
+  if (request.presencePenalty !== undefined && request.presencePenalty !== null) {
+    if (typeof request.presencePenalty !== 'number' || request.presencePenalty < -2 || request.presencePenalty > 2) {
+      throw new Error('presencePenalty must be a number between -2 and 2');
+    }
+  }
+}
+
+/**
+ * Custom error class for provider errors
+ */
+export class LLMError extends Error implements ProviderError {
+  code?: string;
+  statusCode?: number;
+  details?: unknown;
+  retryable?: boolean;
+
+  constructor(
+    message: string,
+    code?: string,
+    statusCode?: number,
+    details?: unknown,
+    retryable?: boolean
+  ) {
+    super(message);
+    this.name = 'LLMError';
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.retryable = retryable ?? false;
+  }
+}
+
+/**
+ * Retry helper with exponential backoff
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxRetries?: number;
+    backoffMultiplier?: number;
+    initialDelayMs?: number;
+  } = {}
+): Promise<T> {
+  const maxRetries = options.maxRetries ?? 3;
+  const backoffMultiplier = options.backoffMultiplier ?? 2;
+  const initialDelayMs = options.initialDelayMs ?? 1000;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+
+      // Check if error is retryable
+      const isRetryable =
+        error instanceof LLMError
+          ? error.retryable
+          : error instanceof Error &&
+            (error.message.includes('timeout') ||
+              error.message.includes('ECONNREFUSED') ||
+              error.message.includes('ENOTFOUND'));
+
+      if (!isRetryable || attempt === maxRetries - 1) {
+        throw error;
+      }
+
+      // Exponential backoff
+      const delay = initialDelayMs * Math.pow(backoffMultiplier, attempt);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError || new Error('Retry failed');
+}
+
+/**
+ * Base provider class
+ */
+export abstract class BaseProvider implements IProvider {
+  protected config: ProviderConfig;
+  protected debug: boolean;
+  protected logger: (level: string, message: string, data?: unknown) => void;
+
+  constructor(config: ProviderConfig) {
+    this.config = config;
+    this.debug = false;
+    this.logger = (level: string, message: string, data?: unknown) => {
+      if (this.debug) {
+        console.log(`[${level}] ${message}`, data ?? '');
+      }
+    };
+  }
+
+  setDebug(debug: boolean): void {
+    this.debug = debug;
+  }
+
+  setLogger(
+    logger: (level: string, message: string, data?: unknown) => void
+  ): void {
+    this.logger = logger;
+  }
+
+  abstract complete(request: CompletionRequest): Promise<CompletionResponse>;
+
+  abstract completeStream(
+    request: CompletionRequest
+  ): AsyncIterable<CompletionChunk>;
+
+  abstract validate(): Promise<void>;
+
+  abstract parseModel(model: string): string;
+
+  /**
+   * Get the timeout for a request
+   */
+  protected getTimeout(request?: CompletionRequest): number {
+    return (
+      request?.timeout ??
+      this.config.timeout ??
+      30000 // Default 30 seconds
+    );
+  }
+
+  /**
+   * Get retry config
+   */
+  protected getRetryConfig(request?: CompletionRequest) {
+    return {
+      maxRetries: request?.retry?.maxRetries ?? this.config.retry?.maxRetries ?? 3,
+      backoffMultiplier:
+        request?.retry?.backoffMultiplier ??
+        this.config.retry?.backoffMultiplier ??
+        2,
+      initialDelayMs:
+        request?.retry?.initialDelayMs ??
+        this.config.retry?.initialDelayMs ??
+        1000,
+    };
+  }
+
+  /**
+   * Get headers including custom headers
+   */
+  protected getHeaders(request?: CompletionRequest): Record<string, string> {
+    return {
+      ...(this.config.headers ?? {}),
+      ...(request?.headers ?? {}),
+    };
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Provider exports
+ */
+
+export { OpenAIProvider } from './openai.js';
+export { OllamaProvider } from './ollama.js';
+export { BaseProvider } from './base.js';
+export type { IProvider } from '../types.js';

package/src/providers/ollama.ts

@@ -0,0 +1,429 @@
+/**
+ * Ollama provider implementation
+ */
+
+import { URL } from 'url';
+
+import {
+  CompletionRequest,
+  CompletionResponse,
+  CompletionChunk,
+  ProviderConfig,
+} from '../types.js';
+import {
+  BaseProvider,
+  validateCompletionRequest,
+  withRetry,
+  LLMError,
+} from './base.js';
+
+/**
+ * Ollama API request format
+ */
+interface OllamaRequest {
+  model: string;
+  messages: Array<{
+    role: string;
+    content: string;
+  }>;
+  stream?: boolean;
+  temperature?: number;
+  top_p?: number;
+  top_k?: number;
+  num_predict?: number;
+  stop?: string[];
+}
+
+/**
+ * Ollama API response format
+ */
+interface OllamaResponse {
+  model: string;
+  created_at: string;
+  message?: {
+    role: string;
+    content: string;
+  };
+  done: boolean;
+  total_duration?: number;
+  load_duration?: number;
+  prompt_eval_count?: number;
+  prompt_eval_duration?: number;
+  eval_count?: number;
+  eval_duration?: number;
+}
+
+/**
+ * Ollama Provider implementation
+ */
+export class OllamaProvider extends BaseProvider {
+  private baseUrl: string = 'https://ollama.com';
+  private apiKey?: string;
+
+  constructor(config: ProviderConfig) {
+    super(config);
+
+    // Get API key from config or env variable
+    const apiKey = config.apiKey || process.env.OLLAMA_CLOUD_API_KEY;
+
+    if (apiKey) {
+      this.apiKey = apiKey;
+      // Default to Ollama Cloud for API key-based requests
+      if (!config.baseUrl) {
+        this.baseUrl = 'https://ollama.com';
+      } else {
+        this.baseUrl = config.baseUrl;
+      }
+    } else {
+      // Local Ollama setup
+      if (config.baseUrl) {
+        this.baseUrl = config.baseUrl;
+      }
+    }
+  }
+
+  /**
+   * Parse model string (e.g., 'ollama/mistral' -> 'mistral')
+   */
+  parseModel(model: string): string {
+    if (model.startsWith('ollama/')) {
+      return model.slice(7); // Remove 'ollama/' prefix
+    }
+    return model;
+  }
+
+  /**
+   * Validate configuration
+   */
+  async validate(): Promise<void> {
+    try {
+      // Make a simple request to verify Ollama is running
+      const response = await this.makeRequest<{ models: Array<{ name: string }> }>(
+        '/api/tags',
+        'GET'
+      );
+
+      if (!Array.isArray(response.models)) {
+        throw new Error('Invalid Ollama response format');
+      }
+
+      this.logger('info', 'Ollama API validation successful');
+    } catch (error) {
+      throw new LLMError(
+        `Ollama validation failed: ${error instanceof Error ? error.message : String(error)}`,
+        'VALIDATION_FAILED',
+        undefined,
+        null,
+        true
+      );
+    }
+  }
+
+  /**
+   * Create a completion
+   */
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    validateCompletionRequest(request);
+
+    const model = this.parseModel(request.model);
+
+    return withRetry(
+      async () => {
+        const ollamaRequest: OllamaRequest = {
+          model,
+          stream: false,
+          messages: request.messages.map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+          })),
+        };
+
+        this.logger('debug', 'Ollama completion request', {
+          model,
+          messageCount: request.messages.length,
+        });
+
+        // Use non-streaming request for complete()
+        const response = await this.makeRequest<OllamaResponse>(
+          '/api/chat',
+          'POST',
+          ollamaRequest,
+          request
+        );
+
+        const fullResponse = response.message?.content || '';
+
+        const result: CompletionResponse = {
+          content: fullResponse,
+          model: model,
+          stopReason: 'stop_sequence',
+          raw: response,
+        };
+
+        this.logger('debug', 'Ollama completion response', {
+          model,
+          contentLength: fullResponse.length,
+        });
+
+        return result;
+      },
+      this.getRetryConfig(request)
+    );
+  }
+
+  /**
+   * Stream completion
+   */
+  async *completeStream(
+    request: CompletionRequest
+  ): AsyncIterable<CompletionChunk> {
+    validateCompletionRequest(request);
+
+    const model = this.parseModel(request.model);
+
+    const ollamaRequest: OllamaRequest = {
+      model,
+      stream: true,
+      messages: request.messages.map((msg) => ({
+        role: msg.role,
+        content: msg.content,
+      })),
+    };
+
+    this.logger('debug', 'Ollama stream request', { model });
+
+    const chunks = await this.streamCompletion(ollamaRequest, request);
+
+    for await (const chunk of chunks) {
+      if (chunk.message?.content) {
+        yield {
+          delta: chunk.message.content,
+          stopReason: chunk.done ? 'stop_sequence' : undefined,
+        };
+      }
+    }
+  }
+
+  /**
+   * Internal stream completion handler
+   */
+  private async *streamCompletion(
+    body: OllamaRequest,
+    request?: CompletionRequest
+  ): AsyncIterable<OllamaResponse> {
+    const stream = await this.makeStreamRequest(
+      '/api/chat',
+      'POST',
+      body,
+      request
+    );
+
+    for await (const chunk of stream) {
+      yield chunk;
+    }
+  }
+
+  /**
+   * Make HTTP request to Ollama API using fetch
+   */
+  private async makeRequest<T>(
+    path: string,
+    method: string = 'POST',
+    body?: unknown,
+    request?: CompletionRequest
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl).toString();
+    const timeout = this.getTimeout(request);
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.getHeaders(request),
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    this.logger('info', '=== Ollama Request ===', {
+      url,
+      method,
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new LLMError(
+          `Ollama API error: ${errorText}`,
+          'API_ERROR',
+          response.status,
+          null,
+          response.status === 503 || response.status === 502
+        );
+      }
+
+      const data = await response.json();
+      return data as T;
+    } catch (error) {
+      if (error instanceof LLMError) {
+        throw error;
+      }
+      if (
+        error instanceof Error &&
+        error.name === 'AbortError'
+      ) {
+        throw new LLMError(
+          'Ollama request timeout',
+          'TIMEOUT',
+          undefined,
+          null,
+          true
+        );
+      }
+      throw new LLMError(
+        `Ollama request failed: ${error instanceof Error ? error.message : String(error)}`,
+        'REQUEST_FAILED',
+        undefined,
+        { error: error instanceof Error ? error.message : String(error) },
+        true
+      );
+    }
+  }
+
+  /**
+   * Stream HTTP request using fetch
+   */
+  private makeStreamRequest(
+    path: string,
+    method: string = 'POST',
+    body?: unknown,
+    request?: CompletionRequest
+  ): AsyncIterable<OllamaResponse> {
+    const self = this;
+
+    return {
+      async *[Symbol.asyncIterator]() {
+        const url = new URL(path, self.baseUrl).toString();
+        const timeout = self.getTimeout(request);
+
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+          ...self.getHeaders(request),
+        };
+
+        if (self.apiKey) {
+          headers['Authorization'] = `Bearer ${self.apiKey}`;
+        }
+
+        self.logger('debug', 'Ollama stream request', {
+          url,
+          method,
+          headers,
+          body: JSON.stringify(body),
+        });
+
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+          const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+          });
+
+          clearTimeout(timeoutId);
+
+          if (!response.ok) {
+            const errorText = await response.text();
+            throw new LLMError(
+              `Ollama stream error: ${errorText}`,
+              'STREAM_ERROR',
+              response.status
+            );
+          }
+
+          const reader = response.body?.getReader();
+          if (!reader) {
+            throw new LLMError(
+              'No response body',
+              'STREAM_ERROR',
+              undefined
+            );
+          }
+
+          const decoder = new TextDecoder();
+          let buffer = '';
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            buffer += decoder.decode(value, { stream: true });
+            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) continue;
+
+              try {
+                const chunk = JSON.parse(line) as OllamaResponse;
+                yield chunk;
+              } catch (error) {
+                // Ignore parse errors in stream
+              }
+            }
+          }
+
+          // Process any remaining data in buffer
+          if (buffer.trim()) {
+            try {
+              const chunk = JSON.parse(buffer) as OllamaResponse;
+              yield chunk;
+            } catch (error) {
+              // Ignore parse errors
+            }
+          }
+        } catch (error) {
+          if (error instanceof LLMError) {
+            throw error;
+          }
+          if (
+            error instanceof Error &&
+            error.name === 'AbortError'
+          ) {
+            throw new LLMError(
+              'Ollama stream request timeout',
+              'TIMEOUT',
+              undefined,
+              null,
+              true
+            );
+          }
+          throw new LLMError(
+            `Ollama stream request failed: ${error instanceof Error ? error.message : String(error)}`,
+            'REQUEST_FAILED',
+            undefined,
+            { error: error instanceof Error ? error.message : String(error) },
+            true
+          );
+        }
+      },
+    };
+  }
+}