Skip to content

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

feat(web): add semantic search to the UI (#2960)

Mohamed Bassem2f740d00d164
diff --git a/apps/web/app/dashboard/search/page.tsx b/apps/web/app/dashboard/search/page.tsx
index 03dbb196..5ad339ca 100644
--- a/apps/web/app/dashboard/search/page.tsx
+++ b/apps/web/app/dashboard/search/page.tsx
@@ -8,7 +8,7 @@ import { useInSearchPageStore } from "@/lib/store/useInSearchPageStore";
import { useSortOrderStore } from "@/lib/store/useSortOrderStore";
function SearchComp() {
- const { data, hasNextPage, fetchNextPage, isFetchingNextPage } =
+ const { data, error, hasNextPage, fetchNextPage, isFetchingNextPage } =
useBookmarkSearch();
const { setInSearchPage } = useInSearchPageStore();
@@ -18,13 +18,17 @@ function SearchComp() {
useEffect(() => {
// also see related cleanup code in SortOrderToggle.tsx
setSortOrder("relevance");
- }, []);
+ }, [setSortOrder]);
useEffect(() => {
setInSearchPage(true);
return () => setInSearchPage(false);
}, [setInSearchPage]);
+ if (error) {
+ throw error;
+ }
+
return (
<div className="flex flex-col gap-3">
{data ? (
diff --git a/apps/web/components/dashboard/SortOrderToggle.tsx b/apps/web/components/dashboard/SortOrderToggle.tsx
index a5a10541..e417175a 100644
--- a/apps/web/components/dashboard/SortOrderToggle.tsx
+++ b/apps/web/components/dashboard/SortOrderToggle.tsx
@@ -8,6 +8,7 @@ import {
DropdownMenuItem,
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
+import { useBookmarkSearchState } from "@/lib/hooks/bookmark-search";
import { useTranslation } from "@/lib/i18n/client";
import { useInSearchPageStore } from "@/lib/store/useInSearchPageStore";
import { useSortOrderStore } from "@/lib/store/useSortOrderStore";
@@ -15,7 +16,8 @@ import { Check, ListFilter, SortAsc, SortDesc } from "lucide-react";
export default function SortOrderToggle() {
const { t } = useTranslation();
- const isInSearchPage = useInSearchPageStore();
+ const isInSearchPage = useInSearchPageStore((state) => state.inSearchPage);
+ const { effectiveSearchMode } = useBookmarkSearchState();
const { sortOrder: currentSort, setSortOrder } = useSortOrderStore();
@@ -26,7 +28,11 @@ export default function SortOrderToggle() {
// reset to default sort order
setSortOrder("desc");
}
- }, [isInSearchPage, currentSort]);
+ }, [isInSearchPage, currentSort, setSortOrder]);
+
+ if (isInSearchPage && effectiveSearchMode !== "fts") {
+ return null;
+ }
return (
<DropdownMenu>
diff --git a/apps/web/components/dashboard/search/SearchInput.tsx b/apps/web/components/dashboard/search/SearchInput.tsx
index 034b3bf7..a09e635f 100644
--- a/apps/web/components/dashboard/search/SearchInput.tsx
+++ b/apps/web/components/dashboard/search/SearchInput.tsx
@@ -4,6 +4,7 @@ import React, {
useCallback,
useEffect,
useImperativeHandle,
+ useMemo,
useRef,
useState,
} from "react";
@@ -21,16 +22,25 @@ import {
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover";
+import { useClientConfig } from "@/lib/clientConfig";
import { useDoBookmarkSearch } from "@/lib/hooks/bookmark-search";
import { useTranslation } from "@/lib/i18n/client";
import { cn } from "@/lib/utils";
import { useSearchHistory } from "@karakeep/shared-react/hooks/search-history";
+import { parseSearchQuery } from "@karakeep/shared/searchQueryParser";
import { EditListModal } from "../lists/EditListModal";
import QueryExplainerTooltip from "./QueryExplainerTooltip";
+import { SearchModeSelector } from "./SearchModeSelector";
import { useSearchAutocomplete } from "./useSearchAutocomplete";
+const SEARCH_PLACEHOLDERS = {
+ fts: "search.keyword_placeholder",
+ hybrid: "search.hybrid_placeholder",
+ semantic: "search.semantic_placeholder",
+} as const;
+
function useFocusSearchOnKeyPress(
inputRef: React.RefObject<HTMLInputElement | null>,
value: string,
@@ -69,11 +79,13 @@ const SearchInput = React.forwardRef<
React.HTMLAttributes<HTMLInputElement> & { loading?: boolean }
>(({ className, ...props }, ref) => {
const { t } = useTranslation();
+ const { semanticSearchEnabled } = useClientConfig().search;
const {
debounceSearch,
searchQuery,
doSearch,
- parsedSearchQuery,
+ setSearchMode,
+ searchMode,
isInSearchPage,
} = useDoBookmarkSearch();
const { addTerm, history } = useSearchHistory({
@@ -168,6 +180,13 @@ const SearchInput = React.forwardRef<
setIsPopoverOpen(false);
}, [value, addTerm]);
+ // Parse what's currently in the input rather than the query that's being
+ // searched: the two diverge while typing, and when navigating away from the
+ // search page the input is cleared but the last search query is kept around.
+ const parsedValue = useMemo(() => parseSearchQuery(value), [value]);
+ const canSaveSearch =
+ parsedValue.result === "full" && parsedValue.text.length === 0;
+
return (
<div className={cn("relative flex-1", className)}>
<EditListModal
@@ -178,24 +197,34 @@ const SearchInput = React.forwardRef<
query: value,
}}
/>
- <Link
- href="https://docs.karakeep.app/Guides/search-query-language"
- target="_blank"
- className="-translate-1/2 absolute right-1.5 top-2 z-50 stroke-foreground px-0.5"
- >
- <QueryExplainerTooltip parsedSearchQuery={parsedSearchQuery} />
- </Link>
- {parsedSearchQuery.result === "full" &&
- parsedSearchQuery.text.length == 0 && (
+ <div className="absolute inset-y-0 right-1.5 z-50 flex items-center gap-1">
+ {canSaveSearch ? (
<Button
onClick={() => setNewNestedListModalOpen(true)}
size="none"
variant="secondary"
- className="absolute right-10 top-2 z-50 px-2 py-1 text-xs"
+ className="h-7 px-2 text-xs"
>
{t("actions.save")}
</Button>
- )}
+ ) : null}
+ <Link
+ href="https://docs.karakeep.app/Guides/search-query-language"
+ target="_blank"
+ className="flex size-7 shrink-0 items-center justify-center rounded-md stroke-foreground transition-colors hover:bg-background/80"
+ >
+ <QueryExplainerTooltip
+ parsedSearchQuery={parsedValue}
+ className="text-muted-foreground"
+ />
+ </Link>
+ {semanticSearchEnabled ? (
+ <SearchModeSelector
+ value={searchMode}
+ onValueChange={(mode) => setSearchMode(mode, value)}
+ />
+ ) : null}
+ </div>
<Command
shouldFilter={false}
className="relative rounded-md bg-transparent"
@@ -206,14 +235,20 @@ const SearchInput = React.forwardRef<
<div className="relative">
<CommandInput
ref={inputRef}
- placeholder={t("common.search")}
+ placeholder={t(SEARCH_PLACEHOLDERS[searchMode])}
value={value}
onValueChange={handleValueChange}
onCompositionStart={handleCompositionStart}
onCompositionEnd={handleCompositionEnd}
onFocus={handleFocus}
onBlur={handleBlur}
- className={cn("h-10", className)}
+ className={cn(
+ "h-10",
+ semanticSearchEnabled ? "pr-20 sm:pr-36" : "pr-10",
+ canSaveSearch &&
+ (semanticSearchEnabled ? "pr-32 sm:pr-48" : "pr-24"),
+ className,
+ )}
{...props}
/>
</div>
diff --git a/apps/web/components/dashboard/search/SearchModeSelector.tsx b/apps/web/components/dashboard/search/SearchModeSelector.tsx
new file mode 100644
index 00000000..9013efce
--- /dev/null
+++ b/apps/web/components/dashboard/search/SearchModeSelector.tsx
@@ -0,0 +1,126 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuLabel,
+ DropdownMenuRadioGroup,
+ DropdownMenuRadioItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { useTranslation } from "@/lib/i18n/client";
+import { cn } from "@/lib/utils";
+import { Blend, BrainCircuit, ChevronDown, TextSearch } from "lucide-react";
+
+import type { ZBookmarkSearchMode } from "@karakeep/shared/types/bookmarks";
+
+const SEARCH_MODES = [
+ {
+ value: "fts",
+ labelKey: "search.mode_keyword",
+ descriptionKey: "search.mode_keyword_description",
+ Icon: TextSearch,
+ },
+ {
+ value: "hybrid",
+ labelKey: "search.mode_hybrid",
+ descriptionKey: "search.mode_hybrid_description",
+ Icon: Blend,
+ experimental: true,
+ },
+ {
+ value: "semantic",
+ labelKey: "search.mode_semantic",
+ descriptionKey: "search.mode_semantic_description",
+ Icon: BrainCircuit,
+ experimental: true,
+ },
+] as const;
+
+export function SearchModeSelector({
+ value,
+ onValueChange,
+}: {
+ value: ZBookmarkSearchMode;
+ onValueChange: (value: ZBookmarkSearchMode) => void;
+}) {
+ const { t } = useTranslation();
+ const activeMode =
+ SEARCH_MODES.find((mode) => mode.value === value) ?? SEARCH_MODES[0];
+ const ActiveIcon = activeMode.Icon;
+
+ return (
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button
+ type="button"
+ variant="none"
+ size="none"
+ aria-label={t("search.mode_label")}
+ className={cn(
+ "group h-7 gap-1.5 rounded-md border px-2 text-xs shadow-sm transition-colors",
+ value === "fts"
+ ? "border-border/60 bg-background/75 text-muted-foreground hover:bg-background hover:text-foreground"
+ : "border-primary/20 bg-primary/10 text-primary hover:bg-primary/15",
+ )}
+ >
+ <ActiveIcon className="size-3.5" />
+ <span className="hidden sm:inline">{t(activeMode.labelKey)}</span>
+ <ChevronDown className="size-3 opacity-60 transition-transform group-data-[state=open]:rotate-180" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className="w-80 p-2">
+ <DropdownMenuLabel className="px-2 pb-2 pt-1">
+ <span className="block text-sm">{t("search.mode_label")}</span>
+ <span className="mt-0.5 block font-normal text-muted-foreground">
+ {t("search.mode_label_description")}
+ </span>
+ </DropdownMenuLabel>
+ <DropdownMenuSeparator />
+ <DropdownMenuRadioGroup
+ value={value}
+ onValueChange={(nextValue) => {
+ const mode = SEARCH_MODES.find(
+ (option) => option.value === nextValue,
+ );
+ if (mode) {
+ onValueChange(mode.value);
+ }
+ }}
+ >
+ {SEARCH_MODES.map((mode) => (
+ <DropdownMenuRadioItem
+ key={mode.value}
+ value={mode.value}
+ className="items-start rounded-md py-2.5 pl-8 pr-2"
+ >
+ <mode.Icon
+ className={cn(
+ "mr-2 mt-0.5 size-4",
+ value === mode.value
+ ? "text-primary"
+ : "text-muted-foreground",
+ )}
+ />
+ <span className="min-w-0 flex-1">
+ <span className="flex items-center gap-2 font-medium">
+ {t(mode.labelKey)}
+ {"experimental" in mode && mode.experimental ? (
+ <span className="rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
+ {t("common.experimental")}
+ </span>
+ ) : null}
+ </span>
+ <span className="mt-0.5 block text-xs leading-relaxed text-muted-foreground">
+ {t(mode.descriptionKey)}
+ </span>
+ </span>
+ </DropdownMenuRadioItem>
+ ))}
+ </DropdownMenuRadioGroup>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ );
+}
diff --git a/apps/web/lib/clientConfig.tsx b/apps/web/lib/clientConfig.tsx
index fb12b367..75b7f9bb 100644
--- a/apps/web/lib/clientConfig.tsx
+++ b/apps/web/lib/clientConfig.tsx
@@ -21,6 +21,9 @@ export const ClientConfigCtx = createContext<ClientConfig>({
chat: {
enabled: false,
},
+ search: {
+ semanticSearchEnabled: false,
+ },
stripe: {
isConfigured: false,
},
diff --git a/apps/web/lib/hooks/bookmark-search.ts b/apps/web/lib/hooks/bookmark-search.ts
index 4a079410..2dc4b1bc 100644
--- a/apps/web/lib/hooks/bookmark-search.ts
+++ b/apps/web/lib/hooks/bookmark-search.ts
@@ -1,39 +1,80 @@
-import { useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useClientConfig } from "@/lib/clientConfig";
import { useSortOrderStore } from "@/lib/store/useSortOrderStore";
import { keepPreviousData, useInfiniteQuery } from "@tanstack/react-query";
+import type { ZBookmarkSearchMode } from "@karakeep/shared/types/bookmarks";
import { useTRPC } from "@karakeep/shared-react/trpc";
import { parseSearchQuery } from "@karakeep/shared/searchQueryParser";
import { useInSearchPageStore } from "../store/useInSearchPageStore";
-function useSearchQuery() {
+const DEFAULT_SEARCH_MODE: ZBookmarkSearchMode = "fts";
+
+function parseSearchMode(value: string | null): ZBookmarkSearchMode {
+ if (value === "semantic" || value === "hybrid") {
+ return value;
+ }
+ return DEFAULT_SEARCH_MODE;
+}
+
+function buildSearchHref(query: string, mode: ZBookmarkSearchMode) {
+ const params = new URLSearchParams();
+ if (query) {
+ params.set("q", query);
+ }
+ if (mode !== DEFAULT_SEARCH_MODE) {
+ params.set("mode", mode);
+ }
+ const queryString = params.toString();
+ return `/dashboard/search${queryString ? `?${queryString}` : ""}`;
+}
+
+export function useBookmarkSearchState() {
+ const { semanticSearchEnabled } = useClientConfig().search;
const searchParams = useSearchParams();
const searchQuery = searchParams.get("q") ?? "";
+ const searchMode = parseSearchMode(searchParams.get("mode"));
const pathname = usePathname();
- const lastQuery = useRef(searchQuery);
+ const lastSearch = useRef({ searchQuery, searchMode });
- // Only update the effective search query when on the search page.
- // This prevents the query from resetting when intercepting routes
+ // Only update the effective search state when on the search page.
+ // This prevents the query or mode from resetting when intercepting routes
// change the URL (e.g., opening a bookmark preview dialog).
if (pathname.startsWith("/dashboard/search")) {
- lastQuery.current = searchQuery;
+ lastSearch.current = { searchQuery, searchMode };
}
- const effectiveQuery = lastQuery.current;
+ const effectiveSearch = lastSearch.current;
const parsed = useMemo(
- () => parseSearchQuery(effectiveQuery),
- [effectiveQuery],
+ () => parseSearchQuery(effectiveSearch.searchQuery),
+ [effectiveSearch.searchQuery],
);
- return { searchQuery: effectiveQuery, parsedSearchQuery: parsed };
+ const selectedSearchMode = semanticSearchEnabled
+ ? effectiveSearch.searchMode
+ : DEFAULT_SEARCH_MODE;
+
+ // A query with no text (e.g. one made up entirely of qualifiers like
+ // `is:fav`) has nothing to embed, so it can only be served by full-text
+ // search. Keep the selected mode around for the UI, but search with fts.
+ const hasQueryText = parsed.text.trim().length > 0;
+
+ return {
+ searchQuery: effectiveSearch.searchQuery,
+ searchMode: selectedSearchMode,
+ effectiveSearchMode: hasQueryText
+ ? selectedSearchMode
+ : DEFAULT_SEARCH_MODE,
+ parsedSearchQuery: parsed,
+ };
}
export function useDoBookmarkSearch() {
const router = useRouter();
- const { searchQuery, parsedSearchQuery } = useSearchQuery();
+ const { searchQuery, searchMode } = useBookmarkSearchState();
const isInSearchPage = useInSearchPageStore((val) => val.inSearchPage);
- const timeoutId = useRef<NodeJS.Timeout>(null);
+ const timeoutId = useRef<ReturnType<typeof setTimeout>>(null);
useEffect(() => {
return () => {
@@ -42,35 +83,62 @@ export function useDoBookmarkSearch() {
}
clearTimeout(timeoutId.current);
};
- }, [timeoutId]);
+ }, []);
- const doSearch = (val: string) => {
- timeoutId.current = null;
- router.replace(`/dashboard/search?q=${encodeURIComponent(val)}`);
- };
+ const navigateToSearch = useCallback(
+ (query: string, mode: ZBookmarkSearchMode) => {
+ router.replace(buildSearchHref(query, mode));
+ },
+ [router],
+ );
- const debounceSearch = (val: string) => {
- if (timeoutId.current) {
- clearTimeout(timeoutId.current);
- }
- timeoutId.current = setTimeout(() => {
- doSearch(val);
- }, 10);
- };
+ const doSearch = useCallback(
+ (val: string) => {
+ timeoutId.current = null;
+ navigateToSearch(val, searchMode);
+ },
+ [navigateToSearch, searchMode],
+ );
+
+ const debounceSearch = useCallback(
+ (val: string) => {
+ if (timeoutId.current) {
+ clearTimeout(timeoutId.current);
+ }
+ timeoutId.current = setTimeout(() => {
+ doSearch(val);
+ }, 10);
+ },
+ [doSearch],
+ );
+
+ const setSearchMode = useCallback(
+ (mode: ZBookmarkSearchMode, query = searchQuery) => {
+ if (timeoutId.current) {
+ clearTimeout(timeoutId.current);
+ timeoutId.current = null;
+ }
+ navigateToSearch(query, mode);
+ },
+ [navigateToSearch, searchQuery],
+ );
return {
doSearch,
debounceSearch,
+ setSearchMode,
searchQuery,
- parsedSearchQuery,
+ searchMode,
isInSearchPage,
};
}
export function useBookmarkSearch() {
const api = useTRPC();
- const { searchQuery } = useSearchQuery();
+ const { searchQuery, effectiveSearchMode } = useBookmarkSearchState();
const sortOrder = useSortOrderStore((state) => state.sortOrder);
+ const effectiveSortOrder =
+ effectiveSearchMode === "fts" ? sortOrder : ("relevance" as const);
const {
data,
@@ -80,12 +148,12 @@ export function useBookmarkSearch() {
hasNextPage,
fetchNextPage,
isFetchingNextPage,
- refetch,
} = useInfiniteQuery(
api.bookmarks.searchBookmarks.infiniteQueryOptions(
{
text: searchQuery,
- sortOrder,
+ searchMode: effectiveSearchMode,
+ sortOrder: effectiveSortOrder,
},
{
placeholderData: keepPreviousData,
@@ -96,14 +164,6 @@ export function useBookmarkSearch() {
),
);
- useEffect(() => {
- refetch();
- }, [refetch, sortOrder]);
-
- if (error) {
- throw error;
- }
-
return {
error,
data,
diff --git a/apps/web/lib/i18n/locales/en/translation.json b/apps/web/lib/i18n/locales/en/translation.json
index 89236b8c..0ac87235 100644
--- a/apps/web/lib/i18n/locales/en/translation.json
+++ b/apps/web/lib/i18n/locales/en/translation.json
@@ -963,7 +963,18 @@
"tags": "Tags",
"lists": "Lists",
"feeds": "Feeds",
- "no_suggestions": "No suggestions"
+ "no_suggestions": "No suggestions",
+ "mode_label": "Search mode",
+ "mode_label_description": "Choose how Karakeep finds matching bookmarks.",
+ "mode_keyword": "Keyword",
+ "mode_keyword_description": "Match exact words in titles, content, URLs, and notes. Almost instant.",
+ "mode_hybrid": "Hybrid",
+ "mode_hybrid_description": "Blend exact matches with related ideas for the best balance. Slower than keyword search.",
+ "mode_semantic": "Semantic",
+ "mode_semantic_description": "Find conceptually similar bookmarks, even without shared words. Slower than keyword search.",
+ "keyword_placeholder": "Search titles, text, URLs, and tags…",
+ "hybrid_placeholder": "Search by words or meaning…",
+ "semantic_placeholder": "Describe what you remember…"
},
"preview": {
"view_original": "View Original",
diff --git a/docs/docs/03-configuration/01-environment-variables.md b/docs/docs/03-configuration/01-environment-variables.md
index 9d8e18dc..d49a9156 100644
--- a/docs/docs/03-configuration/01-environment-variables.md
+++ b/docs/docs/03-configuration/01-environment-variables.md
@@ -103,6 +103,7 @@ Either `OPENAI_API_KEY` or `OLLAMA_BASE_URL` need to be set for automatic taggin
| OLLAMA_KEEP_ALIVE | No | Not set | Controls how long the model will stay loaded into memory following the request (examples: "5m" for 5 minutes, "-1m" to keep the model loaded indefinitely, "0" to unload the model instantly after processing is complete). |
| CHAT_ENABLED | No | false | Whether the experimental chat interface and chat backend endpoints are enabled. Set to `true` to show the chat UI and allow chat API requests. |
| CHAT_MODEL | No | INFERENCE_TEXT_MODEL | The model to use for the experimental chat interface. If `OLLAMA_BASE_URL` is set, chat uses Ollama's OpenAI-compatible `/v1` API with this model. Otherwise chat uses `OPENAI_BASE_URL` when set, or OpenAI's API by default. |
+| SEMANTIC_SEARCH_ENABLED | No | true | Enables the hybrid and semantic bookmark search modes. **Experimental.** `EMBEDDING_ENABLE_AUTO_INDEXING` must also be enabled, and the modes are only offered in the UI when an inference provider is configured as well. |
| INFERENCE_TEXT_MODEL | No | gpt-4.1-mini | The model to use for text inference. You'll need to change this to some other model if you're using ollama. |
| INFERENCE_IMAGE_MODEL | No | gpt-4o-mini | The model to use for image inference. You'll need to change this to some other model if you're using ollama and that model needs to support vision APIs (e.g. llava). |
| EMBEDDING_ENABLE_AUTO_INDEXING | No | false | Whether bookmark embedding generation and vector indexing are enabled. When disabled, bookmark tagging still runs directly without waiting for embeddings. |
diff --git a/packages/shared/config.ts b/packages/shared/config.ts
index 9bbcc2d5..3a6e9365 100644
--- a/packages/shared/config.ts
+++ b/packages/shared/config.ts
@@ -69,6 +69,7 @@ const allEnv = z.object({
OLLAMA_KEEP_ALIVE: z.string().optional(),
CHAT_ENABLED: stringBool("false"),
CHAT_MODEL: z.string().optional(),
+ SEMANTIC_SEARCH_ENABLED: stringBool("true"),
INFERENCE_JOB_TIMEOUT_SEC: z.coerce.number().default(30),
INFERENCE_FETCH_TIMEOUT_SEC: z.coerce.number().default(300),
INFERENCE_TEXT_MODEL: z.string().default("gpt-4.1-mini"),
@@ -337,6 +338,9 @@ const serverConfigSchema = allEnv.transform((val, ctx) => {
chat: {
enabled: val.CHAT_ENABLED,
},
+ experimentalFeatures: {
+ semanticSearch: val.SEMANTIC_SEARCH_ENABLED,
+ },
embedding: {
enableAutoIndexing: val.EMBEDDING_ENABLE_AUTO_INDEXING,
textModel: val.EMBEDDING_TEXT_MODEL,
@@ -552,6 +556,12 @@ export const clientConfig = {
chat: {
enabled: serverConfig.chat.enabled,
},
+ search: {
+ semanticSearchEnabled:
+ serverConfig.experimentalFeatures.semanticSearch &&
+ serverConfig.embedding.enableAutoIndexing &&
+ serverConfig.inference.isConfigured,
+ },
stripe: {
isConfigured: serverConfig.stripe.isConfigured,
},
diff --git a/packages/shared/types/bookmarks.ts b/packages/shared/types/bookmarks.ts
index 8626a9c4..215d49b0 100644
--- a/packages/shared/types/bookmarks.ts
+++ b/packages/shared/types/bookmarks.ts
@@ -308,6 +308,7 @@ export const zSearchBookmarksCursor = z.discriminatedUnion("ver", [
}),
]);
export const zBookmarkSearchMode = z.enum(["fts", "semantic", "hybrid"]);
+export type ZBookmarkSearchMode = z.infer<typeof zBookmarkSearchMode>;
export const zSearchBookmarksRequestSchema = z.object({
text: z.string(),
limit: z.number().max(MAX_NUM_BOOKMARKS_PER_PAGE).optional(),
diff --git a/packages/shared/types/config.ts b/packages/shared/types/config.ts
index f517f1b2..cb28229a 100644
--- a/packages/shared/types/config.ts
+++ b/packages/shared/types/config.ts
@@ -27,6 +27,9 @@ export const zClientConfigSchema = z.object({
chat: z.object({
enabled: z.boolean(),
}),
+ search: z.object({
+ semanticSearchEnabled: z.boolean(),
+ }),
legal: z.object({
termsOfServiceUrl: z.string().optional(),
privacyPolicyUrl: z.string().optional(),
diff --git a/packages/trpc/routers/bookmarks.search.test.ts b/packages/trpc/routers/bookmarks.search.test.ts
index 26e7bc37..16ba3ef2 100644
--- a/packages/trpc/routers/bookmarks.search.test.ts
+++ b/packages/trpc/routers/bookmarks.search.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { afterAll, beforeEach, describe, expect, test, vi } from "vitest";
import serverConfig from "@karakeep/shared/config";
import { BookmarkTypes } from "@karakeep/shared/types/bookmarks";
@@ -15,6 +15,9 @@ const searchMocks = vi.hoisted(() => ({
getRateLimitClient: vi.fn(),
checkRateLimit: vi.fn(),
}));
+const originalSemanticSearchFeature =
+ serverConfig.experimentalFeatures.semanticSearch;
+const originalEmbeddingAutoIndexing = serverConfig.embedding.enableAutoIndexing;
vi.mock("@karakeep/shared/inference", () => ({
InferenceClientFactory: {
@@ -49,6 +52,14 @@ beforeEach<CustomTestContext>(async (context) => {
search: searchMocks.vectorSearch,
});
searchMocks.getRateLimitClient.mockResolvedValue(null);
+ serverConfig.experimentalFeatures.semanticSearch = true;
+ serverConfig.embedding.enableAutoIndexing = true;
+});
+
+afterAll(() => {
+ serverConfig.experimentalFeatures.semanticSearch =
+ originalSemanticSearchFeature;
+ serverConfig.embedding.enableAutoIndexing = originalEmbeddingAutoIndexing;
});
function mockEmbeddingInfra() {
@@ -64,6 +75,23 @@ function mockEmbeddingInfra() {
}
describe("bookmark search modes", () => {
+ test<CustomTestContext>("rejects semantic modes when the experimental feature is disabled", async ({
+ apiCallers,
+ }) => {
+ serverConfig.experimentalFeatures.semanticSearch = false;
+
+ await expect(
+ apiCallers[0].bookmarks.searchBookmarks({
+ text: "query",
+ searchMode: "semantic",
+ }),
+ ).rejects.toMatchObject({
+ code: "BAD_REQUEST",
+ message: "Semantic search is not enabled",
+ });
+ expect(searchMocks.vectorSearch).not.toHaveBeenCalled();
+ });
+
test.each(["semantic", "hybrid"] as const)(
"rate limits %s search",
async (searchMode) => {
diff --git a/packages/trpc/routers/bookmarks.ts b/packages/trpc/routers/bookmarks.ts
index de965ee5..fc3f5dab 100644
--- a/packages/trpc/routers/bookmarks.ts
+++ b/packages/trpc/routers/bookmarks.ts
@@ -890,6 +890,17 @@ export const bookmarksAppRouter = router({
const sortOrder = input.sortOrder || "relevance";
const parsedQuery = parseSearchQuery(input.text);
+ if (
+ input.searchMode !== "fts" &&
+ (!serverConfig.experimentalFeatures.semanticSearch ||
+ !serverConfig.embedding.enableAutoIndexing)
+ ) {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message: "Semantic search is not enabled",
+ });
+ }
+
let filter: FilterQuery[];
if (parsedQuery.matcher) {
const bookmarkIds = await getBookmarkIdsFromMatcher(