A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search
feat: add semantic search (#2959)
Mohamed Bassem71ea4d9b42d3
diff --git a/apps/cli/src/commands/bookmarks.ts b/apps/cli/src/commands/bookmarks.tsindex 17f1dd5d..d2f9e254 100644--- a/apps/cli/src/commands/bookmarks.ts+++ b/apps/cli/src/commands/bookmarks.ts@@ -615,6 +615,17 @@ bookmarkCmd},"relevance",)+ .option(+ "--search-mode <mode>",+ "search mode (fts, semantic, or hybrid)",+ (val) => {+ if (val !== "fts" && val !== "semantic" && val !== "hybrid") {+ throw new Error("search-mode must be one of: fts, semantic, hybrid");+ }+ return val;+ },+ "fts",+ ).option("--include-content","include full bookmark content in results",@@ -629,6 +640,7 @@ bookmarkCmdtext: query,limit: opts.limit,sortOrder: opts.sortOrder as "relevance" | "asc" | "desc",+ searchMode: opts.searchMode as "fts" | "semantic" | "hybrid",includeContent: opts.includeContent,cursor: opts.cursor? JSON.parse(Buffer.from(opts.cursor, "base64").toString(), (k, v) =>diff --git a/apps/mcp/src/bookmarks.test.ts b/apps/mcp/src/bookmarks.test.tsindex dc3e45c7..e72aefc8 100644--- a/apps/mcp/src/bookmarks.test.ts+++ b/apps/mcp/src/bookmarks.test.ts@@ -23,6 +23,7 @@ import {deleteBookmarkHandler,getBookmarkContentHandler,getBookmarkListsHandler,+ searchBookmarksHandler,} from "./bookmarks";const textOf = (result: CallToolResult): string => {@@ -80,6 +81,35 @@ afterEach(() => {vi.clearAllMocks();});+describe("search-bookmarks", () => {+ it("forwards the selected search mode", async () => {+ mockClient.GET.mockResolvedValueOnce({+ data: { bookmarks: [sampleBookmark], nextCursor: null },+ error: undefined,+ });++ const result = await searchBookmarksHandler({+ query: "async concurrency",+ limit: 10,+ searchMode: "semantic",+ });++ expect(mockClient.GET).toHaveBeenCalledWith("/bookmarks/search", {+ params: {+ query: {+ q: "async concurrency",+ limit: 10,+ includeContent: false,+ cursor: undefined,+ sortOrder: undefined,+ searchMode: "semantic",+ },+ },+ });+ expect(textOf(result)).toContain("Rust async book");+ });+});+describe("get-bookmark-lists", () => {it("returns every list containing the bookmark", async () => {mockClient.GET.mockResolvedValueOnce({diff --git a/apps/mcp/src/bookmarks.ts b/apps/mcp/src/bookmarks.tsindex 51f94489..d464aecf 100644--- a/apps/mcp/src/bookmarks.ts+++ b/apps/mcp/src/bookmarks.ts@@ -5,12 +5,8 @@ import { karakeepClient, mcpServer, turndownService } from "./shared";import { compactBookmark, compactList, toMcpToolError } from "./utils";// Tools-mcpServer.tool(- "search-bookmarks",- `Search for bookmarks matching a specific a query.-`,- {- query: z.string().describe(`+export const searchBookmarksInputSchema = {+ query: z.string().describe(`By default, this will do a full-text search, but you can also use qualifiers to filter the results.You can search bookmarks using specific qualifiers. is:fav finds favorited bookmarks,is:archived searches archived bookmarks, is:tagged finds those with tags,@@ -29,50 +25,75 @@ is:archived and (list:reading or #work)### Combine text search with qualifiersmachine learning is:fav`),- limit: z- .number()- .optional()- .describe(`The number of results to return in a single query.`)- .default(10),- nextCursor: z- .string()- .optional()- .describe(- `The next cursor to use for pagination. The value for this is returned from a previous call to this tool.`,- ),- sortOrder: z- .enum(["asc", "desc", "relevance"])- .optional()- .describe(`Sort by relevance or creation date. Defaults to relevance.`),- },- async ({ query, limit, nextCursor, sortOrder }): Promise<CallToolResult> => {- const res = await karakeepClient.GET("/bookmarks/search", {- params: {- query: {- q: query,- limit: limit,- includeContent: false,- cursor: nextCursor,- sortOrder,- },+ limit: z+ .number()+ .optional()+ .describe(`The number of results to return in a single query.`)+ .default(10),+ nextCursor: z+ .string()+ .optional()+ .describe(+ `The next cursor to use for pagination. The value for this is returned from a previous call to this tool.`,+ ),+ sortOrder: z+ .enum(["asc", "desc", "relevance"])+ .optional()+ .describe(`Sort by relevance or creation date. Defaults to relevance.`),+ searchMode: z+ .enum(["fts", "semantic", "hybrid"])+ .optional()+ .describe(+ `Search strategy. 'fts' uses full-text search, 'semantic' uses embeddings, and 'hybrid' combines both. Semantic and hybrid modes only support relevance sorting. Defaults to 'fts'.`,+ )+ .default("fts"),+};++export type SearchBookmarksInput = z.infer<+ z.ZodObject<typeof searchBookmarksInputSchema>+>;++export async function searchBookmarksHandler({+ query,+ limit,+ nextCursor,+ sortOrder,+ searchMode,+}: SearchBookmarksInput): Promise<CallToolResult> {+ const res = await karakeepClient.GET("/bookmarks/search", {+ params: {+ query: {+ q: query,+ limit: limit,+ includeContent: false,+ cursor: nextCursor,+ sortOrder,+ searchMode,},- });- if (!res.data) {- return toMcpToolError(res.error);- }- return {- content: [- {- type: "text",- text: `+ },+ });+ if (!res.data) {+ return toMcpToolError(res.error);+ }+ return {+ content: [+ {+ type: "text",+ text: `${res.data.bookmarks.map((bm) => compactBookmark(bm)).join("\n\n")}Next cursor: ${res.data.nextCursor ? `'${res.data.nextCursor}'` : "no more pages"}`,- },- ],- };- },+ },+ ],+ };+}++mcpServer.tool(+ "search-bookmarks",+ `Search for bookmarks matching a specific query using full-text, semantic, or hybrid search.`,+ searchBookmarksInputSchema,+ searchBookmarksHandler,);mcpServer.tool(diff --git a/packages/api/routes/bookmarks.ts b/packages/api/routes/bookmarks.tsindex 990b0a74..19897113 100644--- a/packages/api/routes/bookmarks.ts+++ b/packages/api/routes/bookmarks.ts@@ -85,6 +85,8 @@ const app = new Hono()text: searchParams.q,cursor: searchParams.cursor,limit: searchParams.limit,+ sortOrder: searchParams.sortOrder,+ searchMode: searchParams.searchMode,includeContent: searchParams.includeContent,});return c.json(diff --git a/packages/api/utils/types.ts b/packages/api/utils/types.tsindex 6fe9b880..34b9b3b0 100644--- a/packages/api/utils/types.ts+++ b/packages/api/utils/types.ts@@ -1,6 +1,9 @@import { z } from "zod";-import { zSortOrder } from "@karakeep/shared/types/bookmarks";+import {+ zBookmarkSearchMode,+ zSortOrder,+} from "@karakeep/shared/types/bookmarks";export const zStringBool = z.string()@@ -23,5 +26,6 @@ export const zGetBookmarkQueryParamsSchema = zexport const zGetBookmarkSearchParamsSchema = z.object({sortOrder: zSortOrder.optional().default(zSortOrder.enum.relevance),+ searchMode: zBookmarkSearchMode.optional().default("fts"),}).extend(zIncludeContentSearchParamsSchema.shape);diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.jsonindex 387a50e0..1a118f4d 100644--- a/packages/open-api/karakeep-openapi-spec.json+++ b/packages/open-api/karakeep-openapi-spec.json@@ -1188,7 +1188,7 @@"/bookmarks/search": {"get": {"operationId": "searchBookmarks",- "description": "Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. Results default to relevance sorting.",+ "description": "Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.","summary": "Search bookmarks","tags": ["Bookmarks"@@ -1209,6 +1209,22 @@"name": "q","in": "query"},+ {+ "schema": {+ "type": "string",+ "enum": [+ "fts",+ "semantic",+ "hybrid"+ ],+ "default": "fts",+ "description": "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested."+ },+ "required": false,+ "description": "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested.",+ "name": "searchMode",+ "in": "query"+ },{"schema": {"type": "string",diff --git a/packages/open-api/lib/bookmarks.ts b/packages/open-api/lib/bookmarks.tsindex ce65a84e..2dfd6520 100644--- a/packages/open-api/lib/bookmarks.ts+++ b/packages/open-api/lib/bookmarks.ts@@ -9,6 +9,7 @@ import {zAssetTypesSchema,zBareBookmarkSchema,zBookmarkReadableContentFormatSchema,+ zBookmarkSearchMode,zManipulatedTagSchema,zNewBookmarkRequestSchema,zSortOrder,@@ -86,8 +87,8 @@ registry.registerPath({method: "get",path: "/bookmarks/search",description:- "Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. " +- "Results default to relevance sorting.",+ "Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. " ++ "Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.",summary: "Search bookmarks",tags: ["Bookmarks"],security: [{ [BearerAuth.name]: [] }],@@ -95,6 +96,12 @@ registry.registerPath({query: z.object({q: z.string().describe("The search query string."),+ searchMode: zBookmarkSearchMode+ .optional()+ .default("fts")+ .describe(+ "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested.",+ ),sortOrder: zSortOrder.optional().default(zSortOrder.enum.relevance)diff --git a/packages/sdk/src/karakeep-api.d.ts b/packages/sdk/src/karakeep-api.d.tsindex 6883c59e..89564cf2 100644--- a/packages/sdk/src/karakeep-api.d.ts+++ b/packages/sdk/src/karakeep-api.d.ts@@ -37,7 +37,7 @@ export interface paths {};/*** Search bookmarks- * @description Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. Results default to relevance sorting.+ * @description Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.*/get: operations["searchBookmarks"];put?: never;@@ -1219,6 +1219,8 @@ export interface operations {query: {/** @description The search query string. */q: string;+ /** @description Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested. */+ searchMode?: "fts" | "semantic" | "hybrid";/** @description Sort order for results. Defaults to 'relevance'. Use 'asc' or 'desc' for date-based sorting. */sortOrder?: "asc" | "desc" | "relevance";/** @description Maximum number of items to return per page. */diff --git a/packages/shared-server/src/eventLogTypes.ts b/packages/shared-server/src/eventLogTypes.tsindex 21a15f5e..e8623159 100644--- a/packages/shared-server/src/eventLogTypes.ts+++ b/packages/shared-server/src/eventLogTypes.ts@@ -172,6 +172,8 @@ type EventLogInternal =| {["event.name"]: "search.query";"search.has_query"?: boolean;+ "search.mode"?: "fts" | "semantic" | "hybrid";+ "search.degraded"?: boolean;"search.results_count"?: number;}| { ["event.name"]: "bookmarks.queried" }diff --git a/packages/shared/types/bookmarks.ts b/packages/shared/types/bookmarks.tsindex b9ce5277..8626a9c4 100644--- a/packages/shared/types/bookmarks.ts+++ b/packages/shared/types/bookmarks.ts@@ -307,11 +307,13 @@ export const zSearchBookmarksCursor = z.discriminatedUnion("ver", [offset: z.number(),}),]);+export const zBookmarkSearchMode = z.enum(["fts", "semantic", "hybrid"]);export const zSearchBookmarksRequestSchema = z.object({text: z.string(),limit: z.number().max(MAX_NUM_BOOKMARKS_PER_PAGE).optional(),cursor: zSearchBookmarksCursor.nullish(),sortOrder: zSortOrder.optional().default("relevance"),+ searchMode: zBookmarkSearchMode.optional().default("fts"),includeContent: z.boolean().optional().default(false),});diff --git a/packages/trpc/lib/__tests__/searchRanking.test.ts b/packages/trpc/lib/__tests__/searchRanking.test.tsnew file mode 100644index 00000000..0ad48048--- /dev/null+++ b/packages/trpc/lib/__tests__/searchRanking.test.ts@@ -0,0 +1,43 @@+import { describe, expect, test } from "vitest";++import { reciprocalRankFusion } from "../searchRanking";++describe("reciprocalRankFusion", () => {+ test("rewards results returned by both search engines", () => {+ const results = reciprocalRankFusion([+ [{ id: "fts-only" }, { id: "both" }],+ [{ id: "semantic-only" }, { id: "both" }],+ ]);++ expect(results.map((result) => result.id)).toEqual([+ "both",+ "fts-only",+ "semantic-only",+ ]);+ });++ test("keeps source order when only one list contains a result", () => {+ const results = reciprocalRankFusion([+ [{ id: "first" }, { id: "second" }, { id: "third" }],+ [],+ ]);++ expect(results.map((result) => result.id)).toEqual([+ "first",+ "second",+ "third",+ ]);+ });++ test("counts duplicate ids only once per source", () => {+ const results = reciprocalRankFusion(+ [[{ id: "duplicate" }, { id: "duplicate" }], [{ id: "other" }]],+ 0,+ );++ expect(results).toEqual([+ { id: "duplicate", score: 1 },+ { id: "other", score: 1 },+ ]);+ });+});diff --git a/packages/trpc/lib/searchRanking.ts b/packages/trpc/lib/searchRanking.tsnew file mode 100644index 00000000..e75f53fd--- /dev/null+++ b/packages/trpc/lib/searchRanking.ts@@ -0,0 +1,47 @@+export interface RankedSearchHit {+ id: string;+ score: number;+}++/**+ * Merge ranked result lists using reciprocal-rank fusion (RRF).+ *+ * RRF deliberately ignores source scores because full-text and vector search+ * scores do not share a meaningful scale. A hit receives credit for its rank+ * in every source, so results returned by both sources naturally rise.+ */+export function reciprocalRankFusion(+ resultLists: readonly (readonly { id: string }[])[],+ rankConstant = 60,+): RankedSearchHit[] {+ const scores = new Map<string, { score: number; bestRank: number }>();++ for (const hits of resultLists) {+ const seen = new Set<string>();+ hits.forEach((hit, index) => {+ if (seen.has(hit.id)) {+ return;+ }+ seen.add(hit.id);++ const rank = index + 1;+ const current = scores.get(hit.id) ?? {+ score: 0,+ bestRank: Number.POSITIVE_INFINITY,+ };+ current.score += 1 / (rankConstant + rank);+ current.bestRank = Math.min(current.bestRank, rank);+ scores.set(hit.id, current);+ });+ }++ return [...scores.entries()]+ .map(([id, ranking]) => ({ id, ...ranking }))+ .sort(+ (a, b) =>+ b.score - a.score ||+ a.bestRank - b.bestRank ||+ a.id.localeCompare(b.id),+ )+ .map(({ id, score }) => ({ id, score }));+}diff --git a/packages/trpc/routers/bookmarks.search.test.ts b/packages/trpc/routers/bookmarks.search.test.tsnew file mode 100644index 00000000..26e7bc37--- /dev/null+++ b/packages/trpc/routers/bookmarks.search.test.ts@@ -0,0 +1,433 @@+import { beforeEach, describe, expect, test, vi } from "vitest";++import serverConfig from "@karakeep/shared/config";+import { BookmarkTypes } from "@karakeep/shared/types/bookmarks";++import type { CustomTestContext } from "../testUtils";+import { defaultBeforeEach } from "../testUtils";+import { createSemanticSearchRateLimitMiddleware } from "./bookmarks";++const searchMocks = vi.hoisted(() => ({+ search: vi.fn(),+ vectorSearch: vi.fn(),+ buildInferenceClient: vi.fn(),+ getVectorStoreClient: vi.fn(),+ getRateLimitClient: vi.fn(),+ checkRateLimit: vi.fn(),+}));++vi.mock("@karakeep/shared/inference", () => ({+ InferenceClientFactory: {+ build: searchMocks.buildInferenceClient,+ },+}));++vi.mock("@karakeep/shared/search", async (original) => ({+ ...(await original<typeof import("@karakeep/shared/search")>()),+ getSearchClient: vi.fn(async () => ({ search: searchMocks.search })),+}));++vi.mock("@karakeep/shared/vectorStore", async (original) => ({+ ...(await original<typeof import("@karakeep/shared/vectorStore")>()),+ getVectorStoreClient: searchMocks.getVectorStoreClient,+}));++vi.mock("@karakeep/shared/ratelimiting", async (original) => ({+ ...(await original<typeof import("@karakeep/shared/ratelimiting")>()),+ getRateLimitClient: searchMocks.getRateLimitClient,+}));++beforeEach<CustomTestContext>(async (context) => {+ await defaultBeforeEach(true)(context);+ searchMocks.search.mockReset();+ searchMocks.vectorSearch.mockReset();+ searchMocks.buildInferenceClient.mockReset();+ searchMocks.getVectorStoreClient.mockReset();+ searchMocks.getRateLimitClient.mockReset();+ searchMocks.checkRateLimit.mockReset();+ searchMocks.getVectorStoreClient.mockResolvedValue({+ search: searchMocks.vectorSearch,+ });+ searchMocks.getRateLimitClient.mockResolvedValue(null);+});++function mockEmbeddingInfra() {+ const generateEmbeddingFromText = vi.fn(async () => ({+ embeddings: [[0.1, 0.2]],+ promptTokens: 1,+ totalTokens: 1,+ }));+ searchMocks.buildInferenceClient.mockReturnValue({+ generateEmbeddingFromText,+ });+ return generateEmbeddingFromText;+}++describe("bookmark search modes", () => {+ test.each(["semantic", "hybrid"] as const)(+ "rate limits %s search",+ async (searchMode) => {+ const next = vi.fn().mockResolvedValue("ok");+ searchMocks.checkRateLimit.mockResolvedValue({ allowed: true });+ searchMocks.getRateLimitClient.mockResolvedValue({+ checkRateLimit: searchMocks.checkRateLimit,+ });+ const wasRateLimitingEnabled = serverConfig.rateLimiting.enabled;+ serverConfig.rateLimiting.enabled = true;++ try {+ const result = await createSemanticSearchRateLimitMiddleware<string>()({+ path: "bookmarks.searchBookmarks",+ ctx: {+ req: { ip: "127.0.0.1" },+ user: { id: "user-123" },+ },+ input: { searchMode },+ next,+ });++ expect(result).toBe("ok");+ expect(searchMocks.checkRateLimit).toHaveBeenCalledWith(+ {+ name: "bookmarks.searchBookmarks.semantic",+ windowMs: 60_000,+ maxRequests: 300,+ },+ "127.0.0.1:user:user-123:bookmarks.searchBookmarks",+ );+ } finally {+ serverConfig.rateLimiting.enabled = wasRateLimitingEnabled;+ }+ },+ );++ test("does not apply the semantic search rate limit to full-text search", async () => {+ const next = vi.fn().mockResolvedValue("ok");+ const wasRateLimitingEnabled = serverConfig.rateLimiting.enabled;+ serverConfig.rateLimiting.enabled = true;++ try {+ const result = await createSemanticSearchRateLimitMiddleware<string>()({+ path: "bookmarks.searchBookmarks",+ ctx: {+ req: { ip: "127.0.0.1" },+ user: { id: "user-123" },+ },+ input: { searchMode: "fts" },+ next,+ });++ expect(result).toBe("ok");+ expect(searchMocks.getRateLimitClient).not.toHaveBeenCalled();+ } finally {+ serverConfig.rateLimiting.enabled = wasRateLimitingEnabled;+ }+ });++ test<CustomTestContext>("defaults to full-text search", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "full text result",+ });+ searchMocks.search.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 1 }],+ totalHits: 1,+ processingTimeMs: 1,+ });++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "result",+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();+ });++ test<CustomTestContext>("fuses full-text and semantic rankings", async ({+ apiCallers,+ }) => {+ const [ftsOnly, shared, semanticOnly] = await Promise.all(+ ["full text", "shared", "semantic"].map((text) =>+ apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text,+ }),+ ),+ );+ searchMocks.search.mockResolvedValue({+ hits: [+ { id: ftsOnly.id, score: 1 },+ { id: shared.id, score: 0.5 },+ ],+ totalHits: 2,+ processingTimeMs: 1,+ });+ searchMocks.vectorSearch.mockResolvedValue({+ hits: [+ { id: semanticOnly.id, score: 0.95 },+ { id: shared.id, score: 0.9 },+ ],+ processingTimeMs: 1,+ });+ const generateEmbeddingFromText = mockEmbeddingInfra();++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "meaningful query",+ searchMode: "hybrid",+ });++ expect(result.bookmarks[0]?.id).toBe(shared.id);+ expect(new Set(result.bookmarks.slice(1).map((item) => item.id))).toEqual(+ new Set([ftsOnly.id, semanticOnly.id]),+ );+ expect(generateEmbeddingFromText).toHaveBeenCalledWith([+ "meaningful query",+ ]);+ expect(searchMocks.vectorSearch).toHaveBeenCalledWith(+ expect.objectContaining({+ vector: [0.1, 0.2],+ limit: 100,+ filter: [+ {+ type: "eq",+ field: "userId",+ value: expect.any(String),+ },+ ],+ }),+ );+ expect(searchMocks.search).toHaveBeenCalledWith(+ expect.objectContaining({ limit: 100 }),+ );+ });++ test<CustomTestContext>("falls back to full-text search when hybrid infrastructure is unavailable", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "fallback result",+ });+ searchMocks.buildInferenceClient.mockReturnValue(null);+ searchMocks.getVectorStoreClient.mockResolvedValue(null);+ searchMocks.search.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 1 }],+ totalHits: 1,+ processingTimeMs: 1,+ });++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "fallback",+ searchMode: "hybrid",+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();+ expect(searchMocks.search).toHaveBeenCalledWith(+ expect.objectContaining({ limit: 20, offset: 0 }),+ );+ });++ test<CustomTestContext>("falls back when the hybrid vector store fails to initialize", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "vector initialization fallback",+ });+ mockEmbeddingInfra();+ searchMocks.getVectorStoreClient.mockRejectedValue(+ new Error("vector store unavailable"),+ );+ searchMocks.search.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 1 }],+ totalHits: 1,+ processingTimeMs: 1,+ });++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "fallback",+ searchMode: "hybrid",+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.search).toHaveBeenCalledWith(+ expect.objectContaining({ limit: 20, offset: 0 }),+ );+ });++ test<CustomTestContext>("falls back to a correctly paginated full-text page when hybrid vector search fails", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "runtime fallback",+ });+ mockEmbeddingInfra();+ searchMocks.vectorSearch.mockRejectedValue(+ new Error("vector query unavailable"),+ );+ searchMocks.search.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 1 }],+ totalHits: 41,+ processingTimeMs: 1,+ });++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "fallback",+ searchMode: "hybrid",+ limit: 10,+ cursor: { ver: 1, offset: 40 },+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.search).toHaveBeenNthCalledWith(+ 1,+ expect.objectContaining({ limit: 100 }),+ );+ expect(searchMocks.search).toHaveBeenNthCalledWith(+ 2,+ expect.objectContaining({ limit: 10, offset: 40 }),+ );+ });++ test<CustomTestContext>("falls back when hybrid embedding generation fails", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "embedding fallback",+ });+ const generateEmbeddingFromText = mockEmbeddingInfra();+ generateEmbeddingFromText.mockRejectedValue(+ new Error("embedding provider unavailable"),+ );+ searchMocks.search.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 1 }],+ totalHits: 1,+ processingTimeMs: 1,+ });++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "fallback",+ searchMode: "hybrid",+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.search).toHaveBeenCalledTimes(2);+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();+ });++ test<CustomTestContext>("falls back to full-text search for filter-only hybrid queries", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "favourited bookmark",+ favourited: true,+ });+ mockEmbeddingInfra();+ searchMocks.search.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 1 }],+ totalHits: 1,+ processingTimeMs: 1,+ });++ // A filter-only query has nothing to embed, so hybrid degrades to full-text+ // search, which also means date sorting is allowed again.+ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "is:fav",+ searchMode: "hybrid",+ sortOrder: "desc",+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();+ });++ test<CustomTestContext>("rejects filter-only semantic queries", async ({+ apiCallers,+ }) => {+ mockEmbeddingInfra();++ await expect(+ apiCallers[0].bookmarks.searchBookmarks({+ text: "is:fav",+ searchMode: "semantic",+ }),+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();+ });++ test<CustomTestContext>("rejects semantic search when its infrastructure is unavailable", async ({+ apiCallers,+ }) => {+ searchMocks.buildInferenceClient.mockReturnValue(null);+ searchMocks.getVectorStoreClient.mockResolvedValue(null);++ await expect(+ apiCallers[0].bookmarks.searchBookmarks({+ text: "semantic query",+ searchMode: "semantic",+ }),+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });+ });++ test<CustomTestContext>("preserves semantic search runtime failures", async ({+ apiCallers,+ }) => {+ mockEmbeddingInfra();+ searchMocks.vectorSearch.mockRejectedValue(+ new Error("vector query unavailable"),+ );++ await expect(+ apiCallers[0].bookmarks.searchBookmarks({+ text: "semantic query",+ searchMode: "semantic",+ }),+ ).rejects.toThrow("vector query unavailable");+ expect(searchMocks.search).not.toHaveBeenCalled();+ });++ test<CustomTestContext>("rejects date sorting for semantic and hybrid search", async ({+ apiCallers,+ }) => {+ mockEmbeddingInfra();++ await expect(+ apiCallers[0].bookmarks.searchBookmarks({+ text: "semantic query",+ searchMode: "hybrid",+ sortOrder: "desc",+ }),+ ).rejects.toMatchObject({ code: "BAD_REQUEST" });+ });++ test<CustomTestContext>("drops semantic hits below the similarity threshold", async ({+ apiCallers,+ }) => {+ const bookmark = await apiCallers[0].bookmarks.createBookmark({+ type: BookmarkTypes.TEXT,+ text: "semantic result",+ });+ mockEmbeddingInfra();+ searchMocks.vectorSearch.mockResolvedValue({+ hits: [{ id: bookmark.id, score: 0.9 }],+ processingTimeMs: 1,+ });++ const result = await apiCallers[0].bookmarks.searchBookmarks({+ text: "meaningful query",+ searchMode: "semantic",+ });++ expect(result.bookmarks.map((item) => item.id)).toEqual([bookmark.id]);+ expect(searchMocks.vectorSearch).toHaveBeenCalledWith(+ expect.objectContaining({ rankingScoreThreshold: 0.6 }),+ );+ expect(searchMocks.search).not.toHaveBeenCalled();+ });+});diff --git a/packages/trpc/routers/bookmarks.ts b/packages/trpc/routers/bookmarks.tsindex e13a11a7..de965ee5 100644--- a/packages/trpc/routers/bookmarks.ts+++ b/packages/trpc/routers/bookmarks.ts@@ -31,6 +31,7 @@ import {import { SUPPORTED_BOOKMARK_ASSET_TYPES } from "@karakeep/shared/assetdb";import serverConfig from "@karakeep/shared/config";import { InferenceClientFactory } from "@karakeep/shared/inference";+import logger from "@karakeep/shared/logger";import { buildSummaryPrompt } from "@karakeep/shared/prompts.server";import { EnqueueOptions } from "@karakeep/shared/queueing";import { getRateLimitClient } from "@karakeep/shared/ratelimiting";@@ -40,6 +41,7 @@ import type { ZBookmarkContent } from "@karakeep/shared/types/bookmarks";import {BookmarkTypes,DEFAULT_NUM_BOOKMARKS_PER_PAGE,+ MAX_NUM_BOOKMARKS_PER_PAGE,zBookmarkSchema,zBookmarkReadableContentFormatSchema,zBookmarkReadableContentSchema,@@ -54,6 +56,8 @@ import {import type { ZBookmarkTags } from "@karakeep/shared/types/tags";import { ANCHOR_TEXT_MAX_LENGTH } from "@karakeep/shared/utils/reading-progress-dom";import { normalizeTagName } from "@karakeep/shared/utils/tag";+import { getVectorStoreClient } from "@karakeep/shared/vectorStore";+import type { VectorFilterQuery } from "@karakeep/shared/vectorStore";import { bookmarkCreationCounter } from "../stats";import type { AuthedContext } from "../index";@@ -66,11 +70,20 @@ import {} from "../index";import { RuleEngine } from "../lib/ruleEngine";import { getBookmarkIdsFromMatcher } from "../lib/search";+import { reciprocalRankFusion } from "../lib/searchRanking";import { Asset } from "../models/assets";import { BareBookmark, Bookmark } from "../models/bookmarks";import { WebhooksService } from "../models/webhooks.service";const bookmarksProcedure = createScopedAuthedProcedure("bookmarks");+const HYBRID_CANDIDATES_PER_SOURCE = MAX_NUM_BOOKMARKS_PER_PAGE;+/**+ * Vector search always returns as many hits as it's asked for, so without a+ * floor an unrelated query still fills a whole page with noise. Vector stores+ * normalize similarity into a 0..1 ranking score (for cosine distance that's+ * `(1 + cosine) / 2`), so this drops anything below ~0.2 cosine similarity.+ */+const SEMANTIC_SCORE_THRESHOLD = 0.6;export const ensureBookmarkOwnership = experimental_trpcMiddleware<{ctx: AuthedContext;@@ -126,6 +139,11 @@ async function attemptToDedupLink(ctx: AuthedContext, url: string) {}const BOOKMARKS_QUERIED_WINDOW_MS = 10 * 60 * 1000;+const semanticSearchRateLimitConfig = {+ name: "bookmarks.searchBookmarks.semantic",+ windowMs: 60 * 1000,+ maxRequests: 300,+} as const;function createBookmarksQueriedMiddleware<T>() {return async function bookmarksQueriedMiddleware(opts: {@@ -142,6 +160,28 @@ function createBookmarksQueriedMiddleware<T>() {};}+export function createSemanticSearchRateLimitMiddleware<T>() {+ const rateLimitMiddleware = createRateLimitMiddleware<T>(+ semanticSearchRateLimitConfig,+ );+ return function semanticSearchRateLimitMiddleware(opts: {+ path: string;+ ctx: {+ req: { ip: string | null };+ user: { id: string };+ };+ input: {+ searchMode: "fts" | "semantic" | "hybrid";+ };+ next: () => Promise<T>;+ }) {+ if (opts.input.searchMode === "fts") {+ return opts.next();+ }+ return rateLimitMiddleware(opts);+ };+}+function safeUrlHost(url: string | undefined): string | undefined {if (!url) {return undefined;@@ -834,6 +874,7 @@ export const bookmarksAppRouter = router({.use(createBookmarksQueriedMiddleware()).use(createEventLogMiddleware("search.query")).input(zSearchBookmarksRequestSchema)+ .use(createSemanticSearchRateLimitMiddleware()).output(z.object({bookmarks: z.array(zBookmarkSchema),@@ -843,18 +884,10 @@ export const bookmarksAppRouter = router({.query(async ({ input, ctx }) => {addLogFields<"search.query">({"search.has_query": input.text.length > 0,+ "search.mode": input.searchMode,});- if (!input.limit) {- input.limit = DEFAULT_NUM_BOOKMARKS_PER_PAGE;- }+ const limit = input.limit ?? DEFAULT_NUM_BOOKMARKS_PER_PAGE;const sortOrder = input.sortOrder || "relevance";- const client = await getSearchClient();- if (!client) {- throw new TRPCError({- code: "INTERNAL_SERVER_ERROR",- message: "Search functionality is not configured",- });- }const parsedQuery = parseSearchQuery(input.text);let filter: FilterQuery[];@@ -876,32 +909,168 @@ export const bookmarksAppRouter = router({*/const createdAtSortOrder = sortOrder === "relevance" ? "desc" : sortOrder;- const resp = await client.search({- query: parsedQuery.text,- filter,- sort: [{ field: "createdAt", order: createdAtSortOrder }],- limit: input.limit,- ...(input.cursor- ? {- offset: input.cursor.offset,- }- : {}),+ const offset = input.cursor?.offset ?? 0;+ let hits: { id: string; score: number }[];+ let hasMore: boolean;+ let resultCount: number;++ const fullTextSearch = async (limit: number, searchOffset?: number) => {+ const client = await getSearchClient();+ if (!client) {+ throw new TRPCError({+ code: "INTERNAL_SERVER_ERROR",+ message: "Search functionality is not configured",+ });+ }+ return client.search({+ query: parsedQuery.text,+ filter,+ sort: [{ field: "createdAt", order: createdAtSortOrder }],+ limit,+ ...(searchOffset !== undefined ? { offset: searchOffset } : {}),+ });+ };++ const fullTextPage = (+ resp: Awaited<ReturnType<typeof fullTextSearch>>,+ ) => ({+ hits: resp.hits.map((hit) => ({+ id: hit.id,+ score: hit.score ?? 0,+ })),+ hasMore: offset + resp.hits.length < resp.totalHits,+ resultCount: resp.totalHits,});+ const degradeToFullTextSearch = async (error?: unknown) => {+ addLogFields<"search.query">({ "search.degraded": true });+ if (error) {+ const message = error instanceof Error ? error.message : `${error}`;+ logger.warn(+ `Hybrid semantic search failed; falling back to full-text search: ${message}`,+ );+ }+ return fullTextPage(await fullTextSearch(limit, offset));+ };++ if (input.searchMode === "fts") {+ ({ hits, hasMore, resultCount } = fullTextPage(+ await fullTextSearch(limit, offset),+ ));+ } else {+ // A query made up entirely of qualifiers (e.g. `is:fav`) has nothing to+ // embed, so it can only be served by full-text search.+ const hasQueryText = parsedQuery.text.trim().length > 0;+ let semanticInfraError: unknown;+ const semanticClients = await (async () => ({+ inferenceClient: InferenceClientFactory.build(),+ vectorStoreClient: await getVectorStoreClient(),+ }))().catch((error: unknown) => {+ if (input.searchMode === "semantic") {+ throw error;+ }+ semanticInfraError = error;+ return null;+ });+ const inferenceClient = semanticClients?.inferenceClient;+ const vectorStoreClient = semanticClients?.vectorStoreClient;+ if (!hasQueryText || !inferenceClient || !vectorStoreClient) {+ if (input.searchMode === "semantic") {+ throw new TRPCError({+ code: "BAD_REQUEST",+ message: hasQueryText+ ? "Semantic search requires configured inference and vector store providers"+ : "Semantic search requires a non-empty text query",+ });+ }++ // Hybrid search remains useful when embeddings are unavailable or+ // when there's no text to embed. It degrades to plain full-text+ // search, which also means date sorting is supported again.+ ({ hits, hasMore, resultCount } =+ await degradeToFullTextSearch(semanticInfraError));+ } else {+ if (sortOrder !== "relevance") {+ throw new TRPCError({+ code: "BAD_REQUEST",+ message:+ "Semantic and hybrid search only support relevance sorting",+ });+ }++ const vectorFilter: VectorFilterQuery[] = filter.map((item) =>+ item.type === "eq"+ ? { type: "eq", field: item.field, value: item.value }+ : { type: "in", field: item.field, values: item.values },+ );++ const semanticSearch = async (limit: number) => {+ const embeddingResponse =+ await inferenceClient.generateEmbeddingFromText([+ parsedQuery.text,+ ]);+ const vector = embeddingResponse.embeddings[0];+ if (!vector) {+ throw new TRPCError({+ code: "INTERNAL_SERVER_ERROR",+ message: "Inference provider returned no query embedding",+ });+ }+ return vectorStoreClient.search({+ vector,+ filter: vectorFilter,+ limit,+ rankingScoreThreshold: SEMANTIC_SCORE_THRESHOLD,+ });+ };++ if (input.searchMode === "semantic") {+ const semanticLimit = offset + limit + 1;+ const semanticResp = await semanticSearch(semanticLimit);+ hits = semanticResp.hits.slice(offset, offset + limit);+ hasMore = semanticResp.hits.length > offset + limit;+ resultCount = semanticResp.hits.length;+ } else {+ // RRF can reorder earlier pages when its input window grows. Fuse a+ // fixed window so every cursor sees the same ranked candidate pool.+ const [ftsResult, semanticResult] = await Promise.allSettled([+ fullTextSearch(HYBRID_CANDIDATES_PER_SOURCE),+ semanticSearch(HYBRID_CANDIDATES_PER_SOURCE),+ ]);+ if (ftsResult.status === "rejected") {+ throw ftsResult.reason;+ }+ if (semanticResult.status === "rejected") {+ ({ hits, hasMore, resultCount } = await degradeToFullTextSearch(+ semanticResult.reason,+ ));+ } else {+ const fusedHits = reciprocalRankFusion([+ ftsResult.value.hits,+ semanticResult.value.hits,+ ]);+ hits = fusedHits.slice(offset, offset + limit);+ hasMore = fusedHits.length > offset + limit;+ resultCount = fusedHits.length;+ }+ }+ }+ }+addLogFields<"search.query">({- "search.results_count": resp.totalHits,+ "search.results_count": resultCount,});- if (resp.hits.length == 0) {+ if (hits.length == 0) {return { bookmarks: [], nextCursor: null };}- const idToRank = resp.hits.reduce<Record<string, number>>((acc, r) => {- acc[r.id] = r.score || 0;+ const idToRank = hits.reduce<Record<string, number>>((acc, r) => {+ acc[r.id] = r.score;return acc;}, {});const { bookmarks: results } = await Bookmark.loadMulti(ctx, {- ids: resp.hits.map((h) => h.id),+ ids: hits.map((h) => h.id),includeContent: input.includeContent,sortOrder: "desc", // Doesn't matter, we're sorting again afterwards and the list contain all data});@@ -920,13 +1089,12 @@ export const bookmarksAppRouter = router({return {bookmarks: results.map((b) => b.asZBookmark()),- nextCursor:- resp.hits.length + (input.cursor?.offset || 0) >= resp.totalHits- ? null- : {- ver: 1 as const,- offset: resp.hits.length + (input.cursor?.offset || 0),- },+ nextCursor: hasMore+ ? {+ ver: 1 as const,+ offset: offset + hits.length,+ }+ : null,};}),checkUrl: bookmarksProcedure