lance-context 0.1.0 → 1.1.0

package/dist/embeddings/retry.js

@@ -0,0 +1,89 @@
+/**
+ * Default maximum response size (10MB)
+ */
+const DEFAULT_MAX_RESPONSE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_OPTIONS = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+    maxResponseSizeBytes: DEFAULT_MAX_RESPONSE_SIZE,
+};
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check if response size exceeds the maximum allowed
+ */
+function checkResponseSize(response, maxSize) {
+    const contentLength = response.headers?.get?.('content-length');
+    if (contentLength) {
+        const size = parseInt(contentLength, 10);
+        if (!isNaN(size) && size > maxSize) {
+            throw new Error(`Response size ${size} bytes exceeds maximum allowed ${maxSize} bytes`);
+        }
+    }
+}
+/**
+ * Check if an error is retryable (network errors, rate limits, server errors)
+ */
+function isRetryableError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        // Retry on network errors
+        if (message.includes('fetch') ||
+            message.includes('network') ||
+            message.includes('econnrefused')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a response status is retryable
+ */
+function isRetryableStatus(status) {
+    // Retry on rate limits (429), server errors (5xx), and some specific cases
+    return status === 429 || status === 408 || (status >= 500 && status < 600);
+}
+/**
+ * Execute a fetch request with exponential backoff retry
+ */
+export async function fetchWithRetry(url, options, retryOptions) {
+    const opts = { ...DEFAULT_OPTIONS, ...retryOptions };
+    let lastError = null;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+        try {
+            const response = await fetch(url, options);
+            // Check response size before processing
+            checkResponseSize(response, opts.maxResponseSizeBytes);
+            // If response is ok or non-retryable error, return it
+            if (response.ok || !isRetryableStatus(response.status)) {
+                return response;
+            }
+            // Retryable status code
+            if (attempt < opts.maxRetries) {
+                const delay = Math.min(opts.baseDelayMs * Math.pow(2, attempt), opts.maxDelayMs);
+                console.error(`[lance-context] Request failed with status ${response.status}, retrying in ${delay}ms (attempt ${attempt + 1}/${opts.maxRetries})`);
+                await sleep(delay);
+                continue;
+            }
+            // Last attempt, return the response even if it's an error
+            return response;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < opts.maxRetries && isRetryableError(error)) {
+                const delay = Math.min(opts.baseDelayMs * Math.pow(2, attempt), opts.maxDelayMs);
+                console.error(`[lance-context] Request failed: ${lastError.message}, retrying in ${delay}ms (attempt ${attempt + 1}/${opts.maxRetries})`);
+                await sleep(delay);
+                continue;
+            }
+            throw lastError;
+        }
+    }
+    throw lastError || new Error('Request failed after retries');
+}
+//# sourceMappingURL=retry.js.map

package/dist/embeddings/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/embeddings/retry.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/types.d.ts

@@ -1,18 +1,72 @@
 /**
- * Embedding backend interface
+ * Embedding backend interface that all embedding providers must implement.
+ * Supports both single text and batch embedding operations.
  */
 export interface EmbeddingBackend {
+    /** Display name of the embedding backend (e.g., 'jina', 'ollama') */
     name: string;
+    /**
+     * Initialize the backend, validating credentials and connectivity.
+     * @throws Error if initialization fails (e.g., invalid API key, server unreachable)
+     */
     initialize(): Promise<void>;
+    /**
+     * Generate an embedding vector for a single text.
+     * @param text - The text to embed
+     * @returns A promise resolving to the embedding vector (array of numbers)
+     */
     embed(text: string): Promise<number[]>;
+    /**
+     * Generate embedding vectors for multiple texts in a single batch.
+     * More efficient than calling embed() multiple times.
+     * @param texts - Array of texts to embed
+     * @returns A promise resolving to an array of embedding vectors
+     */
     embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Get the dimensionality of the embedding vectors produced by this backend.
+     * @returns The number of dimensions in the embedding vectors
+     */
     getDimensions(): number;
+    /**
+     * Get the model identifier used by this backend.
+     * @returns The model name/identifier (e.g., 'nomic-embed-text', 'jina-embeddings-v3')
+     */
+    getModel(): string;
 }
+/**
+ * Configuration options for embedding backends.
+ */
 export interface EmbeddingConfig {
-    backend: 'jina' | 'local' | 'ollama';
+    /** Which embedding backend to use */
+    backend: 'jina' | 'ollama' | 'local';
+    /** Model name/identifier (backend-specific) */
     model?: string;
+    /** API key for cloud-based backends (Jina) */
     apiKey?: string;
+    /** Base URL for the embedding API (useful for Ollama or custom endpoints) */
     baseUrl?: string;
+    /** Rate limiting: maximum requests per second (default: 5 for Jina) */
+    rateLimitRps?: number;
+    /** Rate limiting: maximum burst capacity (default: 10) */
+    rateLimitBurst?: number;
+    /**
+     * Maximum number of texts to process in a single batch request.
+     * Large batches are automatically split into smaller chunks to prevent
+     * timeouts, memory issues, and API rate limit errors.
+     * Default: 100 for Jina, 10 for Ollama (parallel requests)
+     */
+    batchSize?: number;
 }
+/**
+ * Split an array into chunks of specified size.
+ * @param array - The array to chunk
+ * @param size - Maximum size of each chunk
+ * @returns Array of chunks
+ */
+export declare function chunkArray<T>(array: T[], size: number): T[][];
+/**
+ * Default embedding configuration using local Ollama with nomic-embed-text model.
+ */
 export declare const DEFAULT_CONFIG: EmbeddingConfig;
 //# sourceMappingURL=types.d.ts.map

package/dist/embeddings/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjD,aAAa,IAAI,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,cAAc,EAAE,eAI5B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEjD;;;OAGG;IACH,aAAa,IAAI,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,IAAI,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAErC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAM7D;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,eAI5B,CAAC"}

package/dist/embeddings/types.js

@@ -1,3 +1,19 @@
+/**
+ * Split an array into chunks of specified size.
+ * @param array - The array to chunk
+ * @param size - Maximum size of each chunk
+ * @returns Array of chunks
+ */
+export function chunkArray(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+/**
+ * Default embedding configuration using local Ollama with nomic-embed-text model.
+ */
 export const DEFAULT_CONFIG = {
     backend: 'ollama',
     model: 'nomic-embed-text',

package/dist/embeddings/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC7C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,kBAAkB;IACzB,OAAO,EAAE,wBAAwB;CAClC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"AAyEA;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAI,KAAU,EAAE,IAAY;IACpD,MAAM,MAAM,GAAU,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC7C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,kBAAkB;IACzB,OAAO,EAAE,wBAAwB;CAClC,CAAC"}