From 92a80e16064c08363508b9b2889b62756d8eb910 Mon Sep 17 00:00:00 2001
From: mbeaulne <matt.beaulne@gmail.com>
Date: Thu, 18 Jun 2026 14:18:10 -0400
Subject: [PATCH] add client-side embeddings cached in IndexedDB

---
 .../Dashboard/DashboardComponentsV2View.tsx   |  79 +++++-
 .../Editor/hooks/useComponentSearchV2State.ts |  92 ++++++-
 .../componentSearchEmbeddings.test.ts         | 168 ++++++++++++
 src/services/componentSearchEmbeddings.ts     | 257 ++++++++++++++++++
 4 files changed, 581 insertions(+), 15 deletions(-)
 create mode 100644 src/services/componentSearchEmbeddings.test.ts
 create mode 100644 src/services/componentSearchEmbeddings.ts

diff --git a/src/routes/Dashboard/DashboardComponentsV2View.tsx b/src/routes/Dashboard/DashboardComponentsV2View.tsx
index e8d1c2cb6..7bda95495 100644
--- a/src/routes/Dashboard/DashboardComponentsV2View.tsx
+++ b/src/routes/Dashboard/DashboardComponentsV2View.tsx
@@ -20,6 +20,7 @@ import { Skeleton } from "@/components/ui/skeleton";
 import { Spinner } from "@/components/ui/spinner";
 import { QuickTooltip } from "@/components/ui/tooltip";
 import { Heading, Paragraph, Text } from "@/components/ui/typography";
+import { useAiProviderSettings } from "@/hooks/useAiProviderSettings";
 import { getComponentQueryKey } from "@/hooks/useHydrateComponentReference";
 import {
   useComponentAiDescription,
@@ -38,6 +39,7 @@ import {
   LibraryDB,
   type StoredLibrary,
 } from "@/providers/ComponentLibraryProvider/libraries/storage";
+import { rankComponentMatchesByEmbeddings } from "@/services/componentSearchEmbeddings";
 import {
   buildSearchIndex,
   type ComponentSearchSource,
@@ -437,6 +439,23 @@ function sampleEvenly<T>(entries: T[], limit: number): T[] {
   return sampled;
 }
 
+function mergeUniqueMatches(
+  primary: LexicalMatch[],
+  secondary: LexicalMatch[],
+  fallback: LexicalMatch[],
+  limit: number,
+): LexicalMatch[] {
+  const merged: LexicalMatch[] = [];
+  const seen = new Set<string>();
+  for (const match of [...primary, ...secondary, ...fallback]) {
+    if (seen.has(match.digest)) continue;
+    seen.add(match.digest);
+    merged.push(match);
+    if (merged.length >= limit) return merged;
+  }
+  return merged;
+}
+
 function collectAllSourcedReferences({
   standardLibrary,
   publishedRefs,
@@ -485,6 +504,7 @@ export const DashboardComponentsV2View = () => {
     "component-search-v2-ai-descriptions",
   );
   const { backendUrl, configured, available } = useBackend();
+  const { config: aiConfig } = useAiProviderSettings();
   const [query, setQuery] = useState("");
   const [disabledSourceKeys, setDisabledSourceKeys] = useState<string[]>([]);
 
@@ -770,6 +790,8 @@ export const DashboardComponentsV2View = () => {
   const [rerankBaseMatches, setRerankBaseMatches] = useState<LexicalMatch[]>(
     [],
   );
+  const [isEmbeddingSearchPending, setIsEmbeddingSearchPending] =
+    useState(false);
 
   const handleQueryChange = (event: ChangeEvent<HTMLInputElement>) => {
     setQuery(event.target.value);
@@ -780,27 +802,57 @@ export const DashboardComponentsV2View = () => {
     }
   };
 
-  const startAiSearch = (matches: LexicalMatch[]) => {
+  const buildEmbeddingMatches = async (
+    trimmed: string,
+    limit: number,
+  ): Promise<LexicalMatch[]> => {
+    if (!aiConfig.apiBase.trim()) return [];
+    setIsEmbeddingSearchPending(true);
+    try {
+      return await rankComponentMatchesByEmbeddings(
+        filteredIndex,
+        trimmed,
+        { apiBase: aiConfig.apiBase, apiKey: aiConfig.apiKey },
+        { limit },
+      );
+    } catch {
+      return [];
+    } finally {
+      setIsEmbeddingSearchPending(false);
+    }
+  };
+
+  const startAiSearch = async (matches: LexicalMatch[], limit: number) => {
     const trimmed = query.trim();
     if (trimmed.length === 0 || matches.length === 0) return;
 
-    const candidates = matches
+    const embeddingMatches = aiConfig.apiBase.trim()
+      ? await buildEmbeddingMatches(trimmed, limit)
+      : [];
+    const rerankMatches = mergeUniqueMatches(
+      matches.slice(0, 60),
+      embeddingMatches,
+      matches,
+      limit,
+    );
+
+    const candidates = rerankMatches
       .map((m) => componentReferenceToCandidate(m.reference, m.source))
       .filter((c): c is NonNullable<typeof c> => c !== null);
 
     if (candidates.length === 0) return;
 
-    setRerankBaseMatches(matches);
+    setRerankBaseMatches(rerankMatches);
     setRerankedFor(trimmed);
     rerank({ query: trimmed, candidates });
   };
 
   const handleSmartSearch = () => {
-    startAiSearch(aiCandidateMatches);
+    void startAiSearch(aiCandidateMatches, aiCandidateMatches.length);
   };
 
   const handleDeepAiSearch = () => {
-    startAiSearch(deepAiCandidateMatches);
+    void startAiSearch(deepAiCandidateMatches, deepAiCandidateMatches.length);
   };
 
   const handleSourceToggle = (sourceKey: string) => {
@@ -845,7 +897,8 @@ export const DashboardComponentsV2View = () => {
     rerankData !== undefined &&
     rerankData.matches.length > 0 &&
     rerankBaseMatches.length > 0 &&
-    !isReranking;
+    !isReranking &&
+    !isEmbeddingSearchPending;
 
   // What we actually render. Rerank wins when active; otherwise lexical.
   const displayedResults = rerankActive
@@ -1033,20 +1086,30 @@ export const DashboardComponentsV2View = () => {
               onClick={handleSmartSearch}
               disabled={
                 isReranking ||
+                isEmbeddingSearchPending ||
                 isEmpty ||
                 aiCandidateMatches.length === 0 ||
                 !isConfigured
               }
-              aria-label={isReranking ? "AI search in progress" : "AI search"}
+              aria-label={
+                isReranking || isEmbeddingSearchPending
+                  ? "AI search in progress"
+                  : "AI search"
+              }
               title="AI search — rerank these results with an LLM"
             >
-              {isReranking ? <Spinner size={16} /> : <Icon name="Sparkles" />}
+              {isReranking || isEmbeddingSearchPending ? (
+                <Spinner size={16} />
+              ) : (
+                <Icon name="Sparkles" />
+              )}
             </Button>
             <Button
               variant="outline"
               onClick={handleDeepAiSearch}
               disabled={
                 isReranking ||
+                isEmbeddingSearchPending ||
                 isEmpty ||
                 deepAiCandidateMatches.length === 0 ||
                 !isConfigured
diff --git a/src/routes/v2/pages/Editor/hooks/useComponentSearchV2State.ts b/src/routes/v2/pages/Editor/hooks/useComponentSearchV2State.ts
index af8165193..ca57b0a46 100644
--- a/src/routes/v2/pages/Editor/hooks/useComponentSearchV2State.ts
+++ b/src/routes/v2/pages/Editor/hooks/useComponentSearchV2State.ts
@@ -3,6 +3,7 @@ import { useLiveQuery } from "dexie-react-hooks";
 import { useEffect, useState } from "react";
 
 import { listApiPublishedComponentsGet } from "@/api/sdk.gen";
+import { useAiProviderSettings } from "@/hooks/useAiProviderSettings";
 import { getComponentQueryKey } from "@/hooks/useHydrateComponentReference";
 import { useNaturalLanguageComponentRerank } from "@/hooks/useNaturalLanguageComponentSearch";
 import { useBackend } from "@/providers/BackendProvider";
@@ -30,8 +31,10 @@ import {
   registeredSource,
   rerankedMatches,
 } from "@/routes/v2/pages/Editor/components/componentSearchV2Logic";
+import { rankComponentMatchesByEmbeddings } from "@/services/componentSearchEmbeddings";
 import {
   buildSearchIndex,
+  type IndexEntry,
   type LexicalMatch,
   type SourcedReference,
 } from "@/services/componentSearchIndex";
@@ -47,11 +50,29 @@ import type {
 } from "@/utils/componentSpec";
 import { HOURS } from "@/utils/constants";
 
+function mergeUniqueMatches(
+  primary: LexicalMatch[],
+  secondary: LexicalMatch[],
+  fallback: LexicalMatch[],
+  limit: number,
+): LexicalMatch[] {
+  const merged: LexicalMatch[] = [];
+  const seen = new Set<string>();
+  for (const match of [...primary, ...secondary, ...fallback]) {
+    if (seen.has(match.digest)) continue;
+    seen.add(match.digest);
+    merged.push(match);
+    if (merged.length >= limit) return merged;
+  }
+  return merged;
+}
+
 export function useComponentSearchV2State(
   query: string,
 ): ComponentSearchV2State {
   const queryClient = useQueryClient();
   const { backendUrl, configured, available } = useBackend();
+  const { config: aiConfig } = useAiProviderSettings();
 
   const { data: standardLibrary, isLoading: isLoadingStandardLibrary } =
     useQuery({
@@ -191,6 +212,8 @@ export function useComponentSearchV2State(
   const [rerankBaseMatches, setRerankBaseMatches] = useState<LexicalMatch[]>(
     [],
   );
+  const [isEmbeddingSearchPending, setIsEmbeddingSearchPending] =
+    useState(false);
 
   useEffect(() => {
     setRerankedFor(null);
@@ -201,19 +224,66 @@ export function useComponentSearchV2State(
     rerankedFor === trimmedQuery &&
     rerankBaseMatches.length > 0 &&
     !isReranking &&
+    !isEmbeddingSearchPending &&
     rerankData !== undefined;
 
   const displayedMatches = isRerankActive
     ? rerankedMatches(rerankData, rerankBaseMatches)
     : lexicalMatches;
 
-  const startRerank = (
+  const buildEmbeddingMatches = async ({
+    sourceIndex,
+    limit,
+  }: {
+    sourceIndex: IndexEntry[];
+    limit: number;
+  }): Promise<LexicalMatch[]> => {
+    if (!aiConfig.apiBase.trim()) return [];
+    setIsEmbeddingSearchPending(true);
+    try {
+      return await rankComponentMatchesByEmbeddings(
+        sourceIndex,
+        trimmedQuery,
+        {
+          apiBase: aiConfig.apiBase,
+          apiKey: aiConfig.apiKey,
+        },
+        { limit },
+      );
+    } catch {
+      return [];
+    } finally {
+      setIsEmbeddingSearchPending(false);
+    }
+  };
+
+  const startRerank = async (
     matches: LexicalMatch[],
-    { scoreAllCandidates }: { scoreAllCandidates: boolean },
+    {
+      scoreAllCandidates,
+      useEmbeddings,
+      limit,
+    }: {
+      scoreAllCandidates: boolean;
+      useEmbeddings: boolean;
+      limit: number;
+    },
   ) => {
     if (!trimmedQuery || matches.length === 0 || !isConfigured) return;
 
-    const candidates = matches
+    const embeddingMatches =
+      useEmbeddings && aiConfig.apiBase.trim()
+        ? await buildEmbeddingMatches({ sourceIndex: index, limit })
+        : [];
+    const lexicalMatchesToKeep = useEmbeddings ? matches.slice(0, 60) : matches;
+    const rerankMatches = mergeUniqueMatches(
+      lexicalMatchesToKeep,
+      embeddingMatches,
+      matches,
+      limit,
+    );
+
+    const candidates = rerankMatches
       .map((match) =>
         componentReferenceToCandidate(match.reference, match.source),
       )
@@ -223,17 +293,25 @@ export function useComponentSearchV2State(
 
     if (candidates.length === 0) return;
 
-    setRerankBaseMatches(matches);
+    setRerankBaseMatches(rerankMatches);
     setRerankedFor(trimmedQuery);
     mutate({ query: trimmedQuery, candidates, scoreAllCandidates });
   };
 
   const rerank = () => {
-    startRerank(aiCandidateMatches, { scoreAllCandidates: true });
+    void startRerank(aiCandidateMatches, {
+      scoreAllCandidates: true,
+      useEmbeddings: true,
+      limit: aiCandidateMatches.length,
+    });
   };
 
   const deepRerank = () => {
-    startRerank(deepAiCandidateMatches, { scoreAllCandidates: false });
+    void startRerank(deepAiCandidateMatches, {
+      scoreAllCandidates: false,
+      useEmbeddings: true,
+      limit: deepAiCandidateMatches.length,
+    });
   };
 
   const rerankScoreByDigest = buildRerankScoreByDigest(
@@ -262,7 +340,7 @@ export function useComponentSearchV2State(
       trimmedQuery.length > 0 &&
       deepAiCandidateMatches.length > 0 &&
       isConfigured,
-    isReranking,
+    isReranking: isReranking || isEmbeddingSearchPending,
     rerank,
     deepRerank,
   };
diff --git a/src/services/componentSearchEmbeddings.test.ts b/src/services/componentSearchEmbeddings.test.ts
new file mode 100644
index 000000000..303bd7686
--- /dev/null
+++ b/src/services/componentSearchEmbeddings.test.ts
@@ -0,0 +1,168 @@
+import "fake-indexeddb/auto";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  buildSearchIndex,
+  type ComponentSearchSource,
+  type SourcedReference,
+} from "@/services/componentSearchIndex";
+import type { ComponentReference } from "@/utils/componentSpec";
+import { isRecord } from "@/utils/typeGuards";
+
+import {
+  buildComponentEmbeddingText,
+  clearComponentSearchEmbeddingCache,
+  rankComponentMatchesByEmbeddings,
+} from "./componentSearchEmbeddings";
+
+const STANDARD: ComponentSearchSource = {
+  kind: "standard",
+  label: "Standard",
+  id: "standard",
+};
+
+const OPTIONS = {
+  apiBase: "https://api.example.com/v1",
+  apiKey: "sk-test",
+};
+
+function makeSourced(reference: ComponentReference): SourcedReference {
+  return { reference, source: STANDARD };
+}
+
+function embeddingForText(text: string): number[] {
+  if (/spreadsheet|csv|tabular|dataframe/i.test(text)) return [1, 0, 0];
+  if (/train|model|classifier/i.test(text)) return [0, 1, 0];
+  return [0, 0, 1];
+}
+
+function readFetchInput(init: RequestInit | undefined): string[] {
+  if (!init || typeof init.body !== "string") {
+    throw new Error("Expected fetch body");
+  }
+  const body: unknown = JSON.parse(init.body);
+  if (!isRecord(body) || !Array.isArray(body.input)) {
+    throw new Error("Expected embeddings input array");
+  }
+  return body.input.filter(
+    (value): value is string => typeof value === "string",
+  );
+}
+
+describe("component search embeddings", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn(
+      async (_url: string | URL | Request, init?: RequestInit) => {
+        const input = readFetchInput(init);
+        return new Response(
+          JSON.stringify({
+            data: input.map((text, index) => ({
+              index,
+              embedding: embeddingForText(text),
+            })),
+          }),
+          { status: 200, statusText: "OK" },
+        );
+      },
+    );
+  });
+
+  afterEach(async () => {
+    await clearComponentSearchEmbeddingCache();
+    vi.restoreAllMocks();
+  });
+
+  it("builds embedding text from component metadata", () => {
+    const index = buildSearchIndex([
+      makeSourced({
+        digest: "csv",
+        published_by: "publisher@example.com",
+        spec: {
+          name: "load_csv_file",
+          description: "Read a CSV file.",
+          inputs: [{ name: "path", type: "String", description: "File path" }],
+          outputs: [{ name: "table", type: "Dataset" }],
+          implementation: { container: { image: "x" } },
+        },
+      }),
+    ]);
+
+    const text = buildComponentEmbeddingText(index[0]);
+
+    expect(text).toContain("load_csv_file");
+    expect(text).toContain("Read a CSV file");
+    expect(text).toContain("File path");
+    expect(text).toContain("Dataset");
+    expect(text).toContain("Standard");
+    expect(text).toContain("publisher@example.com");
+  });
+
+  it("ranks components by cosine similarity", async () => {
+    const index = buildSearchIndex([
+      makeSourced({
+        digest: "train",
+        spec: {
+          name: "train_model",
+          description: "Train a classifier.",
+          inputs: [],
+          outputs: [],
+          implementation: { container: { image: "x" } },
+        },
+      }),
+      makeSourced({
+        digest: "csv",
+        spec: {
+          name: "load_csv_file",
+          description: "Read a CSV file into a tabular dataframe.",
+          inputs: [],
+          outputs: [],
+          implementation: { container: { image: "x" } },
+        },
+      }),
+    ]);
+
+    const results = await rankComponentMatchesByEmbeddings(
+      index,
+      "open a spreadsheet",
+      OPTIONS,
+      { limit: 2 },
+    );
+
+    expect(results[0]?.digest).toBe("csv");
+  });
+
+  it("caches query and component embeddings in IndexedDB", async () => {
+    const index = buildSearchIndex([
+      makeSourced({
+        digest: "csv",
+        spec: {
+          name: "load_csv_file",
+          description: "Read a CSV file into a tabular dataframe.",
+          inputs: [],
+          outputs: [],
+          implementation: { container: { image: "x" } },
+        },
+      }),
+    ]);
+
+    await rankComponentMatchesByEmbeddings(
+      index,
+      "open a spreadsheet",
+      OPTIONS,
+      {
+        limit: 1,
+      },
+    );
+    await rankComponentMatchesByEmbeddings(
+      index,
+      "open a spreadsheet",
+      OPTIONS,
+      {
+        limit: 1,
+      },
+    );
+
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/services/componentSearchEmbeddings.ts b/src/services/componentSearchEmbeddings.ts
new file mode 100644
index 000000000..3e0b5209c
--- /dev/null
+++ b/src/services/componentSearchEmbeddings.ts
@@ -0,0 +1,257 @@
+import { Dexie, type EntityTable } from "dexie";
+
+import {
+  type IndexEntry,
+  indexEntryToLexicalMatch,
+  type LexicalMatch,
+} from "@/services/componentSearchIndex";
+import { isRecord } from "@/utils/typeGuards";
+
+const COMPONENT_SEARCH_EMBEDDING_MODEL = "text-embedding-3-small";
+const DB_NAME = "tangle_component_search_embeddings";
+const CACHE_SCHEMA_VERSION = 1;
+
+interface ComponentSearchEmbeddingCacheEntry {
+  cacheKey: string;
+  embeddingModel: string;
+  textHash: string;
+  embedding: number[];
+  updatedAt: number;
+}
+
+const componentSearchEmbeddingDb = new Dexie(DB_NAME) as Dexie & {
+  embeddings: EntityTable<ComponentSearchEmbeddingCacheEntry, "cacheKey">;
+};
+
+componentSearchEmbeddingDb.version(1).stores({
+  embeddings: "cacheKey, embeddingModel, textHash",
+});
+
+interface EmbeddingOptions {
+  apiBase: string;
+  apiKey: string;
+  signal?: AbortSignal;
+}
+
+interface RankOptions {
+  limit: number;
+}
+
+function hashText(text: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+function cacheKey(text: string): string {
+  return `${CACHE_SCHEMA_VERSION}:${COMPONENT_SEARCH_EMBEDDING_MODEL}:${hashText(text)}`;
+}
+
+function stringifyEmbeddingField(value: unknown): string {
+  if (typeof value === "string") return value.trim();
+  if (value === null || value === undefined) return "";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+function isNumberArray(value: unknown): value is number[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "number")
+  );
+}
+
+function readEmbeddingResponse(
+  payload: unknown,
+  expectedCount: number,
+): number[][] {
+  if (!isRecord(payload) || !Array.isArray(payload.data)) return [];
+
+  const rows = payload.data
+    .map((row, fallbackIndex) => {
+      if (!isRecord(row) || !isNumberArray(row.embedding)) return null;
+      const index = typeof row.index === "number" ? row.index : fallbackIndex;
+      return { index, embedding: row.embedding };
+    })
+    .filter(
+      (row): row is { index: number; embedding: number[] } => row !== null,
+    )
+    .sort((a, b) => a.index - b.index);
+
+  if (rows.length !== expectedCount) return [];
+  return rows.map((row) => row.embedding);
+}
+
+async function fetchEmbeddings(
+  texts: string[],
+  options: EmbeddingOptions,
+): Promise<number[][]> {
+  const base = options.apiBase.trim().replace(/\/+$/, "");
+  if (!base) return [];
+
+  const response = await fetch(`${base}/embeddings`, {
+    method: "POST",
+    signal: options.signal,
+    headers: {
+      "content-type": "application/json",
+      ...(options.apiKey.trim()
+        ? { authorization: `Bearer ${options.apiKey.trim()}` }
+        : {}),
+    },
+    body: JSON.stringify({
+      model: COMPONENT_SEARCH_EMBEDDING_MODEL,
+      input: texts,
+    }),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Embeddings API returned ${response.status}: ${detail.slice(0, 200) || response.statusText}`,
+    );
+  }
+
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error("Embeddings API returned a non-JSON response");
+  }
+
+  const embeddings = readEmbeddingResponse(payload, texts.length);
+  if (embeddings.length === 0) {
+    throw new Error("Embeddings API returned no usable embeddings");
+  }
+  return embeddings;
+}
+
+async function embedTextsWithCache(
+  texts: string[],
+  options: EmbeddingOptions,
+): Promise<Map<string, number[]>> {
+  const uniqueTexts = [
+    ...new Set(texts.map((text) => text.trim()).filter(Boolean)),
+  ];
+  const keys = uniqueTexts.map(cacheKey);
+  const cachedRows = await componentSearchEmbeddingDb.embeddings.bulkGet(keys);
+
+  const result = new Map<string, number[]>();
+  const missingTexts: string[] = [];
+  for (let i = 0; i < uniqueTexts.length; i++) {
+    const cached = cachedRows[i];
+    if (
+      cached &&
+      cached.embeddingModel === COMPONENT_SEARCH_EMBEDDING_MODEL &&
+      cached.textHash === hashText(uniqueTexts[i])
+    ) {
+      result.set(uniqueTexts[i], cached.embedding);
+    } else {
+      missingTexts.push(uniqueTexts[i]);
+    }
+  }
+
+  if (missingTexts.length === 0) return result;
+
+  const embeddings = await fetchEmbeddings(missingTexts, options);
+  const now = Date.now();
+  await componentSearchEmbeddingDb.embeddings.bulkPut(
+    missingTexts.map((text, index) => ({
+      cacheKey: cacheKey(text),
+      embeddingModel: COMPONENT_SEARCH_EMBEDDING_MODEL,
+      textHash: hashText(text),
+      embedding: embeddings[index],
+      updatedAt: now,
+    })),
+  );
+  for (let i = 0; i < missingTexts.length; i++) {
+    result.set(missingTexts[i], embeddings[i]);
+  }
+
+  return result;
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  return denominator === 0 ? 0 : dot / denominator;
+}
+
+export function buildComponentEmbeddingText(entry: IndexEntry): string {
+  const spec = entry.reference.spec;
+  const ioParts = [...(spec?.inputs ?? []), ...(spec?.outputs ?? [])].flatMap(
+    (ioSpec) => [
+      ioSpec.name,
+      ioSpec.description,
+      stringifyEmbeddingField(ioSpec.type),
+    ],
+  );
+
+  return [
+    entry.name,
+    spec?.description,
+    ...ioParts,
+    entry.source.label,
+    entry.reference.published_by,
+  ]
+    .filter(
+      (part): part is string =>
+        typeof part === "string" && part.trim().length > 0,
+    )
+    .join("\n");
+}
+
+export async function rankComponentMatchesByEmbeddings(
+  index: IndexEntry[],
+  query: string,
+  options: EmbeddingOptions,
+  { limit }: RankOptions,
+): Promise<LexicalMatch[]> {
+  const trimmedQuery = query.trim();
+  if (trimmedQuery.length === 0 || index.length === 0 || limit <= 0) return [];
+
+  const textByDigest = new Map<string, string>();
+  const texts = [trimmedQuery];
+  for (const entry of index) {
+    const text = buildComponentEmbeddingText(entry);
+    if (!text) continue;
+    textByDigest.set(entry.digest, text);
+    texts.push(text);
+  }
+
+  const embeddings = await embedTextsWithCache(texts, options);
+  const queryEmbedding = embeddings.get(trimmedQuery);
+  if (!queryEmbedding) return [];
+
+  return index
+    .map((entry) => {
+      const text = textByDigest.get(entry.digest);
+      const embedding = text ? embeddings.get(text) : undefined;
+      return {
+        entry,
+        score: embedding ? cosineSimilarity(queryEmbedding, embedding) : 0,
+      };
+    })
+    .filter((item) => item.score > 0)
+    .sort(
+      (a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name),
+    )
+    .slice(0, limit)
+    .map((item) => indexEntryToLexicalMatch(item.entry));
+}
+
+export async function clearComponentSearchEmbeddingCache(): Promise<void> {
+  await componentSearchEmbeddingDb.embeddings.clear();
+}