@massa-ai/core 1.2.1

package/dist/services/embeddings/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Embedding Provider Factory with Auto-Fallback
+ *
+ * Main entry point for creating embedding providers with:
+ * - Automatic provider selection based on availability
+ * - Fallback chain: Mistral Text → Mistral Code
+ * - Optional transparent caching
+ * - Health checking before usage
+ *
+ * Usage:
+ * ```typescript
+ * // Auto-select first available provider with cache
+ * const provider = await createEmbeddingProvider({ cache: true });
+ *
+ * // Specific provider with cache
+ * const provider = await createEmbeddingProvider({
+ *   provider: 'mistralText',
+ *   cache: true
+ * });
+ *
+ * // Use provider
+ * const embedding = await provider.embedQuery("Hello world");
+ * const embeddings = await provider.embedBatch(["Hello", "World"]);
+ * ```
+ */
+import { EmbeddingProvider } from "./provider.js";
+import type { EmbeddingCacheStore } from "../cache/embedding-cache-contract.js";
+/**
+ * Options for creating an embedding provider
+ */
+export interface CreateProviderOptions {
+    /**
+     * Provider to use:
+     * - 'auto': Try providers by priority until one works (Ollama first)
+     * - 'ollama': Ollama local embeddings (768D, free, local-first)
+     * - 'transformers' / 'local': In-process transformers.js ONNX embeddings
+     *   (384D, fully offline after first model download — roadmap A5)
+     * - 'mistralText': Mistral text embeddings (1024D)
+     * - 'mistralCode': Mistral code embeddings (1536D)
+     *
+     * Default: 'auto'
+     */
+    provider?: "auto" | "ollama" | "transformers" | "local" | "mistralText" | "mistralCode";
+    /**
+     * Enable transparent caching using SHA-256 content hashing
+     *
+     * Benefits:
+     * - 0.09ms cache hit latency
+     * - Reduce API calls by 60-80%
+     * - Automatic cleanup of old entries
+     *
+     * Default: true
+     */
+    cache?: boolean;
+    /**
+     * Custom cache instance (optional)
+     * If not provided, a new cache will be created with default settings
+     */
+    cacheInstance?: EmbeddingCacheStore;
+    /**
+     * Skip health check before returning provider
+     * Useful for testing or when you know provider is available
+     *
+     * Default: false
+     */
+    skipHealthCheck?: boolean;
+}
+/**
+ * Create embedding provider with auto-fallback
+ *
+ * Auto mode:
+ * Tries providers in priority order until one succeeds:
+ * 1. Mistral Text (general purpose embeddings)
+ * 2. Mistral Code (code-specialized embeddings)
+ *
+ * Specific provider mode:
+ * Creates the requested provider or throws if unavailable
+ */
+export declare function createEmbeddingProvider(options?: CreateProviderOptions): Promise<EmbeddingProvider>;
+/**
+ * Create all available providers (for testing/comparison)
+ *
+ * Returns an array of all providers that pass health checks.
+ * Useful for benchmarking or testing multiple providers.
+ */
+export declare function createAllProviders(options?: {
+    cache?: boolean;
+    skipHealthCheck?: boolean;
+}): Promise<EmbeddingProvider[]>;
+/**
+ * Check which providers are available
+ *
+ * Returns a map of provider IDs to availability status.
+ * Useful for diagnostics and configuration validation.
+ */
+export declare function checkProviderAvailability(): Promise<Record<string, {
+    available: boolean;
+    reason?: string;
+}>>;
+export type { EmbeddingProvider } from "./provider.js";
+export type { CachedEmbeddingProvider } from "./cached-provider.js";
+export type { EmbeddingProviderConfig } from "./config.js";
+export { embeddingProviders, getProvidersByPriority, hasApiKey, } from "./config.js";
+export { EmbeddingService } from "./embedding-service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/embeddings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/embeddings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,iBAAiB,EAAkB,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAUhF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,cAAc,GAAG,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC;IAExF;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAEpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmCD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAuE5B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAmB9B;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CACxD,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CACxD,CAgCA;AAGD,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,SAAS,GACV,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/services/embeddings/index.js

@@ -0,0 +1,174 @@
+/**
+ * Embedding Provider Factory with Auto-Fallback
+ *
+ * Main entry point for creating embedding providers with:
+ * - Automatic provider selection based on availability
+ * - Fallback chain: Mistral Text → Mistral Code
+ * - Optional transparent caching
+ * - Health checking before usage
+ *
+ * Usage:
+ * ```typescript
+ * // Auto-select first available provider with cache
+ * const provider = await createEmbeddingProvider({ cache: true });
+ *
+ * // Specific provider with cache
+ * const provider = await createEmbeddingProvider({
+ *   provider: 'mistralText',
+ *   cache: true
+ * });
+ *
+ * // Use provider
+ * const embedding = await provider.embedQuery("Hello world");
+ * const embeddings = await provider.embedBatch(["Hello", "World"]);
+ * ```
+ */
+import { createProvider } from "./provider.js";
+import { withCache } from "./cached-provider.js";
+import { createEmbeddingCache } from "../cache/embedding-cache-factory.js";
+import { embeddingProviders, getProvidersByPriority, hasApiKey, } from "./config.js";
+import { logger } from "@massa-ai/shared";
+/**
+ * Try to create a provider from configuration
+ * Returns null if provider is not available or configured
+ */
+async function tryCreateProvider(config, providerId, skipHealthCheck) {
+    // Check if API key is available (if needed)
+    if (!hasApiKey(providerId)) {
+        logger.debug(`[${providerId}] Skipping: No API key configured`);
+        return null;
+    }
+    // Create provider
+    const provider = createProvider(config, providerId);
+    // Health check
+    if (!skipHealthCheck) {
+        const available = await provider.isAvailable();
+        if (!available) {
+            logger.debug(`[${providerId}] Health check failed`);
+            return null;
+        }
+    }
+    logger.info(`[${providerId}] Provider ready (model: ${config.model}, dimensions: ${config.dimensions})`);
+    return provider;
+}
+/**
+ * Create embedding provider with auto-fallback
+ *
+ * Auto mode:
+ * Tries providers in priority order until one succeeds:
+ * 1. Mistral Text (general purpose embeddings)
+ * 2. Mistral Code (code-specialized embeddings)
+ *
+ * Specific provider mode:
+ * Creates the requested provider or throws if unavailable
+ */
+export async function createEmbeddingProvider(options = {}) {
+    const { provider: requestedProvider = "auto", cache: enableCache = true, cacheInstance, skipHealthCheck = false, } = options;
+    let baseProvider = null;
+    // Auto mode: try providers by priority
+    if (requestedProvider === "auto") {
+        logger.info("Auto-selecting embedding provider...");
+        const providers = getProvidersByPriority();
+        for (const [id, config] of providers) {
+            logger.debug(`Trying provider: ${id} (priority: ${config.priority})`);
+            baseProvider = await tryCreateProvider(config, id, skipHealthCheck);
+            if (baseProvider) {
+                logger.info(`Selected provider: ${id}`);
+                break;
+            }
+        }
+        if (!baseProvider) {
+            throw new Error("No embedding providers available. For local-first setup:\n" +
+                "1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh\n" +
+                "2. Start Ollama: ollama serve\n" +
+                "3. Pull model: ollama pull nomic-embed-text:latest\n" +
+                "\n" +
+                "Or configure a remote provider:\n" +
+                "- MISTRAL_API_KEY (Mistral AI text and code embeddings)");
+        }
+    }
+    // Specific provider mode
+    else {
+        const config = embeddingProviders[requestedProvider];
+        if (!config) {
+            throw new Error(`Unknown provider: ${requestedProvider}`);
+        }
+        baseProvider = await tryCreateProvider(config, requestedProvider, skipHealthCheck);
+        if (!baseProvider) {
+            throw new Error(`Provider '${requestedProvider}' is not available. ` +
+                `Please check configuration and ensure ${config.provider.toUpperCase()}_API_KEY is set.`);
+        }
+    }
+    // Wrap with cache if requested
+    if (enableCache) {
+        const cache = cacheInstance || createEmbeddingCache(baseProvider.id, baseProvider.model);
+        const cachedProvider = withCache(baseProvider, cache);
+        logger.info(`Cache enabled for ${baseProvider.id}`);
+        return cachedProvider;
+    }
+    return baseProvider;
+}
+/**
+ * Create all available providers (for testing/comparison)
+ *
+ * Returns an array of all providers that pass health checks.
+ * Useful for benchmarking or testing multiple providers.
+ */
+export async function createAllProviders(options = {}) {
+    const { cache: enableCache = false, skipHealthCheck = false } = options;
+    const providers = getProvidersByPriority();
+    const results = [];
+    for (const [id, config] of providers) {
+        const provider = await tryCreateProvider(config, id, skipHealthCheck);
+        if (provider) {
+            if (enableCache) {
+                const cache = createEmbeddingCache(provider.id, provider.model);
+                results.push(withCache(provider, cache));
+            }
+            else {
+                results.push(provider);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Check which providers are available
+ *
+ * Returns a map of provider IDs to availability status.
+ * Useful for diagnostics and configuration validation.
+ */
+export async function checkProviderAvailability() {
+    const providers = getProvidersByPriority();
+    const results = {};
+    for (const [id, config] of providers) {
+        // Check API key
+        if (!hasApiKey(id)) {
+            results[id] = {
+                available: false,
+                reason: "No API key configured",
+            };
+            continue;
+        }
+        // Check health
+        try {
+            const provider = createProvider(config, id);
+            const available = await provider.isAvailable();
+            results[id] = {
+                available,
+                reason: available ? undefined : "Health check failed",
+            };
+        }
+        catch (error) {
+            results[id] = {
+                available: false,
+                reason: error.message,
+            };
+        }
+    }
+    return results;
+}
+export { embeddingProviders, getProvidersByPriority, hasApiKey, } from "./config.js";
+// Phase 7f: relocated EmbeddingService (was data/chromadb/vector-store.ts).
+export { EmbeddingService } from "./embedding-service.js";
+//# sourceMappingURL=index.js.map

package/dist/services/embeddings/index.js.map

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

package/dist/services/embeddings/provider.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Multi-Provider Embedding Service using Vercel AI SDK
+ *
+ * Provides a unified interface for embedding generation across multiple providers
+ * (OpenAI, Google, Cohere, Ollama) with automatic retry and timeout handling.
+ *
+ * Inspired by OpenClaw's provider system with improvements:
+ * - Uses Vercel AI SDK for provider abstraction
+ * - Exponential backoff retry (500ms base, 8s max)
+ * - Configurable timeouts (60s remote, 5min local)
+ * - Health checks before usage
+ * - Batch operations with token limits
+ */
+import type { EmbeddingProviderConfig } from "./config.js";
+/**
+ * Base interface for embedding providers
+ */
+export interface EmbeddingProvider {
+    /** Unique provider identifier */
+    id: string;
+    /** Model identifier */
+    model: string;
+    /** Embedding dimensions */
+    dimensions: number;
+    /** Embed a single text query */
+    embedQuery(text: string): Promise<number[]>;
+    /** Embed multiple texts in batch */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /** Check if provider is available and configured */
+    isAvailable(): Promise<boolean>;
+    /** Get provider configuration */
+    getConfig(): EmbeddingProviderConfig;
+}
+/**
+ * AI SDK-based embedding provider implementation
+ *
+ * Supports OpenAI, Google, Cohere, and Ollama via Vercel AI SDK
+ * with automatic retry, timeout, and health checking.
+ */
+export declare class AISDKEmbeddingProvider implements EmbeddingProvider {
+    private readonly config;
+    private readonly providerId;
+    readonly id: string;
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly providerType;
+    private readonly apiKey?;
+    private readonly baseURL?;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly rateLimiter?;
+    private static ollamaMutex;
+    private static readonly OLLAMA_DELAY_MS;
+    constructor(config: EmbeddingProviderConfig, providerId: string);
+    private getEmbeddingModel;
+    /**
+     * Get provider options (API key, base URL)
+     */
+    private getProviderOptions;
+    /**
+     * Truncate text to fit model context length.
+     *
+     * Limit is resolved per-provider from config.maxChars (see embeddings/config.ts
+     * getMaxChars). Falls back to 4000 chars (bge-m3 safe default) when not set.
+     */
+    private truncateText;
+    /**
+     * Sanitize text to prevent NaN errors in embedding models
+     *
+     * Removes:
+     * - Control characters (U+0000 to U+001F, U+007F)
+     * - Replacement character U+FFFD (indicates broken UTF-8)
+     * - ONLY unpaired surrogate halves (invalid UTF-16)
+     * - Zero-width and non-printable characters
+     *
+     * Preserves valid Unicode (emojis, accented chars, CJK, etc.)
+     */
+    private sanitizeText;
+    /**
+     * Queue Ollama requests to prevent overwhelming the server
+     */
+    private queueOllamaRequest;
+    /**
+     * POST to an Ollama endpoint with an AbortController tied to the provider
+     * timeout.
+     *
+     * Why: when the Ollama runner wedges (model stuck mid-inference), it accepts
+     * the TCP connection but never responds. A bare `fetch` with no signal stays
+     * pending indefinitely, so `queueOllamaRequest`'s `try/finally` never reaches
+     * `finally` and the serialization mutex is held forever — every subsequent
+     * embed queues behind it and the whole index job hangs (only the stale-job
+     * reaper recovers it, minutes later). The outer `withTimeout` rejects its own
+     * race promise at the deadline but cannot cancel the dangling fetch.
+     *
+     * Arming an AbortController here guarantees the fetch settles (rejects with
+     * AbortError) at the deadline: the mutex releases, `withRetry` can retry or
+     * surface the error, and the job fails fast instead of hanging.
+     */
+    private ollamaFetch;
+    /**
+     * Embed a single text query
+     */
+    embedQuery(text: string): Promise<number[]>;
+    /**
+     * Embed multiple texts in batch with intelligent rate limiting
+     *
+     * Features:
+     * - Rate limiting for RPM/TPM/RPD
+     * - Sub-batching to respect provider limits
+     * - Sequential processing with delays between batches
+     * - Progress logging for large batches
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Direct batch embedding without rate limiting (used internally)
+     */
+    private embedBatchDirect;
+    /**
+     * Check if provider is available and configured correctly
+     *
+     * For Ollama: performs a fast 2s connectivity check first to avoid
+     * long timeouts when the service is offline (issue #15).
+     *
+     * Then validates with a test embedding:
+     * - API key is valid
+     * - Model is accessible
+     * - Network connectivity
+     * - Service is responding
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get provider configuration
+     */
+    getConfig(): EmbeddingProviderConfig;
+    /**
+     * Get rate limiter status (if configured)
+     */
+    getRateLimitStatus(): {
+        rpm: {
+            current: number;
+            limit: number;
+            percentage: number;
+        };
+        tpm: {
+            current: number;
+            limit: number;
+            percentage: number;
+        };
+        rpd: {
+            current: number;
+            limit: number;
+            percentage: number;
+        };
+    } | null;
+}
+/**
+ * Factory function to create embedding providers from configuration.
+ *
+ * Dispatches to the local transformers.js provider for `provider: "transformers"`
+ * (roadmap A5); every other provider type uses the Vercel-AI-SDK-backed
+ * AISDKEmbeddingProvider.
+ */
+export declare function createProvider(config: EmbeddingProviderConfig, providerId: string): EmbeddingProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/services/embeddings/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/services/embeddings/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAM3D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IAEX,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IAEnB,gCAAgC;IAChC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5C,oCAAoC;IACpC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEjD,oDAAoD;IACpD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC,iCAAiC;IACjC,SAAS,IAAI,uBAAuB,CAAC;CACtC;AAgFD;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAyB5D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAzB7B,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAQf;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAuB;IAGpD,OAAO,CAAC,MAAM,CAAC,WAAW,CAAoC;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAoD;gBAGxE,MAAM,EAAE,uBAAuB,EAC/B,UAAU,EAAE,MAAM;IA2BrC,OAAO,CAAC,iBAAiB;IA4DzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAgBpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IAqBpB;;OAEG;YACW,kBAAkB;IAgBhC;;;;;;;;;;;;;;;OAeG;YACW,WAAW;IAkBzB;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0FjD;;;;;;;;OAQG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAyDtD;;OAEG;YACW,gBAAgB;IAyG9B;;;;;;;;;;;OAWG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA0DrC;;OAEG;IACH,SAAS,IAAI,uBAAuB;IAIpC;;OAEG;IACH,kBAAkB;;;;;;;;;;;;;;;;;CAMnB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,uBAAuB,EAC/B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAQnB"}