llmjs2 0.0.2 → 1.0.0

package/src/agent.ts

@@ -0,0 +1,285 @@
+/**
+ * Agent - Stateful conversation manager with tool support
+ */
+
+import {
+  completion,
+  streamCompletion,
+  CompletionRequest,
+  CompletionResponse,
+  CompletionChunk,
+  Message,
+  Tool,
+  LLMError,
+} from './index.js';
+
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+  /** Model identifier (e.g., 'ollama/qwen3.5:397b-cloud') */
+  model: string;
+
+  /** API key for the provider (optional, reads from OLLAMA_CLOUD_API_KEY env by default) */
+  apiKey?: string;
+
+  /** Base URL for the API (optional, defaults to https://ollama.com) */
+  baseUrl?: string;
+
+  /** System instruction for the agent */
+  instruction?: string;
+
+  /** Available tools/functions */
+  tools?: Tool[];
+
+  /** Tool executor function - receives tool name and arguments, returns result string */
+  toolExecutor?: (toolName: string, args: Record<string, unknown>) => string;
+}
+
+/**
+ * Agent generation request
+ */
+export interface AgentGenerateRequest {
+  /** User prompt/message */
+  userPrompt: string;
+
+  /** Optional images (base64 or URLs) */
+  images?: string[];
+
+  /** Optional reference documents or context */
+  references?: string[];
+
+  /** Additional context variables */
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Agent generation response
+ */
+export interface AgentGenerateResponse {
+  /** Generated response */
+  response: string;
+
+  /** Full completion response from provider */
+  completion: CompletionResponse;
+}
+
+/**
+ * Stateful agent for conversations and tool use
+ */
+export class Agent {
+  private config: AgentConfig;
+  private conversationHistory: Message[] = [];
+
+  constructor(config: AgentConfig) {
+    if (!config.model) {
+      throw new LLMError('Model is required in agent config', 'MISSING_MODEL');
+    }
+
+    this.config = config;
+
+    // Initialize conversation with system instruction
+    if (config.instruction) {
+      this.conversationHistory.push({
+        role: 'system',
+        content: config.instruction,
+      });
+    }
+  }
+
+  /**
+   * Generate a response for a user message
+   */
+  async generate(request: AgentGenerateRequest): Promise<AgentGenerateResponse> {
+    if (!request.userPrompt) {
+      throw new LLMError('userPrompt is required', 'MISSING_USER_PROMPT');
+    }
+
+    // Build user message with context
+    let userMessage = request.userPrompt;
+
+    if (request.images && request.images.length > 0) {
+      userMessage += `\n\n[Images: ${request.images.length} image(s) attached]`;
+    }
+
+    if (request.references && request.references.length > 0) {
+      userMessage += '\n\nReferences:\n' + request.references.join('\n---\n');
+    }
+
+    if (request.context && Object.keys(request.context).length > 0) {
+      userMessage +=
+        '\n\nContext: ' + JSON.stringify(request.context, null, 2);
+    }
+
+    // Add user message to history
+    this.conversationHistory.push({
+      role: 'user',
+      content: userMessage,
+    });
+
+    // Get initial completion
+    let completion_result = await this.getCompletion();
+    let toolCalls = completion_result.toolCalls;
+    let maxIterations = 10;
+    let iterations = 0;
+
+    // Handle tool calls in a loop
+    while (toolCalls && toolCalls.length > 0 && iterations < maxIterations) {
+      iterations++;
+
+      // Execute all tool calls
+      const toolResults: string[] = [];
+      
+      for (const toolCall of toolCalls) {
+        try {
+          let result: string;
+          
+          if (this.config.toolExecutor) {
+            // Use provided tool executor
+            result = this.config.toolExecutor(toolCall.name, toolCall.arguments);
+          } else {
+            // Fallback: return error
+            result = `Tool '${toolCall.name}' not configured`;
+          }
+          
+          toolResults.push(`Tool: ${toolCall.name}\nResult: ${result}`);
+        } catch (error) {
+          toolResults.push(`Tool: ${toolCall.name}\nError: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+
+      // Add tool results to conversation
+      this.conversationHistory.push({
+        role: 'user',
+        content: 'Tool Results:\n' + toolResults.join('\n\n'),
+      });
+
+      // Get next completion
+      completion_result = await this.getCompletion();
+      toolCalls = completion_result.toolCalls;
+    }
+
+    // Add final assistant response to history
+    this.conversationHistory.push({
+      role: 'assistant',
+      content: completion_result.content,
+    });
+
+    return {
+      response: completion_result.content,
+      completion: completion_result,
+    };
+  }
+
+  /**
+   * Get completion from the model
+   */
+  private async getCompletion(): Promise<CompletionResponse> {
+    const completionRequest: CompletionRequest = {
+      model: this.config.model,
+      apiKey: this.config.apiKey,
+      baseUrl: this.config.baseUrl,
+      messages: this.conversationHistory,
+      tools: this.config.tools,
+    };
+
+    return completion(completionRequest);
+  }
+
+  /**
+   * Stream a response for a user message
+   */
+  async *generateStream(
+    request: AgentGenerateRequest
+  ): AsyncIterable<CompletionChunk> {
+    if (!request.userPrompt) {
+      throw new LLMError('userPrompt is required', 'MISSING_USER_PROMPT');
+    }
+
+    // Build user message with context
+    let userMessage = request.userPrompt;
+
+    if (request.images && request.images.length > 0) {
+      userMessage += `\n\n[Images: ${request.images.length} image(s) attached]`;
+    }
+
+    if (request.references && request.references.length > 0) {
+      userMessage += '\n\nReferences:\n' + request.references.join('\n---\n');
+    }
+
+    if (request.context && Object.keys(request.context).length > 0) {
+      userMessage +=
+        '\n\nContext: ' + JSON.stringify(request.context, null, 2);
+    }
+
+    // Add user message to history
+    this.conversationHistory.push({
+      role: 'user',
+      content: userMessage,
+    });
+
+    // Create completion request
+    const completionRequest: CompletionRequest = {
+      model: this.config.model,
+      apiKey: this.config.apiKey,
+      baseUrl: this.config.baseUrl,
+      messages: this.conversationHistory,
+      tools: this.config.tools,
+    };
+
+    // Stream and collect response
+    let fullResponse = '';
+
+    const stream = streamCompletion(completionRequest);
+    for await (const chunk of stream) {
+      fullResponse += chunk.delta;
+      yield chunk;
+    }
+
+    // Add assistant response to history
+    this.conversationHistory.push({
+      role: 'assistant',
+      content: fullResponse,
+    });
+  }
+
+  /**
+   * Get conversation history
+   */
+  getHistory(): Message[] {
+    return [...this.conversationHistory];
+  }
+
+  /**
+   * Clear conversation history (keeps system instruction if set)
+   */
+  clearHistory(): void {
+    if (this.config.instruction) {
+      this.conversationHistory = [
+        {
+          role: 'system',
+          content: this.config.instruction,
+        },
+      ];
+    } else {
+      this.conversationHistory = [];
+    }
+  }
+
+  /**
+   * Add a message to history
+   */
+  addMessage(role: 'system' | 'user' | 'assistant', content: string): void {
+    this.conversationHistory.push({
+      role,
+      content,
+    });
+  }
+
+  /**
+   * Get the current configuration
+   */
+  getConfig(): AgentConfig {
+    return { ...this.config };
+  }
+}

package/src/index.ts

@@ -0,0 +1,268 @@
+/**
+ * llmjs2 - Enterprise-grade LLM abstraction layer
+ * Unified API for OpenAI and Ollama
+ */
+
+import {
+  CompletionRequest,
+  CompletionResponse,
+  CompletionChunk,
+  CompletionOptions,
+  ProviderType,
+  IProvider,
+} from './types.js';
+import { OpenAIProvider } from './providers/openai.js';
+import { OllamaProvider } from './providers/ollama.js';
+import { LLMError } from './providers/base.js';
+
+/**
+ * Global configuration for completion
+ */
+let globalOptions: CompletionOptions = {};
+
+/**
+ * Provider cache
+ */
+const providerCache: Map<string, IProvider> = new Map();
+
+/**
+ * Configure global settings
+ */
+export function configure(options: CompletionOptions): void {
+  globalOptions = { ...globalOptions, ...options };
+}
+
+/**
+ * Get provider type from model string
+ */
+function getProviderType(model: string): ProviderType {
+  if (model.startsWith('openai/')) {
+    return 'openai';
+  }
+  if (model.startsWith('ollama/')) {
+    return 'ollama';
+  }
+  // Default to openai if no prefix specified
+  return 'openai';
+}
+
+/**
+ * Create appropriate provider instance
+ */
+function createProvider(
+  providerType: ProviderType,
+  request: CompletionRequest
+): IProvider {
+  const cacheKey = `${providerType}:${request.apiKey || 'default'}:${request.baseUrl || 'default'}`;
+
+  // Return cached provider if available
+  if (providerCache.has(cacheKey)) {
+    return providerCache.get(cacheKey)!;
+  }
+
+  let provider: IProvider;
+
+  switch (providerType) {
+    case 'openai': {
+      const apiKey = request.apiKey || process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        throw new LLMError(
+          'OpenAI API key is required. Pass it as apiKey in the request or set OPENAI_API_KEY environment variable.',
+          'MISSING_API_KEY'
+        );
+      }
+      provider = new OpenAIProvider({
+        type: 'openai',
+        apiKey: apiKey,
+        baseUrl: request.baseUrl,
+        timeout: request.timeout ?? globalOptions.globalTimeout,
+        retry: request.retry ?? globalOptions.globalRetry,
+      });
+      break;
+    }
+
+    case 'ollama': {
+      provider = new OllamaProvider({
+        type: 'ollama',
+        baseUrl: request.baseUrl,
+        timeout: request.timeout ?? globalOptions.globalTimeout,
+        retry: request.retry ?? globalOptions.globalRetry,
+      });
+      break;
+    }
+
+    default:
+      throw new LLMError(`Unsupported provider: ${providerType}`, 'UNKNOWN_PROVIDER');
+  }
+
+  // Apply global settings
+  if (globalOptions.debug) {
+    provider.setDebug(true);
+  }
+
+  if (globalOptions.logger) {
+    provider.setLogger(globalOptions.logger);
+  }
+
+  // Cache the provider
+  providerCache.set(cacheKey, provider);
+
+  return provider;
+}
+
+/**
+ * Create a completion request
+ *
+ * @example
+ * import { completion } from 'llmjs2';
+ *
+ * const result = await completion({
+ *   model: 'openai/gpt-4',
+ *   apiKey: 'sk-...',
+ *   messages: [
+ *     { role: 'user', content: 'Hello!' }
+ *   ]
+ * });
+ *
+ * console.log(result.content);
+ */
+export async function completion(
+  request: CompletionRequest
+): Promise<CompletionResponse> {
+  if (!request.model) {
+    throw new LLMError('Model is required', 'MISSING_MODEL');
+  }
+
+  const providerType = getProviderType(request.model);
+  const provider = createProvider(providerType, request);
+
+  try {
+    return await provider.complete(request);
+  } catch (error) {
+    if (error instanceof LLMError) {
+      throw error;
+    }
+    throw new LLMError(
+      `Completion failed: ${error instanceof Error ? error.message : String(error)}`,
+      'COMPLETION_FAILED',
+      undefined,
+      error
+    );
+  }
+}
+
+/**
+ * Stream a completion request
+ *
+ * @example
+ * import { streamCompletion } from 'llmjs2';
+ *
+ * const stream = streamCompletion({
+ *   model: 'openai/gpt-4',
+ *   apiKey: 'sk-...',
+ *   messages: [
+ *     { role: 'user', content: 'Write a poem' }
+ *   ]
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.delta);
+ * }
+ */
+export async function* streamCompletion(
+  request: CompletionRequest
+): AsyncIterable<CompletionChunk> {
+  if (!request.model) {
+    throw new LLMError('Model is required', 'MISSING_MODEL');
+  }
+
+  const providerType = getProviderType(request.model);
+  const provider = createProvider(providerType, request);
+
+  try {
+    yield* provider.completeStream(request);
+  } catch (error) {
+    if (error instanceof LLMError) {
+      throw error;
+    }
+    throw new LLMError(
+      `Stream failed: ${error instanceof Error ? error.message : String(error)}`,
+      'STREAM_FAILED',
+      undefined,
+      error
+    );
+  }
+}
+
+/**
+ * Validate provider connectivity and configuration
+ */
+export async function validateProvider(
+  model: string,
+  apiKey?: string,
+  baseUrl?: string
+): Promise<void> {
+  const providerType = getProviderType(model);
+
+  const request: CompletionRequest = {
+    model,
+    apiKey,
+    baseUrl,
+    messages: [{ role: 'user', content: 'test' }],
+  };
+
+  const provider = createProvider(providerType, request);
+
+  try {
+    await provider.validate();
+  } catch (error) {
+    if (error instanceof LLMError) {
+      throw error;
+    }
+    throw new LLMError(
+      `Validation failed: ${error instanceof Error ? error.message : String(error)}`,
+      'VALIDATION_FAILED'
+    );
+  }
+}
+
+/**
+ * Clear provider cache
+ */
+export function clearProviderCache(): void {
+  providerCache.clear();
+}
+
+/**
+ * Export types for consumers
+ */
+export type {
+  CompletionRequest,
+  CompletionResponse,
+  CompletionChunk,
+  CompletionOptions,
+  Message,
+  MessageRole,
+  Tool,
+  ProviderType,
+  ProviderConfig,
+  ProviderError,
+} from './types.js';
+
+/**
+ * Export error class
+ */
+export { LLMError };
+
+/**
+ * Export provider classes for advanced use cases
+ */
+export { OpenAIProvider } from './providers/openai.js';
+export { OllamaProvider } from './providers/ollama.js';
+export { BaseProvider } from './providers/base.js';
+
+/**
+ * Export Agent for stateful conversations
+ */
+export { Agent } from './agent.js';
+export type { AgentConfig, AgentGenerateRequest, AgentGenerateResponse } from './agent.js';