mem-os-python 1.6.27__py3-none-any.whl

memos/_js/embedding-queue.js

@@ -0,0 +1,316 @@
+/**
+ * EmbeddingQueue — bounded, retryable, event-emitting background worker
+ * pool for embedding generation.
+ *
+ * Why this exists: the previous MemOS engine called `provider.embed()` inline
+ * from `store()` and `update()`. For local-hash that costs nothing, but the
+ * moment a user points MemOS at Ollama, LM Studio, or any OpenAI-compatible
+ * endpoint, every write blocks for the full round-trip. This queue lets
+ * `store()` return as soon as the node is persisted, with the embedding work
+ * happening in the background under a bounded concurrency cap.
+ *
+ * Design:
+ *   - One shared queue per MemOS instance.
+ *   - `enqueue()` is fire-and-forget — returns a job id immediately.
+ *   - Workers are pulled in FIFO order. Concurrency is bounded by
+ *     `EmbeddingQueueConfig.concurrency` (default 2).
+ *   - When `batchSize` > 1 and the provider implements `batchEmbed`,
+ *     a worker drains up to `batchSize` pending jobs into one batched
+ *     call; a failed batch falls back to per-job retries.
+ *   - Failures are retried with exponential backoff up to `maxRetries`
+ *     (default 3) before the job is marked `failed` and an
+ *     `embedding:failed` event fires.
+ *   - Backpressure: if `maxQueueSize` is exceeded, `enqueue()` throws
+ *     instead of growing memory unbounded. Callers can `await flush()`
+ *     to make room.
+ *   - Lifecycle events: `embedding:queued`, `embedding:started`,
+ *     `embedding:complete`, `embedding:failed`, `embedding:retry`.
+ *
+ * The queue does not know about storage. It only knows how to call the
+ * `EmbeddingProvider`. Persistence of the resulting vector is the
+ * responsibility of the caller (a `persist` callback) so this module
+ * stays storage-agnostic and easy to test.
+ *
+ * @module @memos/embedding-queue
+ */
+const DEFAULT_CONCURRENCY = 2;
+const DEFAULT_BATCH_SIZE = 1;
+const DEFAULT_MAX_QUEUE_SIZE = 10_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_BACKOFF_MS = 250;
+const DEFAULT_BATCH_LINGER_MS = 5;
+/** Generate a short, unique job id without pulling in a uuid dep. */
+function generateJobId() {
+    return `emb-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Bounded, retryable, non-blocking embedding queue.
+ *
+ * @example
+ * ```ts
+ * const queue = new EmbeddingQueue({
+ *   provider,
+ *   concurrency: 4,
+ *   onPersist: async (nodeId, vector, model) => {
+ *     await storage.saveEmbedding(nodeId, vector, model);
+ *   },
+ * });
+ *
+ * const jobId = queue.enqueue(node.id, text);
+ * await queue.flush();
+ * await queue.close();
+ * ```
+ */
+export class EmbeddingQueue {
+    provider;
+    concurrency;
+    batchSize;
+    maxQueueSize;
+    maxRetries;
+    retryBackoffMs;
+    batchLingerMs;
+    onPersist;
+    onStatusChange;
+    /** Pending jobs not yet picked up by a worker. */
+    pending = [];
+    /** Currently running job groups, by worker slot index. */
+    running;
+    /** Job index by id, for status queries. */
+    jobs = new Map();
+    /** Resolvers for `flush()` callers, resolved when the queue drains. */
+    drainWaiters = [];
+    /** Set true after `close()` so enqueue can reject and workers exit. */
+    closed = false;
+    /** Guards one-at-a-time deferred group pickup (see schedule()). */
+    scheduleQueued = false;
+    constructor(config) {
+        this.provider = config.provider;
+        this.concurrency = Math.max(1, config.concurrency ?? DEFAULT_CONCURRENCY);
+        this.batchSize = Math.max(1, config.batchSize ?? DEFAULT_BATCH_SIZE);
+        this.maxQueueSize = Math.max(1, config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE);
+        this.maxRetries = Math.max(0, config.maxRetries ?? DEFAULT_MAX_RETRIES);
+        this.retryBackoffMs = Math.max(0, config.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS);
+        this.batchLingerMs = Math.max(0, config.batchLingerMs ?? DEFAULT_BATCH_LINGER_MS);
+        this.onPersist = config.onPersist;
+        this.onStatusChange = config.onStatusChange;
+        this.running = new Array(this.concurrency).fill(null);
+    }
+    /**
+     * Enqueue an embedding job. Returns a job id immediately.
+     *
+     * @throws if the queue is full or has been closed.
+     */
+    enqueue(nodeId, text) {
+        if (this.closed) {
+            throw new Error("EmbeddingQueue is closed.");
+        }
+        if (this.pending.length + this.activeCount() >= this.maxQueueSize) {
+            throw new Error(`EmbeddingQueue is full (${this.maxQueueSize} jobs). ` +
+                `Call await queue.flush() to make room.`);
+        }
+        const job = {
+            id: generateJobId(),
+            nodeId,
+            text,
+            status: "queued",
+            attempts: 0,
+            lastError: null,
+            enqueuedAt: Date.now(),
+            updatedAt: Date.now(),
+            vector: null,
+            model: null,
+        };
+        this.pending.push(job);
+        this.jobs.set(job.id, job);
+        this.notifyStatus(job, "queued", null);
+        this.schedule();
+        return job.id;
+    }
+    /** Number of jobs currently waiting or running. */
+    size() {
+        return this.pending.length + this.activeCount();
+    }
+    /** Number of jobs currently being processed. */
+    activeCount() {
+        let n = 0;
+        for (const group of this.running) {
+            if (group)
+                n += group.length;
+        }
+        return n;
+    }
+    /** Return a snapshot of a job by id, or null if unknown. */
+    getJob(id) {
+        const j = this.jobs.get(id);
+        return j ? { ...j } : null;
+    }
+    /** Return all jobs that are not in a terminal state. */
+    pendingJobs() {
+        const out = [];
+        for (const j of this.jobs.values()) {
+            if (j.status === "queued" ||
+                j.status === "running" ||
+                j.status === "retrying") {
+                out.push({ ...j });
+            }
+        }
+        return out;
+    }
+    /**
+     * Wait for the queue to drain. Resolves when both `pending` and
+     * `running` are empty. If the queue is already drained, resolves on
+     * the next microtask.
+     */
+    async flush() {
+        if (this.size() === 0)
+            return;
+        await new Promise((resolve) => this.drainWaiters.push(resolve));
+    }
+    /**
+     * Permanently stop the queue. In-flight jobs are allowed to finish
+     * (and their persist callbacks run) but no new work is accepted.
+     */
+    async close() {
+        this.closed = true;
+        await this.flush();
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    notifyStatus(job, status, error) {
+        job.status = status;
+        job.updatedAt = Date.now();
+        job.lastError = error;
+        if (this.onStatusChange) {
+            try {
+                const result = this.onStatusChange(job.nodeId, status, error);
+                if (result && typeof result.then === "function") {
+                    // Best-effort: do not await persistence callbacks in status notify.
+                    result.catch(() => undefined);
+                }
+            }
+            catch {
+                // Status-callback errors are non-fatal.
+            }
+        }
+    }
+    /**
+     * Pull pending jobs into idle worker slots. The actual pickup is
+     * deferred by one microtask so a synchronous enqueue burst (e.g. an
+     * ingestion loop storing N memories back-to-back) coalesces into
+     * full `batchSize` groups instead of starting a half-empty group per
+     * enqueue.
+     */
+    schedule() {
+        if (this.scheduleQueued)
+            return;
+        this.scheduleQueued = true;
+        // Coalescing linger: when the queue is fully idle, wait `batchLingerMs`
+        // before picking up work so rapid sequential enqueues (e.g. `await
+        // store()` in a loop) form full `batchSize` groups instead of one
+        // single-job group each. While workers are already busy, pending jobs
+        // accumulate on their own — pick those up immediately with no added
+        // latency. A linger of 0 restores the immediate microtask pickup.
+        const lingerIdle = this.batchLingerMs > 0 && this.activeCount() === 0;
+        if (!lingerIdle) {
+            queueMicrotask(() => {
+                this.scheduleQueued = false;
+                this.scheduleNow();
+            });
+        }
+        else {
+            setTimeout(() => {
+                this.scheduleQueued = false;
+                this.scheduleNow();
+            }, this.batchLingerMs);
+        }
+    }
+    scheduleNow() {
+        for (let i = 0; i < this.running.length; i += 1) {
+            if (this.running[i] !== null)
+                continue;
+            if (this.pending.length === 0)
+                break;
+            const group = this.pending.splice(0, this.batchSize);
+            this.running[i] = group;
+            // Fire-and-forget worker loop.
+            void this.runGroup(i, group);
+        }
+    }
+    async runGroup(slot, group) {
+        const canBatch = group.length > 1 && typeof this.provider.batchEmbed === "function";
+        if (!canBatch) {
+            for (const job of group) {
+                await this.runJobWithRetries(job);
+            }
+        }
+        else {
+            for (const job of group) {
+                this.notifyStatus(job, "running", null);
+            }
+            try {
+                const vectors = await this.provider.batchEmbed(group.map((job) => job.text));
+                for (const [index, job] of group.entries()) {
+                    job.attempts = 1;
+                    job.vector = vectors[index] ?? null;
+                    job.model = this.provider.model;
+                    if (this.onPersist) {
+                        await this.onPersist(job.nodeId, job.vector, this.provider.model);
+                    }
+                    this.notifyStatus(job, "complete", null);
+                }
+            }
+            catch {
+                // The batch as a whole failed — fall back to the per-job retry
+                // path so one poisoned text cannot silently fail its whole group.
+                for (const job of group) {
+                    job.attempts = 0;
+                    await this.runJobWithRetries(job);
+                }
+            }
+        }
+        this.running[slot] = null;
+        this.afterJob();
+    }
+    async runJobWithRetries(job) {
+        this.notifyStatus(job, "running", null);
+        let attempt = 0;
+        let lastError = null;
+        while (attempt <= this.maxRetries) {
+            attempt += 1;
+            job.attempts = attempt;
+            try {
+                const vector = await this.provider.embed(job.text);
+                job.vector = vector;
+                job.model = this.provider.model;
+                if (this.onPersist) {
+                    await this.onPersist(job.nodeId, vector, this.provider.model);
+                }
+                this.notifyStatus(job, "complete", null);
+                return;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt > this.maxRetries)
+                    break;
+                const delay = this.retryBackoffMs * Math.pow(2, attempt - 1);
+                this.notifyStatus(job, "retrying", lastError.message);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                // Mark the next attempt as running so observers see the transition.
+                this.notifyStatus(job, "running", null);
+            }
+        }
+        this.notifyStatus(job, "failed", lastError ? lastError.message : "unknown error");
+    }
+    /** After a worker slot frees, schedule the next pending job and
+     *  resolve any flush() waiters that are now satisfied. */
+    afterJob() {
+        this.schedule();
+        if (this.size() === 0 && this.drainWaiters.length > 0) {
+            const waiters = this.drainWaiters.splice(0, this.drainWaiters.length);
+            for (const w of waiters)
+                w();
+        }
+    }
+}
+//# sourceMappingURL=embedding-queue.js.map

memos/_js/embedding-queue.js.map

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

memos/_js/embeddings.d.ts

@@ -0,0 +1,187 @@
+import type { EmbeddingConfig, EmbeddingProvider, EmbeddingRuntimeInfo, EmbeddingVector } from "./types.js";
+/**
+ * Strip all trailing slash characters from a URL/base path without using a
+ * regular expression. Avoids a ReDoS-flagged `/+$/` pattern on user-supplied
+ * input (CodeQL js/regular-expression-polynomial-redos).
+ */
+export declare function stripTrailingSlashes(url: string): string;
+export declare function normalizeVector(vector: EmbeddingVector): EmbeddingVector;
+export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
+export declare class LocalHashEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "local-hash";
+    readonly model: string;
+    readonly dimensions: number;
+    constructor(options?: {
+        dimensions?: number;
+        model?: string;
+    });
+    embed(text: string): Promise<EmbeddingVector>;
+}
+export declare class OllamaEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "ollama";
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly baseUrl;
+    private readonly queryPrefix;
+    private readonly documentPrefix;
+    constructor(options?: {
+        baseUrl?: string;
+        model?: string;
+        dimensions?: number;
+        /** Optional string prepended to QUERY text before embedding. Many
+         *  retrieval models (Liquid E / e5, nomic with a prompt) are
+         *  trained for an asymmetric query/document setting and expect an
+         *  instruction on the query side, e.g. "query: ". Empty by default
+         *  = backward compatible. */
+        queryPrefix?: string;
+        /** Optional string prepended to DOCUMENT text (the index-side
+         *  content) before embedding, e.g. "document: " for Liquid
+         *  LFM2.5-Embedding / e5. Applied by `embed()`/`batchEmbed()` but
+         *  NOT by `embedQuery()`, which applies `queryPrefix` only. Empty
+         *  by default = backward compatible. */
+        documentPrefix?: string;
+    });
+    private callEmbed;
+    embed(text: string): Promise<EmbeddingVector>;
+    /**
+     * Query embedding applies the configured `queryPrefix`, when set, so the
+     * retrieval question is embedded in the model's query mode. Documents are
+     * embedded WITHOUT the prefix (plain indexing text).
+     */
+    embedQuery(text: string): Promise<EmbeddingVector>;
+    batchEmbed(texts: string[]): Promise<EmbeddingVector[]>;
+    embedDocuments(texts: string[]): Promise<EmbeddingVector[]>;
+}
+export declare class OpenAICompatibleEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "openai-compatible";
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly queryPrefix;
+    private readonly documentPrefix;
+    constructor(options: {
+        baseUrl?: string;
+        apiKey?: string;
+        model?: string;
+        dimensions?: number;
+        /** Prepended to QUERY text by `embedQuery()`. Asymmetric retrieval
+         *  models served over OpenAI-compatible endpoints (e.g. Liquid
+         *  LFM2.5-Embedding via llama.cpp, e5 via vLLM) are trained with a
+         *  query-side instruction — e.g. "query: " — and silently degrade
+         *  without it. Empty by default = backward compatible. */
+        queryPrefix?: string;
+        /** Prepended to DOCUMENT text by `embed()`/`batchEmbed()` — e.g.
+         *  "document: " for Liquid LFM2.5-Embedding / e5 index-side text.
+         *  `embedQuery()` applies `queryPrefix` only. Empty by default. */
+        documentPrefix?: string;
+    });
+    private callEmbeddings;
+    embed(text: string): Promise<EmbeddingVector>;
+    embedQuery(text: string): Promise<EmbeddingVector>;
+    batchEmbed(texts: string[]): Promise<EmbeddingVector[]>;
+}
+/**
+ * Voyage AI embedding provider.
+ *
+ * Voyage's `voyage-3` family is the strongest open-weight-class
+ * retrieval model we can hit over HTTP, and it's a common default
+ * for serious RAG work. The provider uses the public
+ * `https://api.voyageai.com/v1/embeddings` endpoint and Bearer auth.
+ */
+export declare class VoyageAIEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "voyage";
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options?: {
+        apiKey?: string;
+        model?: string;
+        dimensions?: number;
+        baseUrl?: string;
+    });
+    embed(text: string): Promise<EmbeddingVector>;
+    batchEmbed(texts: string[]): Promise<EmbeddingVector[]>;
+    private callEmbeddings;
+}
+export declare function createEmbeddingProvider(config: EmbeddingConfig | undefined): EmbeddingProvider;
+/**
+ * Cohere embed-v3 embedding provider.
+ *
+ * Cohere's `embed-english-v3.0` (and its multilingual sibling) is a
+ * strong default for English retrieval. The provider hits
+ * `https://api.cohere.ai/v1/embed` and returns a normalized vector.
+ */
+export declare class CohereEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "cohere";
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly inputType;
+    constructor(options?: {
+        apiKey?: string;
+        model?: string;
+        dimensions?: number;
+        baseUrl?: string;
+        inputType?: string;
+    });
+    embed(text: string): Promise<EmbeddingVector>;
+    batchEmbed(texts: string[]): Promise<EmbeddingVector[]>;
+    private callEmbed;
+}
+export declare class FastEmbedEmbeddingProvider implements EmbeddingProvider {
+    readonly id = "fastembed";
+    readonly model: string;
+    readonly dimensions: number;
+    private pipeline;
+    private resolved;
+    /**
+     * Set when the transformers pipeline could NOT be loaded and the
+     * deterministic local hash fallback is serving embeddings instead.
+     * Null while unresolved or when the real model loaded fine. Exposed
+     * via `getRuntimeInfo()` so benchmarks can detect — and optionally
+     * refuse to run on — the fallback.
+     */
+    private fallbackReason;
+    constructor(options?: {
+        model?: string;
+        dimensions?: number;
+    });
+    /**
+     * Runtime resolution metadata. `fallbackActive` is only meaningful after
+     * the first `embed()` call (or an explicit probe) has triggered
+     * `resolve()`; before that it reports `false` with a null reason, which
+     * callers should read as "not yet known" rather than "no fallback".
+     */
+    getRuntimeInfo(): EmbeddingRuntimeInfo;
+    /** Dimensions seen on the most recent embed/batchEmbed result. */
+    private lastObservedDimensions;
+    /**
+     * Lazily resolve the transformers pipeline. We use a dynamic import so
+     * the optional dep is only paid for when (and if) the user installs it.
+     * Any failure to load silently falls back to the local hash.
+     *
+     * Tries `@huggingface/transformers` (the maintained successor) first,
+     * then falls back to the abandoned `@xenova/transformers` for users who
+     * still have it installed.
+     */
+    private resolve;
+    /**
+     * One-time loud warning when the local-hash fallback activates. Silent
+     * degradation is the worst plug-in experience: everything "works" but
+     * semantic search quietly returns garbage.
+     */
+    private warnFallbackOnce;
+    embed(text: string): Promise<EmbeddingVector>;
+    batchEmbed(texts: string[]): Promise<EmbeddingVector[]>;
+    /**
+     * Deterministic feature-hash fallback. Produces a `dimensions`-long
+     * vector with the same shape (and L2 norm) as a real
+     * sentence-transformer embedding, so storage and ranking code is
+     * identical to the online path.
+     */
+    private fallbackEmbed;
+}
+//# sourceMappingURL=embeddings.d.ts.map

memos/_js/embeddings.d.ts.map

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