specvector 0.0.1 → 0.1.0

package/src/llm/factory.ts

@@ -0,0 +1,146 @@
+/**
+ * Provider Factory - Creates LLM providers based on configuration.
+ */
+
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+import type { LLMProvider, LLMError } from "./provider";
+import { LLMErrors } from "./provider";
+import { OpenRouterProvider } from "./openrouter";
+import { OllamaProvider } from "./ollama";
+
+/**
+ * Supported provider types.
+ */
+export type ProviderType = "openrouter" | "ollama";
+
+/**
+ * Unified configuration for creating any LLM provider.
+ */
+export interface ProviderConfig {
+  /** Provider type */
+  provider: ProviderType;
+  /** Model identifier */
+  model: string;
+  /** API key (required for OpenRouter) */
+  apiKey?: string;
+  /** Custom host URL (optional, for Ollama) */
+  host?: string;
+}
+
+/**
+ * Create an LLM provider based on configuration.
+ * 
+ * @example
+ * ```typescript
+ * // OpenRouter
+ * const result = createProvider({
+ *   provider: "openrouter",
+ *   model: "anthropic/claude-sonnet-4.5",
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ * });
+ * 
+ * // Ollama
+ * const result = createProvider({
+ *   provider: "ollama",
+ *   model: "llama3.2",
+ * });
+ * ```
+ */
+export function createProvider(
+  config: ProviderConfig
+): Result<LLMProvider, LLMError> {
+  // Validate common fields
+  if (!config.provider) {
+    return err(LLMErrors.providerError("Provider type is required"));
+  }
+
+  if (!config.model) {
+    return err(LLMErrors.invalidModel("Model is required"));
+  }
+
+  // Route to appropriate provider
+  switch (config.provider) {
+    case "openrouter":
+      return createOpenRouterFromConfig(config);
+    
+    case "ollama":
+      return createOllamaFromConfig(config);
+    
+    default:
+      return err(
+        LLMErrors.providerError(
+          `Unsupported provider: "${(config as { provider: string }).provider}". ` +
+          `Supported providers: openrouter, ollama`
+        )
+      );
+  }
+}
+
+/**
+ * Create OpenRouter provider from unified config.
+ */
+function createOpenRouterFromConfig(
+  config: ProviderConfig
+): Result<LLMProvider, LLMError> {
+  // Check for API key
+  const apiKey = config.apiKey ?? process.env.OPENROUTER_API_KEY;
+  
+  if (!apiKey) {
+    return err(
+      LLMErrors.authFailed(
+        "OpenRouter requires an API key. Set OPENROUTER_API_KEY environment variable " +
+        "or provide apiKey in config."
+      )
+    );
+  }
+
+  return ok(new OpenRouterProvider({
+    apiKey,
+    model: config.model,
+  }));
+}
+
+/**
+ * Create Ollama provider from unified config.
+ */
+function createOllamaFromConfig(
+  config: ProviderConfig
+): Result<LLMProvider, LLMError> {
+  return ok(new OllamaProvider({
+    model: config.model,
+    host: config.host,
+  }));
+}
+
+/**
+ * Create provider from environment variables.
+ * 
+ * Reads SPECVECTOR_PROVIDER (default: "openrouter") and SPECVECTOR_MODEL.
+ */
+export function createProviderFromEnv(): Result<LLMProvider, LLMError> {
+  const provider = (process.env.SPECVECTOR_PROVIDER ?? "openrouter") as ProviderType;
+  const model = process.env.SPECVECTOR_MODEL;
+
+  if (!model) {
+    return err(
+      LLMErrors.invalidModel(
+        "SPECVECTOR_MODEL environment variable is required"
+      )
+    );
+  }
+
+  return createProvider({
+    provider,
+    model,
+    apiKey: process.env.OPENROUTER_API_KEY,
+    host: process.env.OLLAMA_HOST,
+  });
+}
+
+/**
+ * Get list of supported providers.
+ */
+export function getSupportedProviders(): ProviderType[] {
+  return ["openrouter", "ollama"];
+}

package/src/llm/index.ts

@@ -0,0 +1,50 @@
+/**
+ * LLM Provider module - Public API
+ * 
+ * @example
+ * ```typescript
+ * import { createProvider, type ProviderConfig } from "./llm";
+ * 
+ * const config: ProviderConfig = {
+ *   provider: "openrouter",
+ *   model: "anthropic/claude-sonnet-4.5",
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ * };
+ * 
+ * const result = createProvider(config);
+ * if (result.ok) {
+ *   const response = await result.value.chat([
+ *     { role: "user", content: "Hello!" }
+ *   ]);
+ * }
+ * ```
+ */
+
+// Re-export types
+export type {
+  Message,
+  MessageRole,
+  Tool,
+  ToolCall,
+  ChatResponse,
+  ChatOptions,
+  TokenUsage,
+  JSONSchema,
+} from "../types/llm";
+
+// Re-export provider interface and errors
+export type { LLMProvider, LLMError, LLMErrorCode } from "./provider";
+export { LLMErrors, isRetryableError, createLLMError } from "./provider";
+
+// Re-export factory
+export {
+  createProvider,
+  createProviderFromEnv,
+  getSupportedProviders,
+  type ProviderConfig,
+  type ProviderType,
+} from "./factory";
+
+// Re-export individual providers for direct use
+export { OpenRouterProvider, type OpenRouterConfig } from "./openrouter";
+export { OllamaProvider, type OllamaConfig } from "./ollama";

package/src/llm/ollama.ts

@@ -0,0 +1,313 @@
+/**
+ * Ollama LLM Provider implementation.
+ * Uses local Ollama API at /api/chat for self-hosted models.
+ */
+
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+import type { Message, ChatResponse, ChatOptions, Tool, ToolCall } from "../types/llm";
+import type { LLMProvider, LLMError } from "./provider";
+import { LLMErrors } from "./provider";
+
+const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+const DEFAULT_TIMEOUT_MS = 120000; // 2 minutes (local models can be slow)
+
+/**
+ * Configuration for Ollama provider.
+ */
+export interface OllamaConfig {
+  /** Model name (e.g., "llama3.2", "mistral", "codellama") */
+  model: string;
+  /** Ollama host URL (default: http://localhost:11434) */
+  host?: string;
+}
+
+/**
+ * Ollama API request format.
+ */
+interface OllamaRequest {
+  model: string;
+  messages: OllamaMessage[];
+  tools?: OllamaTool[];
+  stream: false;
+  options?: {
+    temperature?: number;
+    num_predict?: number;
+  };
+}
+
+interface OllamaMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_calls?: OllamaToolCall[];
+  tool_name?: string;
+}
+
+interface OllamaTool {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: object;
+  };
+}
+
+interface OllamaToolCall {
+  function: {
+    name: string;
+    arguments: Record<string, unknown>;  // Object, not JSON string
+  };
+}
+
+/**
+ * Ollama API response format.
+ */
+interface OllamaResponse {
+  model: string;
+  message: {
+    role: string;
+    content: string;
+    tool_calls?: OllamaToolCall[];
+  };
+  done: boolean;
+  done_reason?: string;
+  prompt_eval_count?: number;
+  eval_count?: number;
+  total_duration?: number;
+}
+
+interface OllamaErrorResponse {
+  error: string;
+}
+
+/**
+ * Ollama LLM Provider for local/self-hosted models.
+ */
+export class OllamaProvider implements LLMProvider {
+  readonly name = "ollama";
+  readonly model: string;
+  
+  private readonly host: string;
+
+  constructor(config: OllamaConfig) {
+    this.model = config.model;
+    this.host = config.host ?? process.env.OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST;
+  }
+
+  /**
+   * Create provider from environment variables.
+   */
+  static fromEnv(model: string): OllamaProvider {
+    return new OllamaProvider({ model });
+  }
+
+  /**
+   * Check if Ollama is running.
+   */
+  async isAvailable(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.host}/api/version`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async chat(
+    messages: Message[],
+    options?: ChatOptions
+  ): Promise<Result<ChatResponse, LLMError>> {
+    const request = this.buildRequest(messages, options);
+
+    // Create abort controller for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
+    try {
+      const response = await fetch(`${this.host}/api/chat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(request),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        return this.handleErrorResponse(response);
+      }
+
+      const data = (await response.json()) as OllamaResponse;
+      return this.parseResponse(data);
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      // Check for abort/timeout
+      if (error instanceof Error && error.name === "AbortError") {
+        return err(LLMErrors.timeout());
+      }
+
+      // Check for connection refused (Ollama not running)
+      if (error instanceof TypeError) {
+        if (error.message.includes("fetch") || 
+            error.message.includes("ECONNREFUSED") ||
+            error.message.includes("Failed to fetch")) {
+          return err(LLMErrors.networkError(error));
+        }
+      }
+
+      return err(
+        LLMErrors.providerError(
+          `Ollama request failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+          error instanceof Error ? error : undefined
+        )
+      );
+    }
+  }
+
+  private buildRequest(
+    messages: Message[],
+    options?: ChatOptions
+  ): OllamaRequest {
+    const request: OllamaRequest = {
+      model: this.model,
+      messages: messages.map(this.mapMessage),
+      stream: false,
+    };
+
+    if (options?.tools && options.tools.length > 0) {
+      request.tools = options.tools.map(this.mapTool);
+    }
+
+    // Build options object if needed
+    const ollamaOptions: OllamaRequest["options"] = {};
+    
+    if (options?.temperature !== undefined) {
+      ollamaOptions.temperature = options.temperature;
+    }
+
+    if (options?.max_tokens !== undefined) {
+      ollamaOptions.num_predict = options.max_tokens;
+    }
+
+    if (Object.keys(ollamaOptions).length > 0) {
+      request.options = ollamaOptions;
+    }
+
+    return request;
+  }
+
+  private mapMessage = (message: Message): OllamaMessage => {
+    const mapped: OllamaMessage = {
+      role: message.role,
+      content: message.content ?? "",
+    };
+
+    // Convert tool calls: our format uses JSON string, Ollama uses object
+    if (message.tool_calls && message.tool_calls.length > 0) {
+      mapped.tool_calls = message.tool_calls.map((tc) => ({
+        function: {
+          name: tc.name,
+          arguments: JSON.parse(tc.arguments),  // Parse JSON string to object
+        },
+      }));
+    }
+
+    // For tool responses, use tool_name instead of name
+    if (message.role === "tool" && message.name) {
+      mapped.tool_name = message.name;
+    }
+
+    return mapped;
+  };
+
+  private mapTool = (tool: Tool): OllamaTool => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    },
+  });
+
+  private parseResponse(data: OllamaResponse): Result<ChatResponse, LLMError> {
+    if (!data.message) {
+      return err(LLMErrors.providerError("Ollama returned empty response"));
+    }
+
+    let toolCalls: ToolCall[] | undefined;
+    if (data.message.tool_calls && data.message.tool_calls.length > 0) {
+      // Generate unique IDs and convert object args to JSON string
+      toolCalls = data.message.tool_calls.map((tc, index) => ({
+        id: `ollama_call_${Date.now()}_${index}`,
+        name: tc.function.name,
+        arguments: JSON.stringify(tc.function.arguments),  // Convert object to JSON string
+      }));
+    }
+
+    // Determine finish reason
+    let finishReason: ChatResponse["finish_reason"] = "stop";
+    if (toolCalls && toolCalls.length > 0) {
+      finishReason = "tool_calls";
+    } else if (data.done_reason === "length") {
+      finishReason = "length";
+    }
+
+    return ok({
+      content: data.message.content || null,
+      tool_calls: toolCalls,
+      usage: {
+        prompt_tokens: data.prompt_eval_count ?? 0,
+        completion_tokens: data.eval_count ?? 0,
+        total_tokens: (data.prompt_eval_count ?? 0) + (data.eval_count ?? 0),
+      },
+      model: data.model,
+      finish_reason: finishReason,
+    });
+  }
+
+  private async handleErrorResponse(
+    response: Response
+  ): Promise<Result<ChatResponse, LLMError>> {
+    let errorMessage = `Ollama API error: ${response.status}`;
+    
+    try {
+      const errorData = (await response.json()) as OllamaErrorResponse;
+      if (errorData.error) {
+        errorMessage = errorData.error;
+      }
+    } catch {
+      // Use default error message
+    }
+
+    // Check for model not found
+    if (response.status === 404 || 
+        errorMessage.toLowerCase().includes("model") ||
+        errorMessage.toLowerCase().includes("not found")) {
+      return err(LLMErrors.invalidModel(this.model));
+    }
+
+    // Check for timeout
+    if (response.status === 408 || response.status === 504) {
+      return err(LLMErrors.timeout());
+    }
+
+    return err(LLMErrors.providerError(errorMessage));
+  }
+}
+
+/**
+ * Create an Ollama provider with validation.
+ */
+export function createOllamaProvider(
+  config: OllamaConfig
+): Result<OllamaProvider, LLMError> {
+  if (!config.model) {
+    return err(LLMErrors.invalidModel("Model is required"));
+  }
+  return ok(new OllamaProvider(config));
+}