vecbox 0.1.0

package/src/providers/llamacpp.ts

@@ -0,0 +1,292 @@
+/**
+ * Llama.cpp Provider - Local embeddings using llama.cpp directly
+ * Uses llama-embedding binary without any external dependencies
+ */
+
+import { access, constants } from 'fs/promises';
+import { join, resolve } from 'path';
+import { EmbeddingProvider } from '@providers/base/EmbeddingProvider';
+import type { EmbedConfig, EmbedInput, EmbedResult, BatchEmbedResult } from '@src/types/index';
+import { logger } from '@src/util/logger';
+import * as http from 'http';
+
+// Extend EmbedConfig to include llamaPath
+interface LlamaCppConfig extends EmbedConfig {
+  llamaPath?: string;
+}
+
+export class LlamaCppProvider extends EmbeddingProvider {
+  private llamaPath: string;
+  private modelPath: string;
+
+  constructor(config: LlamaCppConfig) {
+    super({ ...config, provider: 'llamacpp' });
+    this.modelPath = config.model || 'nomic-embed-text-v1.5.Q4_K_M.gguf';
+    this.llamaPath = config.llamaPath || './llama.cpp/build/bin/llama-embedding';
+    logger.info(`Llama.cpp provider initialized with model: ${this.modelPath}`);
+  }
+
+  // Public API methods
+  getProviderName(): string {
+    return 'Llama.cpp';
+  }
+
+  getDimensions(): number {
+    // Known dimensions for common models
+    const model = this.getModel();
+    if (model.includes('nomic-embed-text-v1.5')) return 768;
+    if (model.includes('nomic-embed-text-v1')) return 768;
+    if (model.includes('all-MiniLM-L6-v2')) return 384;
+    if (model.includes('bge-base')) return 768;
+    if (model.includes('bert-base')) return 768;
+    return 768; // default
+  }
+
+  async isReady(): Promise<boolean> {
+    try {
+      // Check if llama-embedding exists and is executable
+      await access(this.llamaPath, constants.F_OK);
+      await access(this.llamaPath, constants.X_OK);
+      
+      // Check if model file exists
+      const modelPath = await this.getModelPath();
+      await access(modelPath, constants.F_OK);
+      
+      logger.debug('Llama.cpp provider is ready');
+      return true;
+    } catch (error: unknown) {
+      logger.error(`Llama.cpp readiness check failed: ${(error instanceof Error ? error.message : String(error))}`);
+      return false;
+    }
+  }
+
+  async embed(input: EmbedInput): Promise<EmbedResult> {
+    try {
+      logger.debug(`Embedding text with llama.cpp: ${this.getModel()}`);
+      
+      const text = await this.readInput(input);
+      if (!text.trim()) {
+        throw new Error('Text input cannot be empty');
+      }
+
+      // Use HTTP API instead of CLI arguments
+      const requestBody = {
+        input: text,
+        model: await this.getModelPath(),
+        pooling: 'mean',
+        normalize: 2
+      };
+
+      // Execute HTTP request to llama.cpp server
+      const result = await this.executeLlamaEmbedding([JSON.stringify(requestBody)]);
+      
+      // Parse output to extract embedding
+      const embedding = this.parseRawOutput(result.stdout);
+      
+      return {
+        embedding,
+        dimensions: embedding.length,
+        model: this.getModel(),
+        provider: 'llamacpp',
+      };
+    } catch (error: unknown) {
+      logger.error(`Llama.cpp embedding failed: ${(error instanceof Error ? error.message : String(error))}`);
+      throw error;
+    }
+  }
+
+  async embedBatch(inputs: EmbedInput[]): Promise<BatchEmbedResult> {
+    try {
+      logger.debug(`Batch embedding ${inputs.length} texts with llama.cpp`);
+      
+      const texts = [];
+      for (const input of inputs) {
+        const text = await this.readInput(input);
+        if (text.trim()) {
+          texts.push(text);
+        }
+      }
+      
+      if (texts.length === 0) {
+        throw new Error('No valid texts to embed');
+      }
+
+      // For batch processing, use HTTP API
+      const modelPath = await this.getModelPath();
+      const requests = inputs.map(input => ({
+        input: input.text || '',
+        model: modelPath,
+        pooling: 'mean',
+        normalize: 2
+      }));
+
+      // Execute batch requests (for now, do individual requests)
+      const embeddings: number[][] = [];
+      for (const request of requests) {
+        const result = await this.executeLlamaEmbedding([JSON.stringify(request)]);
+        const embedding = this.parseRawOutput(result.stdout);
+        embeddings.push(embedding);
+      }
+      
+      return {
+        embeddings,
+        dimensions: embeddings[0]?.length || 0,
+        model: this.getModel(),
+        provider: 'llamacpp',
+      };
+    } catch (error: unknown) {
+      logger.error(`Llama.cpp batch embedding failed: ${(error instanceof Error ? error.message : String(error))}`);
+      throw error;
+    }
+  }
+
+  // Protected methods
+  protected getModel(): string {
+    return this.modelPath;
+  }
+
+  // Private helper methods
+  private async getModelPath(): Promise<string> {
+    // Try different model paths
+    const possiblePaths = [
+      this.modelPath, // As provided
+      join('./llama.cpp/models', this.modelPath), // In llama.cpp/models
+      join('./llama.cpp', this.modelPath), // In llama.cpp root
+      this.modelPath // Fallback
+    ];
+
+    for (const path of possiblePaths) {
+      try {
+        await access(path, constants.F_OK);
+        return resolve(path);
+      } catch {
+        continue;
+      }
+    }
+
+    throw new Error(`Model file not found: ${this.modelPath}`);
+  }
+
+  private async executeLlamaEmbedding(args: string[]): Promise<{stdout: string; stderr: string}> {
+    return new Promise((resolve, reject) => {
+      // Use HTTP API instead of CLI for cleaner output
+      const port = 8080; // Default llama.cpp server port
+      
+      // Parse the request body from args[0] (JSON string)
+      let requestBody;
+      try {
+        requestBody = JSON.parse(args[0] || '{}');
+      } catch {
+        reject(new Error('Invalid request body for HTTP API'));
+        return;
+      }
+
+      const postData = JSON.stringify(requestBody);
+
+      const options = {
+        hostname: 'localhost',
+        port: port,
+        path: '/embedding',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(postData)
+        }
+      };
+
+      const req = http.request(options, (res: http.IncomingMessage) => {
+        let data = '';
+        
+        res.on('data', (chunk: Buffer | string) => {
+          data += chunk;
+        });
+        
+        res.on('end', () => {
+          if (res.statusCode === 200) {
+            resolve({ stdout: data, stderr: '' });
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+          }
+        });
+      });
+
+      req.on('error', (error: Error) => {
+        reject(new Error(`Failed to connect to llama.cpp server: ${(error instanceof Error ? error.message : String(error))}`));
+      });
+
+      req.write(postData);
+      req.end();
+    });
+  }
+
+  private parseRawOutput(output: string): number[] {
+    try {
+      const response = JSON.parse(output);
+      
+      logger.debug(`PARSE DEBUG: Response type: ${typeof response}`);
+      logger.debug(`PARSE DEBUG: Is Array: ${Array.isArray(response)}`);
+      
+      // CASE 1: Array of objects with nested embedding
+      // Format: [{index: 0, embedding: [[...]]}]
+      if (Array.isArray(response) && response.length > 0) {
+        const first = response[0];
+        
+        if (first && first.embedding && Array.isArray(first.embedding)) {
+          const emb = first.embedding;
+          
+          // Check if nested: [[...]]
+          if (Array.isArray(emb[0])) {
+            const flat = emb[0]; // ← Take the inner array
+            logger.debug(`Parsed ${flat.length} dimensions (nested)`);
+            return flat;
+          }
+          
+          // Not nested: [...]
+          logger.debug(`Parsed ${emb.length} dimensions (direct)`);
+          return emb;
+        }
+      }
+      
+      // CASE 2: Direct object {embedding: [...]}
+      if (response.embedding && Array.isArray(response.embedding)) {
+        const emb = response.embedding;
+        
+        // Check nested
+        if (Array.isArray(emb[0])) {
+          return emb[0];
+        }
+        
+        return emb;
+      }
+      
+      // CASE 3: Direct array of numbers
+      if (Array.isArray(response) && typeof response[0] === 'number') {
+        logger.debug(`Parsed ${response.length} dimensions (flat array)`);
+        return response;
+      }
+      
+      throw new Error(`Unexpected format: ${JSON.stringify(Object.keys(response))}`);
+      
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? (error instanceof Error ? error.message : String(error)) : 'Unknown error';
+      throw new Error(`Parse failed: ${errorMessage}`, { cause: error });
+    }
+  }
+
+  private parseArrayOutput(output: string): number[][] {
+    // Parse array format: [[val1,val2,...], [val1,val2,...], ...]
+    const arrayPattern = /\[([^\]]+)\]/g;
+    const matches = [...output.matchAll(arrayPattern)];
+    
+    if (matches.length === 0) {
+      throw new Error('No array embeddings found in output');
+    }
+
+    const embeddings = matches.map(match => {
+      const values = match[1]?.split(',').map(v => v.trim()) || [];
+      return values.map(v => parseFloat(v)).filter(v => !isNaN(v));
+    }).filter(embedding => embedding.length > 0);
+
+    return embeddings;
+  }
+}

package/src/providers/mistral.ts

@@ -0,0 +1,113 @@
+import { Mistral } from '@mistralai/mistralai';
+import { EmbeddingProvider } from '@providers/base/EmbeddingProvider';
+import type { EmbedConfig, EmbedInput, EmbedResult, BatchEmbedResult } from '@src/types/index';
+import { Logger } from '@src/util/logger';
+
+const logger = Logger.createModuleLogger('mistral');
+
+export class MistralProvider extends EmbeddingProvider {
+  private client: Mistral;
+
+  constructor(config: EmbedConfig) {
+    super(config);
+    
+    if (!config.apiKey) {
+      throw new Error('Mistral API key is required');
+    }
+
+    this.client = new Mistral({
+      apiKey: config.apiKey,
+      serverURL: config.baseUrl,
+      timeoutMs: config.timeout || 30000,
+    });
+
+    logger.info('Mistral provider initialized');
+  }
+
+  async embed(input: EmbedInput): Promise<EmbedResult> {
+    try {
+      const text = await this.readInput(input);
+      logger.debug(`Embedding text with model: ${this.getModel()}`);
+
+      const response = await this.client.embeddings.create({
+        model: this.getModel(),
+        inputs: [text],
+      });
+
+      const embedding = response.data[0];
+      if (!embedding) {
+        throw new Error('No embedding returned from Mistral API');
+      }
+
+      return {
+        embedding: embedding.embedding || [],
+        dimensions: embedding.embedding?.length || 0,
+        model: response.model,
+        provider: 'mistral',
+        usage: response.usage?.promptTokens && response.usage?.totalTokens ? {
+          promptTokens: response.usage.promptTokens,
+          totalTokens: response.usage.totalTokens,
+        } : undefined,
+      };
+    } catch (error: unknown) {
+      logger.error(`Mistral embedding failed: ${(error instanceof Error ? error.message : String(error))}`);
+      throw error;
+    }
+  }
+
+  async embedBatch(inputs: EmbedInput[]): Promise<BatchEmbedResult> {
+    try {
+      const texts = await Promise.all(inputs.map(input => this.readInput(input)));
+      logger.debug(`Batch embedding ${texts.length} texts with model: ${this.getModel()}`);
+
+      const response = await this.client.embeddings.create({
+        model: this.getModel(),
+        inputs: texts,
+      });
+
+      const embeddings = response.data.map((item) => {
+        if (!item.embedding) throw new Error('No embedding returned from Mistral API');
+        return item.embedding as number[];
+      });
+
+      return {
+        embeddings,
+        dimensions: embeddings[0]?.length || 0,
+        model: response.model,
+        provider: 'mistral',
+        usage: response.usage?.promptTokens && response.usage?.totalTokens ? {
+          promptTokens: response.usage.promptTokens,
+          totalTokens: response.usage.totalTokens,
+        } : undefined,
+      };
+    } catch (error: unknown) {
+      logger.error(`Mistral batch embedding failed: ${(error instanceof Error ? error.message : String(error))}`);
+      throw error;
+    }
+  }
+
+  getDimensions(): number {
+    // Mistral embedding dimensions
+    const model = this.getModel();
+    if (model.includes('mistral-embed')) return 1024;
+    return 1024; // default for Mistral
+  }
+
+  getProviderName(): string {
+    return 'Mistral AI';
+  }
+
+  async isReady(): Promise<boolean> {
+    try {
+      // Test with a simple embedding request
+      const response = await this.client.embeddings.create({
+        model: this.getModel(),
+        inputs: ['test'],
+      });
+      return response.data.length > 0;
+    } catch (error: unknown) {
+      logger.error(`Mistral readiness check failed: ${(error instanceof Error ? error.message : String(error))}`);
+      return false;
+    }
+  }
+}

package/src/providers/openai.ts

@@ -0,0 +1,108 @@
+import OpenAI from 'openai';
+import { EmbeddingProvider } from '@providers/base/EmbeddingProvider';
+import type { EmbedConfig, EmbedInput, EmbedResult, BatchEmbedResult } from '@src/types/index';
+import { Logger } from '@src/util/logger';
+
+const logger = Logger.createModuleLogger('openai');
+
+export class OpenAIProvider extends EmbeddingProvider {
+  private client: OpenAI;
+
+  constructor(config: EmbedConfig) {
+    super(config);
+    
+    if (!config.apiKey) {
+      throw new Error('OpenAI API key is required');
+    }
+
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseUrl,
+      timeout: config.timeout || 30000,
+    });
+
+    logger.info('OpenAI provider initialized');
+  }
+
+  async embed(input: EmbedInput): Promise<EmbedResult> {
+    try {
+      const text = await this.readInput(input);
+      logger.debug(`Embedding text with model: ${this.getModel()}`);
+
+      const response = await this.client.embeddings.create({
+        model: this.getModel(),
+        input: text,
+      });
+
+      const embedding = response.data[0];
+      if (!embedding) {
+        throw new Error('No embedding returned from OpenAI API');
+      }
+
+      return {
+        embedding: embedding.embedding || [],
+        dimensions: embedding.embedding?.length || 0,
+        model: response.model,
+        provider: 'openai',
+        usage: response.usage ? {
+          promptTokens: response.usage.prompt_tokens,
+          totalTokens: response.usage.total_tokens,
+        } : undefined,
+      };
+    } catch (error: unknown) {
+      logger.error(`OpenAI embedding failed: ${(error instanceof Error ? error.message : String(error))}`);
+      throw error;
+    }
+  }
+
+  async embedBatch(inputs: EmbedInput[]): Promise<BatchEmbedResult> {
+    try {
+      const texts = await Promise.all(inputs.map(input => this.readInput(input)));
+      logger.debug(`Batch embedding ${texts.length} texts with model: ${this.getModel()}`);
+
+      const response = await this.client.embeddings.create({
+        model: this.getModel(),
+        input: texts,
+      });
+
+      const embeddings = response.data.map(item => item.embedding);
+
+      return {
+        embeddings,
+        dimensions: embeddings[0]?.length || 0,
+        model: response.model,
+        provider: 'openai',
+        usage: response.usage ? {
+          promptTokens: response.usage.prompt_tokens,
+          totalTokens: response.usage.total_tokens,
+        } : undefined,
+      };
+    } catch (error: unknown) {
+      logger.error(`OpenAI batch embedding failed: ${(error instanceof Error ? error.message : String(error))}`);
+      throw error;
+    }
+  }
+
+  getDimensions(): number {
+    // Common OpenAI embedding dimensions
+    const model = this.getModel();
+    if (model.includes('text-embedding-3-large')) return 3072;
+    if (model.includes('text-embedding-3-small')) return 1536;
+    if (model.includes('text-embedding-ada-002')) return 1536;
+    return 1536; // default
+  }
+
+  getProviderName(): string {
+    return 'OpenAI';
+  }
+
+  async isReady(): Promise<boolean> {
+    try {
+      await this.client.models.list();
+      return true;
+    } catch (error: unknown) {
+      logger.error(`OpenAI readiness check failed: ${(error instanceof Error ? error.message : String(error))}`);
+      return false;
+    }
+  }
+}

package/src/types/deepseek.d.ts

@@ -0,0 +1,15 @@
+declare module 'deepseek' {
+  export class DeepSeek {
+    constructor(options: { apiKey: string; baseURL?: string; timeout?: number });
+    embeddings: {
+      create: (options: { model: string; input: string | string[] }) => Promise<{
+        data: Array<{ embedding: number[]; model: string }>;
+        model: string;
+        usage?: {
+          prompt_tokens: number;
+          total_tokens: number;
+        };
+      }>;
+    };
+  }
+}

package/src/types/index.d.ts

@@ -0,0 +1,43 @@
+export type ProviderType = 
+  | 'openai'
+  | 'gemini' 
+  | 'claude'
+  | 'mistral'
+  | 'deepseek'
+  | 'llamacpp';
+
+export interface EmbedConfig {
+  provider: ProviderType;
+  model?: string;
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+export interface EmbedInput {
+  text?: string;
+  filePath?: string;
+}
+
+export interface EmbedResult {
+  embedding: number[];
+  dimensions: number;
+  model: string;
+  provider: string;
+  usage?: {
+    promptTokens?: number;
+    totalTokens?: number;
+  } | undefined;
+}
+
+export interface BatchEmbedResult {
+  embeddings: number[][];
+  dimensions: number;
+  model: string;
+  provider: string;
+  usage?: {
+    promptTokens?: number;
+    totalTokens?: number;
+  } | undefined;
+}

package/src/types/index.ts

@@ -0,0 +1,43 @@
+export type ProviderType = 
+  | 'openai'
+  | 'gemini' 
+  | 'claude'
+  | 'mistral'
+  | 'deepseek'
+  | 'llamacpp';
+
+export interface EmbedConfig {
+  provider: ProviderType;
+  model?: string;
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+export interface EmbedInput {
+  text?: string;
+  filePath?: string;
+}
+
+export interface EmbedResult {
+  embedding: number[];
+  dimensions: number;
+  model: string;
+  provider: string;
+  usage?: {
+    promptTokens?: number;
+    totalTokens?: number;
+  } | undefined;
+}
+
+export interface BatchEmbedResult {
+  embeddings: number[][];
+  dimensions: number;
+  model: string;
+  provider: string;
+  usage?: {
+    promptTokens?: number;
+    totalTokens?: number;
+  } | undefined;
+}

package/src/types/package.json

@@ -0,0 +1 @@
+{"name": "@types", "version": "1.0.0", "type": "module", "main": "index.js", "types": "index.d.ts"}

package/src/types/transformers.d.ts

@@ -0,0 +1,7 @@
+declare module '@xenova/transformers' {
+  export function pipeline(task: string, model: string): Promise<unknown>;
+  export const env: {
+    cacheDir: string;
+    allowLocalModels: boolean;
+  };
+}