@happyvertical/smrt-core 0.30.0

package/dist/embeddings/similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.js","sources":["../../src/embeddings/similarity.ts"],"sourcesContent":["/**\n * Vector Similarity Calculations\n *\n * Provides cosine similarity for semantic search.\n */\n\n/**\n * Cosine similarity calculator for embedding vectors\n */\nexport class CosineSimilarity {\n  /**\n   * Calculate cosine similarity between two vectors\n   *\n   * @param a - First embedding vector\n   * @param b - Second embedding vector\n   * @returns Similarity score between -1 and 1 (higher = more similar)\n   * @throws Error if vectors have different dimensions\n   */\n  static calculate(a: number[], b: number[]): number {\n    if (a.length !== b.length) {\n      throw new Error(\n        `Vector dimension mismatch: ${a.length} vs ${b.length}. ` +\n          'Ensure all embeddings use the same model and dimensions.',\n      );\n    }\n\n    if (a.length === 0) {\n      return 0;\n    }\n\n    let dotProduct = 0;\n    let normA = 0;\n    let normB = 0;\n\n    for (let i = 0; i < a.length; i++) {\n      dotProduct += a[i] * b[i];\n      normA += a[i] * a[i];\n      normB += b[i] * b[i];\n    }\n\n    const denominator = Math.sqrt(normA) * Math.sqrt(normB);\n\n    if (denominator === 0) {\n      return 0;\n    }\n\n    return dotProduct / denominator;\n  }\n\n  /**\n   * Calculate similarities between a query vector and multiple candidates\n   *\n   * @param query - Query embedding vector\n   * @param candidates - Array of candidate vectors with IDs\n   * @returns Array sorted by similarity (highest first)\n   */\n  static rankBySimilarity<T extends { id: string; embedding: number[] }>(\n    query: number[],\n    candidates: T[],\n  ): Array<T & { similarity: number }> {\n    const results = candidates.map((candidate) => ({\n      ...candidate,\n      similarity: CosineSimilarity.calculate(query, candidate.embedding),\n    }));\n\n    return results.sort((a, b) => b.similarity - a.similarity);\n  }\n\n  /**\n   * Filter candidates by minimum similarity threshold\n   *\n   * @param query - Query embedding vector\n   * @param candidates - Array of candidate vectors\n   * @param minSimilarity - Minimum similarity threshold (0-1)\n   * @returns Filtered and sorted results\n   */\n  static filterBySimilarity<T extends { id: string; embedding: number[] }>(\n    query: number[],\n    candidates: T[],\n    minSimilarity: number,\n  ): Array<T & { similarity: number }> {\n    return CosineSimilarity.rankBySimilarity(query, candidates).filter(\n      (result) => result.similarity >= minSimilarity,\n    );\n  }\n}\n"],"names":[],"mappings":"AASO,MAAM,iBAAiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAS5B,OAAO,UAAU,GAAa,GAAqB;AACjD,QAAI,EAAE,WAAW,EAAE,QAAQ;AACzB,YAAM,IAAI;AAAA,QACR,8BAA8B,EAAE,MAAM,OAAO,EAAE,MAAM;AAAA,MAAA;AAAA,IAGzD;AAEA,QAAI,EAAE,WAAW,GAAG;AAClB,aAAO;AAAA,IACT;AAEA,QAAI,aAAa;AACjB,QAAI,QAAQ;AACZ,QAAI,QAAQ;AAEZ,aAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,oBAAc,EAAE,CAAC,IAAI,EAAE,CAAC;AACxB,eAAS,EAAE,CAAC,IAAI,EAAE,CAAC;AACnB,eAAS,EAAE,CAAC,IAAI,EAAE,CAAC;AAAA,IACrB;AAEA,UAAM,cAAc,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK;AAEtD,QAAI,gBAAgB,GAAG;AACrB,aAAO;AAAA,IACT;AAEA,WAAO,aAAa;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,iBACL,OACA,YACmC;AACnC,UAAM,UAAU,WAAW,IAAI,CAAC,eAAe;AAAA,MAC7C,GAAG;AAAA,MACH,YAAY,iBAAiB,UAAU,OAAO,UAAU,SAAS;AAAA,IAAA,EACjE;AAEF,WAAO,QAAQ,KAAK,CAAC,GAAG,MAAM,EAAE,aAAa,EAAE,UAAU;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,OAAO,mBACL,OACA,YACA,eACmC;AACnC,WAAO,iBAAiB,iBAAiB,OAAO,UAAU,EAAE;AAAA,MAC1D,CAAC,WAAW,OAAO,cAAc;AAAA,IAAA;AAAA,EAErC;AACF;"}

package/dist/embeddings/storage.d.ts

@@ -0,0 +1,125 @@
+import { DatabaseInterface, VectorCapabilities } from '@happyvertical/sql';
+import { StoredEmbedding } from './types';
+/**
+ * Storage operations for embeddings in _smrt_embeddings table
+ */
+export declare class EmbeddingStorage {
+    /**
+     * Insert or update an embedding
+     *
+     * @param db - Database interface
+     * @param data - Embedding data to store
+     * @param vector - Optional vector capabilities for native storage
+     */
+    static upsert(db: DatabaseInterface, data: {
+        objectClass: string;
+        objectId: string;
+        fieldName: string;
+        contentHash: string;
+        embedding: number[];
+        model: string;
+        dimensions: number;
+        provider?: string;
+    }, vector?: VectorCapabilities): Promise<void>;
+    /**
+     * Search for similar embeddings using the best available strategy.
+     *
+     * When vector capabilities are provided, delegates to database-level
+     * vector search. Otherwise falls back to loading all embeddings and
+     * computing cosine similarity in memory.
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name to search within
+     * @param embedding - Query embedding vector
+     * @param options - Search options
+     * @param vector - Optional vector capabilities for native search
+     * @returns Array of { objectId, similarity } ranked by similarity (highest first)
+     */
+    static searchSimilar(db: DatabaseInterface, objectClass: string, embedding: number[], options?: {
+        field?: string;
+        model?: string;
+        limit?: number;
+        minSimilarity?: number;
+    }, vector?: VectorCapabilities): Promise<Array<{
+        objectId: string;
+        similarity: number;
+    }>>;
+    /**
+     * Ensure the native vector column and index exist on _smrt_embeddings.
+     * Called once during initialization when storage: 'native' is configured.
+     *
+     * @param db - Database interface
+     * @param dimensions - Vector dimensions
+     * @param vector - Vector capabilities
+     */
+    static ensureVectorStorage(_db: DatabaseInterface, dimensions: number, vector: VectorCapabilities): Promise<void>;
+    /**
+     * Get a specific embedding
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name
+     * @param objectId - Object ID
+     * @param fieldName - Field name
+     * @param model - Model used
+     * @returns Stored embedding or null
+     */
+    static get(db: DatabaseInterface, objectClass: string, objectId: string, fieldName: string, model: string): Promise<StoredEmbedding | null>;
+    /**
+     * Get all embeddings for an object
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name
+     * @param objectId - Object ID
+     * @returns Array of stored embeddings
+     */
+    static getForObject(db: DatabaseInterface, objectClass: string, objectId: string): Promise<StoredEmbedding[]>;
+    /**
+     * List embeddings for a class (optionally filtered by field and model)
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name
+     * @param fieldName - Optional field filter
+     * @param model - Optional model filter
+     * @returns Array of stored embeddings
+     */
+    static listForClass(db: DatabaseInterface, objectClass: string, fieldName?: string, model?: string): Promise<StoredEmbedding[]>;
+    /**
+     * Get object IDs that have embeddings for a specific field
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name
+     * @param fieldName - Field name
+     * @returns Array of object IDs
+     */
+    static getObjectIdsWithEmbeddings(db: DatabaseInterface, objectClass: string, fieldName: string): Promise<string[]>;
+    /**
+     * Delete all embeddings for an object
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name
+     * @param objectId - Object ID
+     */
+    static deleteForObject(db: DatabaseInterface, objectClass: string, objectId: string): Promise<void>;
+    /**
+     * Delete a specific embedding
+     *
+     * @param db - Database interface
+     * @param objectClass - Class name
+     * @param objectId - Object ID
+     * @param fieldName - Field name
+     * @param model - Model used
+     */
+    static delete(db: DatabaseInterface, objectClass: string, objectId: string, fieldName: string, model: string): Promise<void>;
+    /**
+     * Check if embedding table exists
+     *
+     * @param db - Database interface
+     * @returns True if table exists
+     */
+    static tableExists(db: DatabaseInterface): Promise<boolean>;
+    /**
+     * Parse a database row into StoredEmbedding
+     */
+    private static parseRow;
+}
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/embeddings/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAO/C;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;OAMG;WACU,MAAM,CACjB,EAAE,EAAE,iBAAiB,EACrB,IAAI,EAAE;QACJ,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,EACD,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC;IA6ChB;;;;;;;;;;;;;OAaG;WACU,aAAa,CACxB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACnB,EACN,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAuE3D;;;;;;;OAOG;WACU,mBAAmB,CAC9B,GAAG,EAAE,iBAAiB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;;;;;OASG;WACU,GAAG,CACd,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAclC;;;;;;;OAOG;WACU,YAAY,CACvB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,EAAE,CAAC;IAY7B;;;;;;;;OAQG;WACU,YAAY,CACvB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC;IAqB7B;;;;;;;OAOG;WACU,0BAA0B,CACrC,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC;IAWpB;;;;;;OAMG;WACU,eAAe,CAC1B,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;;;OAQG;WACU,MAAM,CACjB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;OAKG;WACU,WAAW,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IASjE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CAexB"}

package/dist/embeddings/storage.js

@@ -0,0 +1,283 @@
+import { randomUUID } from "node:crypto";
+import { createLogger } from "@happyvertical/logger";
+import { CosineSimilarity } from "./similarity.js";
+const logger = createLogger({ level: "info" });
+const VECTOR_COLUMN = "embedding_vector";
+class EmbeddingStorage {
+  /**
+   * Insert or update an embedding
+   *
+   * @param db - Database interface
+   * @param data - Embedding data to store
+   * @param vector - Optional vector capabilities for native storage
+   */
+  static async upsert(db, data, vector) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const id = randomUUID();
+    await db.upsert(
+      "_smrt_embeddings",
+      ["object_class", "object_id", "field_name", "model"],
+      {
+        id,
+        object_class: data.objectClass,
+        object_id: data.objectId,
+        field_name: data.fieldName,
+        content_hash: data.contentHash,
+        embedding: JSON.stringify(data.embedding),
+        model: data.model,
+        dimensions: data.dimensions,
+        provider: data.provider || null,
+        created_at: now,
+        updated_at: now
+      }
+    );
+    if (vector) {
+      try {
+        await vector.upsertVector(
+          "_smrt_embeddings",
+          {
+            object_class: data.objectClass,
+            object_id: data.objectId,
+            field_name: data.fieldName,
+            model: data.model
+          },
+          VECTOR_COLUMN,
+          data.embedding
+        );
+      } catch (error) {
+        logger.warn(
+          `[embeddings] Failed to store native vector: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
+  /**
+   * Search for similar embeddings using the best available strategy.
+   *
+   * When vector capabilities are provided, delegates to database-level
+   * vector search. Otherwise falls back to loading all embeddings and
+   * computing cosine similarity in memory.
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name to search within
+   * @param embedding - Query embedding vector
+   * @param options - Search options
+   * @param vector - Optional vector capabilities for native search
+   * @returns Array of { objectId, similarity } ranked by similarity (highest first)
+   */
+  static async searchSimilar(db, objectClass, embedding, options = {}, vector) {
+    const { field, model, limit = 10, minSimilarity = 0 } = options;
+    if (vector) {
+      try {
+        const conditions = ["object_class = $2"];
+        const params = [objectClass];
+        if (field) {
+          conditions.push(`field_name = $${params.length + 2}`);
+          params.push(field);
+        }
+        if (model) {
+          conditions.push(`model = $${params.length + 2}`);
+          params.push(model);
+        }
+        const results = await vector.search(
+          "_smrt_embeddings",
+          VECTOR_COLUMN,
+          embedding,
+          {
+            limit,
+            metric: "cosine",
+            where: conditions.join(" AND "),
+            params
+          }
+        );
+        return results.map((r) => ({
+          objectId: r.object_id,
+          similarity: 1 - r.distance
+        })).filter((r) => r.similarity >= minSimilarity);
+      } catch (error) {
+        logger.warn(
+          `[embeddings] Native vector search failed, falling back to in-memory: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    const storedEmbeddings = await EmbeddingStorage.listForClass(
+      db,
+      objectClass,
+      field,
+      model
+    );
+    if (storedEmbeddings.length === 0) {
+      return [];
+    }
+    return storedEmbeddings.map((stored) => ({
+      objectId: stored.object_id,
+      similarity: CosineSimilarity.calculate(embedding, stored.embedding)
+    })).filter((item) => item.similarity >= minSimilarity).sort((a, b) => b.similarity - a.similarity).slice(0, limit);
+  }
+  /**
+   * Ensure the native vector column and index exist on _smrt_embeddings.
+   * Called once during initialization when storage: 'native' is configured.
+   *
+   * @param db - Database interface
+   * @param dimensions - Vector dimensions
+   * @param vector - Vector capabilities
+   */
+  static async ensureVectorStorage(_db, dimensions, vector) {
+    await vector.ensureColumn("_smrt_embeddings", VECTOR_COLUMN, dimensions);
+    await vector.ensureIndex("_smrt_embeddings", VECTOR_COLUMN, {
+      dimensions,
+      metric: "cosine",
+      type: "hnsw"
+    });
+  }
+  /**
+   * Get a specific embedding
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name
+   * @param objectId - Object ID
+   * @param fieldName - Field name
+   * @param model - Model used
+   * @returns Stored embedding or null
+   */
+  static async get(db, objectClass, objectId, fieldName, model) {
+    const result = await db.single`
+      SELECT * FROM _smrt_embeddings
+      WHERE object_class = ${objectClass}
+        AND object_id = ${objectId}
+        AND field_name = ${fieldName}
+        AND model = ${model}
+    `;
+    if (!result) return null;
+    return EmbeddingStorage.parseRow(result);
+  }
+  /**
+   * Get all embeddings for an object
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name
+   * @param objectId - Object ID
+   * @returns Array of stored embeddings
+   */
+  static async getForObject(db, objectClass, objectId) {
+    const { rows } = await db.query(
+      `SELECT * FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,
+      objectClass,
+      objectId
+    );
+    return rows.map(
+      (row) => EmbeddingStorage.parseRow(row)
+    );
+  }
+  /**
+   * List embeddings for a class (optionally filtered by field and model)
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name
+   * @param fieldName - Optional field filter
+   * @param model - Optional model filter
+   * @returns Array of stored embeddings
+   */
+  static async listForClass(db, objectClass, fieldName, model) {
+    let sql = `SELECT * FROM _smrt_embeddings WHERE object_class = ?`;
+    const params = [objectClass];
+    if (fieldName) {
+      sql += ` AND field_name = ?`;
+      params.push(fieldName);
+    }
+    if (model) {
+      sql += ` AND model = ?`;
+      params.push(model);
+    }
+    const { rows } = await db.query(sql, ...params);
+    return rows.map(
+      (row) => EmbeddingStorage.parseRow(row)
+    );
+  }
+  /**
+   * Get object IDs that have embeddings for a specific field
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name
+   * @param fieldName - Field name
+   * @returns Array of object IDs
+   */
+  static async getObjectIdsWithEmbeddings(db, objectClass, fieldName) {
+    const { rows } = await db.query(
+      `SELECT DISTINCT object_id FROM _smrt_embeddings
+       WHERE object_class = ? AND field_name = ?`,
+      objectClass,
+      fieldName
+    );
+    return rows.map((row) => row.object_id);
+  }
+  /**
+   * Delete all embeddings for an object
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name
+   * @param objectId - Object ID
+   */
+  static async deleteForObject(db, objectClass, objectId) {
+    await db.query(
+      `DELETE FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,
+      objectClass,
+      objectId
+    );
+  }
+  /**
+   * Delete a specific embedding
+   *
+   * @param db - Database interface
+   * @param objectClass - Class name
+   * @param objectId - Object ID
+   * @param fieldName - Field name
+   * @param model - Model used
+   */
+  static async delete(db, objectClass, objectId, fieldName, model) {
+    await db.query(
+      `DELETE FROM _smrt_embeddings
+       WHERE object_class = ? AND object_id = ? AND field_name = ? AND model = ?`,
+      objectClass,
+      objectId,
+      fieldName,
+      model
+    );
+  }
+  /**
+   * Check if embedding table exists
+   *
+   * @param db - Database interface
+   * @returns True if table exists
+   */
+  static async tableExists(db) {
+    try {
+      await db.query(`SELECT 1 FROM _smrt_embeddings LIMIT 1`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Parse a database row into StoredEmbedding
+   */
+  static parseRow(row) {
+    return {
+      id: row.id,
+      object_class: row.object_class,
+      object_id: row.object_id,
+      field_name: row.field_name,
+      content_hash: row.content_hash,
+      embedding: JSON.parse(row.embedding),
+      model: row.model,
+      dimensions: row.dimensions,
+      provider: row.provider,
+      created_at: new Date(row.created_at),
+      updated_at: new Date(row.updated_at)
+    };
+  }
+}
+export {
+  EmbeddingStorage
+};
+//# sourceMappingURL=storage.js.map

package/dist/embeddings/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sources":["../../src/embeddings/storage.ts"],"sourcesContent":["/**\n * Embedding Storage Operations\n *\n * CRUD operations for the _smrt_embeddings system table.\n * Supports both JSON-based and native vector storage strategies.\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface, VectorCapabilities } from '@happyvertical/sql';\nimport { CosineSimilarity } from './similarity';\nimport type { StoredEmbedding } from './types';\n\nconst logger = createLogger({ level: 'info' });\n\n/** Column name for native vector storage */\nconst VECTOR_COLUMN = 'embedding_vector';\n\n/**\n * Storage operations for embeddings in _smrt_embeddings table\n */\nexport class EmbeddingStorage {\n  /**\n   * Insert or update an embedding\n   *\n   * @param db - Database interface\n   * @param data - Embedding data to store\n   * @param vector - Optional vector capabilities for native storage\n   */\n  static async upsert(\n    db: DatabaseInterface,\n    data: {\n      objectClass: string;\n      objectId: string;\n      fieldName: string;\n      contentHash: string;\n      embedding: number[];\n      model: string;\n      dimensions: number;\n      provider?: string;\n    },\n    vector?: VectorCapabilities,\n  ): Promise<void> {\n    const now = new Date().toISOString();\n    const id = randomUUID();\n\n    await db.upsert(\n      '_smrt_embeddings',\n      ['object_class', 'object_id', 'field_name', 'model'],\n      {\n        id,\n        object_class: data.objectClass,\n        object_id: data.objectId,\n        field_name: data.fieldName,\n        content_hash: data.contentHash,\n        embedding: JSON.stringify(data.embedding),\n        model: data.model,\n        dimensions: data.dimensions,\n        provider: data.provider || null,\n        created_at: now,\n        updated_at: now,\n      },\n    );\n\n    // Also store native vector if capability is available\n    if (vector) {\n      try {\n        await vector.upsertVector(\n          '_smrt_embeddings',\n          {\n            object_class: data.objectClass,\n            object_id: data.objectId,\n            field_name: data.fieldName,\n            model: data.model,\n          },\n          VECTOR_COLUMN,\n          data.embedding,\n        );\n      } catch (error) {\n        // Log but don't fail — JSON fallback is always available\n        logger.warn(\n          `[embeddings] Failed to store native vector: ${error instanceof Error ? error.message : String(error)}`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Search for similar embeddings using the best available strategy.\n   *\n   * When vector capabilities are provided, delegates to database-level\n   * vector search. Otherwise falls back to loading all embeddings and\n   * computing cosine similarity in memory.\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name to search within\n   * @param embedding - Query embedding vector\n   * @param options - Search options\n   * @param vector - Optional vector capabilities for native search\n   * @returns Array of { objectId, similarity } ranked by similarity (highest first)\n   */\n  static async searchSimilar(\n    db: DatabaseInterface,\n    objectClass: string,\n    embedding: number[],\n    options: {\n      field?: string;\n      model?: string;\n      limit?: number;\n      minSimilarity?: number;\n    } = {},\n    vector?: VectorCapabilities,\n  ): Promise<Array<{ objectId: string; similarity: number }>> {\n    const { field, model, limit = 10, minSimilarity = 0 } = options;\n\n    // Native vector search path\n    if (vector) {\n      try {\n        // Build WHERE clause for class/field/model filtering.\n        // Parameter numbering starts at $2 because vector.search() reserves\n        // $1 for the query vector embedding in its internal SQL query.\n        const conditions: string[] = ['object_class = $2'];\n        const params: any[] = [objectClass];\n\n        if (field) {\n          conditions.push(`field_name = $${params.length + 2}`);\n          params.push(field);\n        }\n\n        if (model) {\n          conditions.push(`model = $${params.length + 2}`);\n          params.push(model);\n        }\n\n        const results = await vector.search(\n          '_smrt_embeddings',\n          VECTOR_COLUMN,\n          embedding,\n          {\n            limit,\n            metric: 'cosine',\n            where: conditions.join(' AND '),\n            params,\n          },\n        );\n\n        // Convert cosine distance (0=identical, 2=opposite) to similarity (1=identical, -1=opposite)\n        return results\n          .map((r) => ({\n            objectId: r.object_id as string,\n            similarity: 1 - r.distance,\n          }))\n          .filter((r) => r.similarity >= minSimilarity);\n      } catch (error) {\n        // Fall back to in-memory search on vector search failure\n        logger.warn(\n          `[embeddings] Native vector search failed, falling back to in-memory: ${error instanceof Error ? error.message : String(error)}`,\n        );\n      }\n    }\n\n    // In-memory fallback: load all embeddings and compute cosine similarity\n    const storedEmbeddings = await EmbeddingStorage.listForClass(\n      db,\n      objectClass,\n      field,\n      model,\n    );\n\n    if (storedEmbeddings.length === 0) {\n      return [];\n    }\n\n    return storedEmbeddings\n      .map((stored) => ({\n        objectId: stored.object_id,\n        similarity: CosineSimilarity.calculate(embedding, stored.embedding),\n      }))\n      .filter((item) => item.similarity >= minSimilarity)\n      .sort((a, b) => b.similarity - a.similarity)\n      .slice(0, limit);\n  }\n\n  /**\n   * Ensure the native vector column and index exist on _smrt_embeddings.\n   * Called once during initialization when storage: 'native' is configured.\n   *\n   * @param db - Database interface\n   * @param dimensions - Vector dimensions\n   * @param vector - Vector capabilities\n   */\n  static async ensureVectorStorage(\n    _db: DatabaseInterface,\n    dimensions: number,\n    vector: VectorCapabilities,\n  ): Promise<void> {\n    await vector.ensureColumn('_smrt_embeddings', VECTOR_COLUMN, dimensions);\n    await vector.ensureIndex('_smrt_embeddings', VECTOR_COLUMN, {\n      dimensions,\n      metric: 'cosine',\n      type: 'hnsw',\n    });\n  }\n\n  /**\n   * Get a specific embedding\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @param fieldName - Field name\n   * @param model - Model used\n   * @returns Stored embedding or null\n   */\n  static async get(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n    fieldName: string,\n    model: string,\n  ): Promise<StoredEmbedding | null> {\n    const result = await db.single`\n      SELECT * FROM _smrt_embeddings\n      WHERE object_class = ${objectClass}\n        AND object_id = ${objectId}\n        AND field_name = ${fieldName}\n        AND model = ${model}\n    `;\n\n    if (!result) return null;\n\n    return EmbeddingStorage.parseRow(result);\n  }\n\n  /**\n   * Get all embeddings for an object\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @returns Array of stored embeddings\n   */\n  static async getForObject(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n  ): Promise<StoredEmbedding[]> {\n    const { rows } = await db.query(\n      `SELECT * FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,\n      objectClass,\n      objectId,\n    );\n\n    return rows.map((row: Record<string, unknown>) =>\n      EmbeddingStorage.parseRow(row),\n    );\n  }\n\n  /**\n   * List embeddings for a class (optionally filtered by field and model)\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param fieldName - Optional field filter\n   * @param model - Optional model filter\n   * @returns Array of stored embeddings\n   */\n  static async listForClass(\n    db: DatabaseInterface,\n    objectClass: string,\n    fieldName?: string,\n    model?: string,\n  ): Promise<StoredEmbedding[]> {\n    let sql = `SELECT * FROM _smrt_embeddings WHERE object_class = ?`;\n    const params: unknown[] = [objectClass];\n\n    if (fieldName) {\n      sql += ` AND field_name = ?`;\n      params.push(fieldName);\n    }\n\n    if (model) {\n      sql += ` AND model = ?`;\n      params.push(model);\n    }\n\n    const { rows } = await db.query(sql, ...params);\n\n    return rows.map((row: Record<string, unknown>) =>\n      EmbeddingStorage.parseRow(row),\n    );\n  }\n\n  /**\n   * Get object IDs that have embeddings for a specific field\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param fieldName - Field name\n   * @returns Array of object IDs\n   */\n  static async getObjectIdsWithEmbeddings(\n    db: DatabaseInterface,\n    objectClass: string,\n    fieldName: string,\n  ): Promise<string[]> {\n    const { rows } = await db.query(\n      `SELECT DISTINCT object_id FROM _smrt_embeddings\n       WHERE object_class = ? AND field_name = ?`,\n      objectClass,\n      fieldName,\n    );\n\n    return rows.map((row: Record<string, unknown>) => row.object_id as string);\n  }\n\n  /**\n   * Delete all embeddings for an object\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   */\n  static async deleteForObject(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n  ): Promise<void> {\n    await db.query(\n      `DELETE FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,\n      objectClass,\n      objectId,\n    );\n  }\n\n  /**\n   * Delete a specific embedding\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @param fieldName - Field name\n   * @param model - Model used\n   */\n  static async delete(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n    fieldName: string,\n    model: string,\n  ): Promise<void> {\n    await db.query(\n      `DELETE FROM _smrt_embeddings\n       WHERE object_class = ? AND object_id = ? AND field_name = ? AND model = ?`,\n      objectClass,\n      objectId,\n      fieldName,\n      model,\n    );\n  }\n\n  /**\n   * Check if embedding table exists\n   *\n   * @param db - Database interface\n   * @returns True if table exists\n   */\n  static async tableExists(db: DatabaseInterface): Promise<boolean> {\n    try {\n      await db.query(`SELECT 1 FROM _smrt_embeddings LIMIT 1`);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Parse a database row into StoredEmbedding\n   */\n  private static parseRow(row: Record<string, unknown>): StoredEmbedding {\n    return {\n      id: row.id as string,\n      object_class: row.object_class as string,\n      object_id: row.object_id as string,\n      field_name: row.field_name as string,\n      content_hash: row.content_hash as string,\n      embedding: JSON.parse(row.embedding as string) as number[],\n      model: row.model as string,\n      dimensions: row.dimensions as number,\n      provider: row.provider as string | undefined,\n      created_at: new Date(row.created_at as string),\n      updated_at: new Date(row.updated_at as string),\n    };\n  }\n}\n"],"names":[],"mappings":"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"}