Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
// oxlint-disable ok/no-physical-direction-utility -- pre-rule backlog — physical margin/padding/inset utilities predate the rule; drain by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting this line. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-physical-direction-utility
import type { ConfigBinding } from '@inkeep/open-knowledge-core/config/bind-config-doc';
import { humanFormat } from '@inkeep/open-knowledge-core/config/errors';
import {
checkEmbeddingsBaseUrl,
DEFAULT_EMBEDDINGS_BASE_URL,
DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS,
DEFAULT_EMBEDDINGS_MAX_BATCH_CHARS,
DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE,
DEFAULT_EMBEDDINGS_MODEL,
MAX_EMBEDDINGS_DOC_TIMEOUT_MS,
MAX_EMBEDDINGS_MAX_BATCH_CHARS,
MAX_EMBEDDINGS_MAX_BATCH_SIZE,
MIN_EMBEDDINGS_DOC_TIMEOUT_MS,
MIN_EMBEDDINGS_MAX_BATCH_CHARS,
MIN_EMBEDDINGS_MAX_BATCH_SIZE,
} from '@inkeep/open-knowledge-core/config/schema';
import {
classifySemanticProviderError,
isSemanticSearchOffered,
type LocalOpEmbeddingsTestResponse,
type SemanticIndexStatus,
} from '@inkeep/open-knowledge-core/schemas/api';
import { Plural, Trans, useLingui } from '@lingui/react/macro';
import { ChevronRight } from 'lucide-react';
import { type ReactNode, useEffect, useRef, useState } from 'react';
import { toast } from 'sonner';
import { Button } from '@/components/ui/button';
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
import {
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
Dialog as DialogRoot,
DialogTitle,
} from '@/components/ui/dialog';
import { Field, FieldDescription, FieldLabel } from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import { Switch } from '@/components/ui/switch';
import { useSemanticSearchStatus } from '@/hooks/use-semantic-search-status';
import { okUserHomeLabel } from '@/lib/channel-cli-copy';
import { useConfigContext } from '@/lib/config-provider';
import {
type EmbeddingsKeyTransport,
httpEmbeddingsKeyTransport,
} from '@/lib/transports/embeddings-key-transport';
import { SettingsSectionHeader } from './SettingsSectionHeader';
const SETTLE_REFRESH_DELAYS_MS = [2500, 5000] as const;
const PERFORMANCE_CLEAR_HINT_ID = 'settings-search-performance-clear-hint';
export function SearchSection({ transport }: { transport?: EmbeddingsKeyTransport }) {
const { t } = useLingui();
const { projectLocalConfig, projectLocalSynced, projectLocalBinding } = useConfigContext();
const { status, refresh } = useSemanticSearchStatus();
const resolvedTransport = transport ?? httpEmbeddingsKeyTransport();
const [confirmOpen, setConfirmOpen] = useState(false);
const [baseUrlError, setBaseUrlError] = useState<string | null>(null);
const [baseUrlTouched, setBaseUrlTouched] = useState(false);
const settleTimersRef = useRef<Array<ReturnType<typeof setTimeout>>>([]);
useEffect(
() => () => {
for (const timer of settleTimersRef.current) clearTimeout(timer);
},
[],
);
const configuredBaseUrl =
projectLocalConfig?.search?.semantic?.baseUrl ?? DEFAULT_EMBEDDINGS_BASE_URL;
const configuredModel = projectLocalConfig?.search?.semantic?.model ?? DEFAULT_EMBEDDINGS_MODEL;
const configuredMaxBatchSize =
projectLocalConfig?.search?.semantic?.maxBatchSize ?? DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE;
const configuredMaxBatchChars =
projectLocalConfig?.search?.semantic?.maxBatchChars ?? DEFAULT_EMBEDDINGS_MAX_BATCH_CHARS;
const configuredDocTimeoutMs =
projectLocalConfig?.search?.semantic?.docTimeoutMs ?? DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS;
const [baseUrlDraft, setBaseUrlDraft] = useState(configuredBaseUrl);
const [modelDraft, setModelDraft] = useState(configuredModel);
const [pendingProvider, setPendingProvider] = useState<{
baseUrl: string;
model: string;
} | null>(null);
const [disclosureOverride, setDisclosureOverride] = useState<boolean | null>(null);
const [performanceDisclosureOverride, setPerformanceDisclosureOverride] = useState<
boolean | null
>(null);
const [testing, setTesting] = useState(false);
const [testResult, setTestResult] = useState<{
response: LocalOpEmbeddingsTestResponse | null;
} | null>(null);
const [prevConfigured, setPrevConfigured] = useState({
baseUrl: configuredBaseUrl,
model: configuredModel,
});
if (configuredBaseUrl !== prevConfigured.baseUrl || configuredModel !== prevConfigured.model) {
setPrevConfigured({ baseUrl: configuredBaseUrl, model: configuredModel });
setBaseUrlDraft(configuredBaseUrl);
setModelDraft(configuredModel);
setBaseUrlTouched(false);
setBaseUrlError(null);
setTestResult(null);
}
const enabled = projectLocalConfig?.search?.semantic?.enabled ?? false;
const bindingReady = projectLocalSynced && projectLocalBinding !== null;
const hasProviderOverride =
configuredBaseUrl !== DEFAULT_EMBEDDINGS_BASE_URL ||
configuredModel !== DEFAULT_EMBEDDINGS_MODEL;
const hasTransportOverride =
configuredMaxBatchSize !== DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE ||
configuredMaxBatchChars !== DEFAULT_EMBEDDINGS_MAX_BATCH_CHARS ||
configuredDocTimeoutMs !== DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS;
const disclosureOpen = disclosureOverride ?? hasProviderOverride;
const performanceDisclosureOpen = performanceDisclosureOverride ?? hasTransportOverride;
function scheduleSettleRefresh() {
for (const timer of settleTimersRef.current) clearTimeout(timer);
settleTimersRef.current = SETTLE_REFRESH_DELAYS_MS.map((delay) => setTimeout(refresh, delay));
}
function onTuningCommitted() {
refresh();
scheduleSettleRefresh();
}
function write(next: boolean): boolean {
if (projectLocalBinding === null) {
toast.error(t`Search settings not yet loaded — try again in a moment`);
return false;
}
const result = projectLocalBinding.patch({ search: { semantic: { enabled: next } } });
if (!result.ok) {
const detail = humanFormat(result.error);
toast.error(
next
? t`Failed to enable semantic search — ${detail}`
: t`Failed to disable semantic search — ${detail}`,
);
return false;
}
refresh();
scheduleSettleRefresh();
return true;
}
function normalizeBaseUrl(next: string): string {
return next.trim() || DEFAULT_EMBEDDINGS_BASE_URL;
}
function normalizeModel(next: string): string {
return next.trim() || DEFAULT_EMBEDDINGS_MODEL;
}
function writeProvider(next: { baseUrl: string; model: string }): boolean {
if (projectLocalBinding === null) {
toast.error(t`Search settings not yet loaded — try again in a moment`);
return false;
}
const result = projectLocalBinding.patch({
search: { semantic: { baseUrl: next.baseUrl, model: next.model } },
});
if (!result.ok) {
const detail = humanFormat(result.error);
toast.error(t`Failed to update the embeddings provider — ${detail}`);
return false;
}
setTestResult(null);
refresh();
scheduleSettleRefresh();
return true;
}
function requestProviderChange(next: { baseUrl: string; model: string }): void {
if (next.baseUrl === configuredBaseUrl && next.model === configuredModel) return;
setPendingProvider(next);
}
function onConfirmProviderChange(): void {
if (pendingProvider && writeProvider(pendingProvider)) setPendingProvider(null);
}
function onCancelProviderChange(): void {
setPendingProvider(null);
setBaseUrlDraft(configuredBaseUrl);
setModelDraft(configuredModel);
setBaseUrlError(null);
}
async function onTestConnection(): Promise<void> {
if (testing) return;
setTesting(true);
setTestResult(null);
let response: LocalOpEmbeddingsTestResponse | null = null;
try {
response = await resolvedTransport.testConnection();
} catch {
response = null;
}
setTesting(false);
setTestResult({ response });
}
function onToggleRequest(next: boolean) {
if (next) {
setConfirmOpen(true);
return;
}
write(false);
}
function onConfirm() {
if (write(true)) setConfirmOpen(false);
}
function baseUrlProblemMessage(value: string): string | null {
const trimmed = value.trim();
if (!trimmed) return null;
const problem = checkEmbeddingsBaseUrl(trimmed);
if (problem === null) return null;
return problem === 'invalid-url'
? t`Enter a valid URL (for example https://api.openai.com/v1).`
: t`Use an https:// URL — http:// is only allowed for loopback endpoints.`;
}
function onBaseUrlChange(value: string): void {
setBaseUrlDraft(value);
if (baseUrlTouched) setBaseUrlError(baseUrlProblemMessage(value));
}
function commitProviderEdits(): void {
setBaseUrlTouched(true);
const message = baseUrlProblemMessage(baseUrlDraft);
setBaseUrlError(message);
if (message !== null) return;
requestProviderChange({
baseUrl: normalizeBaseUrl(baseUrlDraft),
model: normalizeModel(modelDraft),
});
}
const keyPresent = status?.keyPresent ?? false;
const keyNotRequired = status?.keyNotRequired ?? false;
const keyHint = status?.keyHint ?? null;
const keySource = status?.keySource ?? null;
const total = status?.total ?? 0;
const endpointHost = hostOf(configuredBaseUrl) ?? configuredBaseUrl;
return (
<section
aria-labelledby="settings-search-title"
className="space-y-3"
data-testid="settings-search"
>
<SettingsSectionHeader
titleId="settings-search-title"
title={<Trans>Semantic search</Trans>}
scope="project-local"
>
<Trans>
Add meaning-based ranking to search so conceptually-related pages surface even when they
share no keywords.
</Trans>
</SettingsSectionHeader>
<div className="rounded-md border p-3">
<div className="flex items-center justify-between gap-3">
<div className="min-w-0">
<label htmlFor="settings-search-semantic-toggle" className="text-sm font-medium">
<Trans>Semantic search</Trans>
</label>
<p
id="settings-search-semantic-toggle-description"
className="text-muted-foreground text-1sm"
data-testid="settings-search-body"
>
{enabled ? (
<Trans>
On — your search queries and the text of matching pages are sent to your
embeddings provider (OpenAI by default) to compute embeddings.
</Trans>
) : (
<Trans>Off — search ranks by keyword only. No content leaves this computer.</Trans>
)}
</p>
</div>
<Switch
id="settings-search-semantic-toggle"
aria-describedby="settings-search-semantic-toggle-description"
checked={enabled}
disabled={!bindingReady}
onCheckedChange={onToggleRequest}
aria-label={enabled ? t`Disable semantic search` : t`Enable semantic search`}
data-testid="settings-search-semantic-toggle"
/>
</div>
{enabled ? <SemanticStatusPanel status={status} /> : null}
</div>
<EmbeddingsKeyField
transport={resolvedTransport}
refresh={refresh}
endpointHost={endpointHost}
keyPresent={keyPresent}
keyHint={keyHint}
keySource={keySource}
keyNotRequired={keyNotRequired}
loaded={status !== null}
/>
<Collapsible
open={disclosureOpen}
onOpenChange={setDisclosureOverride}
className="rounded-md border"
data-testid="settings-search-custom-endpoint"
>
<CollapsibleTrigger
className="group flex w-full items-center justify-between gap-2 px-3 py-2 text-sm font-medium hover:bg-muted/50"
data-testid="settings-search-custom-endpoint-trigger"
>
<Trans>Custom endpoint</Trans>
<ChevronRight
className="size-4 transition-transform group-data-[state=open]:rotate-90 motion-reduce:transition-none"
aria-hidden
/>
</CollapsibleTrigger>
<CollapsibleContent className="space-y-4 border-t px-3 py-3">
<p className="text-muted-foreground text-1sm">
<Trans>
Point semantic search at any OpenAI-compatible embeddings endpoint — a self-hosted
server or another provider. The API key above is for whichever endpoint you set here.
</Trans>
</p>
<div className="space-y-2">
<label htmlFor="settings-search-base-url" className="block text-sm font-medium">
<Trans>Endpoint</Trans>
</label>
<Input
id="settings-search-base-url"
value={baseUrlDraft}
onChange={(e) => onBaseUrlChange(e.currentTarget.value)}
onBlur={commitProviderEdits}
onKeyDown={(e) => {
if (e.key === 'Enter') {
e.preventDefault();
commitProviderEdits();
}
}}
placeholder={DEFAULT_EMBEDDINGS_BASE_URL}
disabled={!bindingReady}
spellCheck={false}
autoComplete="off"
aria-invalid={baseUrlError !== null}
aria-describedby="settings-search-base-url-message"
data-testid="settings-search-base-url"
className="h-8 font-mono text-sm"
/>
<p
id="settings-search-base-url-message"
aria-live="polite"
className={
baseUrlError ? 'text-1sm text-destructive' : 'text-muted-foreground text-1sm'
}
data-testid={
baseUrlError ? 'settings-search-base-url-error' : 'settings-search-base-url-help'
}
>
{baseUrlError ?? (
<Trans>Clear the field to reset back to the default OpenAI endpoint.</Trans>
)}
</p>
</div>
<div className="space-y-2">
<label htmlFor="settings-search-model" className="block text-sm font-medium">
<Trans>Model</Trans>
</label>
<Input
id="settings-search-model"
value={modelDraft}
onChange={(e) => setModelDraft(e.currentTarget.value)}
onBlur={commitProviderEdits}
onKeyDown={(e) => {
if (e.key === 'Enter') {
e.preventDefault();
commitProviderEdits();
}
}}
placeholder={DEFAULT_EMBEDDINGS_MODEL}
disabled={!bindingReady}
spellCheck={false}
autoComplete="off"
aria-describedby="settings-search-model-help"
data-testid="settings-search-model"
className="h-8 font-mono text-sm"
/>
<p
id="settings-search-model-help"
className="text-muted-foreground text-1sm"
data-testid="settings-search-model-help"
>
<Trans>
The model id your endpoint serves. Its vector size is detected automatically — clear
the field to go back to {DEFAULT_EMBEDDINGS_MODEL}.
</Trans>
</p>
</div>
<div className="space-y-2">
<Button
variant="outline"
onClick={() => void onTestConnection()}
disabled={testing || !bindingReady}
data-testid="settings-search-test-connection"
>
{testing ? <Trans>Testing</Trans> : <Trans>Test connection</Trans>}
</Button>
<TestConnectionResult
result={testResult}
testing={testing}
configuredBaseUrl={configuredBaseUrl}
configuredModel={configuredModel}
/>
</div>
</CollapsibleContent>
</Collapsible>
<Collapsible
open={performanceDisclosureOpen}
onOpenChange={setPerformanceDisclosureOverride}
className="rounded-md border"
data-testid="settings-search-performance"
data-field="search.semantic.maxBatchSize"
>
<CollapsibleTrigger
className="group flex w-full items-center justify-between gap-2 px-3 py-2 text-sm font-medium hover:bg-muted/50"
data-testid="settings-search-performance-trigger"
>
<Trans>Embedding request settings</Trans>
<ChevronRight
className="size-4 transition-transform group-data-[state=open]:rotate-90 motion-reduce:transition-none"
aria-hidden
/>
</CollapsibleTrigger>
<CollapsibleContent
className="flex flex-col gap-4 border-t px-3 py-3"
onFocusCapture={() => setPerformanceDisclosureOverride(true)}
>
<p className="text-muted-foreground text-1sm">
<Trans>
Adjust indexing request size and timeout for slow or memory-constrained embedding
servers. Most setups should keep the defaults.
</Trans>
</p>
<p id={PERFORMANCE_CLEAR_HINT_ID} className="text-muted-foreground text-1sm">
<Trans>Clear a field to restore its default value.</Trans>
</p>
<PerformanceTuningField
id="settings-search-max-batch-size"
label={<Trans>Maximum text chunks per indexing request</Trans>}
help={
<Trans>
Lower this to reduce memory use and work per request. Smaller batches send more
requests and may make indexing slower overall.
</Trans>
}
configKey="maxBatchSize"
configuredValue={configuredMaxBatchSize}
defaultValue={DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE}
binding={projectLocalBinding}
bindingReady={bindingReady}
onCommitted={onTuningCommitted}
/>
<PerformanceTuningField
id="settings-search-max-batch-chars"
label={<Trans>Character budget per indexing request</Trans>}
help={
<Trans>
Limits the combined text sent in each request. A single larger chunk is sent on its
own; documents are not split again.
</Trans>
}
configKey="maxBatchChars"
configuredValue={configuredMaxBatchChars}
defaultValue={DEFAULT_EMBEDDINGS_MAX_BATCH_CHARS}
binding={projectLocalBinding}
bindingReady={bindingReady}
onCommitted={onTuningCommitted}
/>
<PerformanceTuningField
id="settings-search-doc-timeout-seconds"
label={<Trans>Indexing request timeout (seconds)</Trans>}
help={
<Trans>
How long OpenKnowledge waits for each embedding request while indexing. Search
requests use a fixed 8-second timeout per attempt, unchanged by this setting.
</Trans>
}
configKey="docTimeoutMs"
configuredValue={configuredDocTimeoutMs}
defaultValue={DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS}
binding={projectLocalBinding}
bindingReady={bindingReady}
onCommitted={onTuningCommitted}
/>
</CollapsibleContent>
</Collapsible>
<EnableSemanticSearchConfirmDialog
open={confirmOpen}
onOpenChange={setConfirmOpen}
onConfirm={onConfirm}
/>
<ProviderChangeConfirmDialog
pending={pendingProvider}
pageCount={total}
onCancel={onCancelProviderChange}
onConfirm={onConfirmProviderChange}
/>
</section>
);
}
type PerformanceTuningKey = 'maxBatchSize' | 'maxBatchChars' | 'docTimeoutMs';
const PERFORMANCE_TUNING_BOUNDS: Record<
PerformanceTuningKey,
{ min: number; max: number; displayDivisor?: number }
> = {
maxBatchSize: { min: MIN_EMBEDDINGS_MAX_BATCH_SIZE, max: MAX_EMBEDDINGS_MAX_BATCH_SIZE },
maxBatchChars: { min: MIN_EMBEDDINGS_MAX_BATCH_CHARS, max: MAX_EMBEDDINGS_MAX_BATCH_CHARS },
docTimeoutMs: {
min: MIN_EMBEDDINGS_DOC_TIMEOUT_MS,
max: MAX_EMBEDDINGS_DOC_TIMEOUT_MS,
displayDivisor: 1000,
},
};
interface PerformanceTuningFieldProps {
id: string;
label: ReactNode;
help: ReactNode;
configKey: PerformanceTuningKey;
configuredValue: number;
defaultValue: number;
binding: ConfigBinding | null;
bindingReady: boolean;
onCommitted: () => void;
}
function PerformanceTuningField({
id,
label,
help,
configKey,
configuredValue,
defaultValue,
binding,
bindingReady,
onCommitted,
}: PerformanceTuningFieldProps) {
const { t, i18n } = useLingui();
const bounds = PERFORMANCE_TUNING_BOUNDS[configKey];
const displayDivisor = bounds.displayDivisor ?? 1;
const displayedConfiguredValue = configuredValue / displayDivisor;
const displayedDefaultValue = defaultValue / displayDivisor;
const displayedMinimum = bounds.min / displayDivisor;
const displayedMaximum = bounds.max / displayDivisor;
const [draft, setDraft] = useState(String(displayedConfiguredValue));
const [error, setError] = useState<string | null>(null);
const [savedValue, setSavedValue] = useState<number | null>(null);
const [previousConfiguredValue, setPreviousConfiguredValue] = useState(displayedConfiguredValue);
if (displayedConfiguredValue !== previousConfiguredValue) {
setPreviousConfiguredValue(displayedConfiguredValue);
setDraft(String(displayedConfiguredValue));
setError(null);
if (savedValue !== configuredValue) setSavedValue(null);
}
useEffect(() => {
if (savedValue === null) return;
const timer = setTimeout(() => setSavedValue(null), 1500);
return () => clearTimeout(timer);
}, [savedValue]);
const acceptsFractionalDisplay = displayDivisor > 1;
function commit(): void {
const trimmed = draft.trim();
const source = trimmed === '' ? String(displayedDefaultValue) : trimmed;
const pattern = acceptsFractionalDisplay ? /^\d+(?:\.\d+)?$/ : /^\d+$/;
const displayValue = Number(source);
const storedValue = Math.round(displayValue * displayDivisor);
if (
!pattern.test(source) ||
!Number.isSafeInteger(storedValue) ||
displayValue < displayedMinimum ||
displayValue > displayedMaximum
) {
const numberFormat = new Intl.NumberFormat(i18n.locale);
const minimum = numberFormat.format(displayedMinimum);
const maximum = numberFormat.format(displayedMaximum);
setError(
acceptsFractionalDisplay
? t`Enter a number of seconds between ${minimum} and ${maximum}.`
: t`Enter a whole number between ${minimum} and ${maximum}.`,
);
return;
}
if (binding === null) {
setError(t`Search settings not yet loaded — try again in a moment`);
return;
}
if (storedValue === configuredValue) {
setDraft(String(displayValue));
setError(null);
return;
}
const semanticPatch: Partial<Record<PerformanceTuningKey, number>> = {
[configKey]: storedValue,
};
const result = binding.patch({ search: { semantic: semanticPatch } });
if (!result.ok) {
const detail = humanFormat(result.error);
const message = t`Failed to update performance setting — ${detail}`;
setError(message);
toast.error(message);
return;
}
setDraft(String(displayValue));
setError(null);
setSavedValue(storedValue);
onCommitted();
}
const messageId = `${id}-message`;
const helpId = `${id}-help`;
return (
<Field data-invalid={error !== null} data-disabled={!bindingReady} className="gap-2">
<FieldLabel htmlFor={id}>{label}</FieldLabel>
<Input
id={id}
value={draft}
onChange={(event) => {
setDraft(event.currentTarget.value);
setSavedValue(null);
if (error !== null) setError(null);
}}
onBlur={commit}
onKeyDown={(event) => {
if (event.key === 'Enter' && !event.nativeEvent.isComposing) {
event.preventDefault();
commit();
}
}}
disabled={!bindingReady}
inputMode={acceptsFractionalDisplay ? 'decimal' : 'numeric'}
autoComplete="off"
spellCheck={false}
aria-invalid={error !== null}
aria-describedby={`${helpId} ${messageId} ${PERFORMANCE_CLEAR_HINT_ID}`}
data-testid={id}
className="h-8 font-mono text-sm"
/>
<FieldDescription id={helpId} className="nth-last-2:mt-0" data-testid={`${id}-help`}>
{help}
</FieldDescription>
<FieldDescription
id={messageId}
aria-live="polite"
aria-atomic="true"
className={error ? 'text-1sm text-destructive' : 'text-muted-foreground text-1sm'}
data-testid={error ? `${id}-error` : `${id}-saved`}
>
{error ?? (savedValue !== null ? <Trans>Saved</Trans> : null)}
</FieldDescription>
</Field>
);
}
interface EmbeddingsKeyFieldProps {
transport: EmbeddingsKeyTransport;
refresh: () => void;
endpointHost: string;
keyPresent: boolean;
keyHint: string | null;
keySource: 'project' | 'file' | 'env' | null;
keyNotRequired: boolean;
loaded: boolean;
}
function EmbeddingsKeyField({
transport,
refresh,
endpointHost,
keyPresent,
keyHint,
keySource,
keyNotRequired,
loaded,
}: EmbeddingsKeyFieldProps) {
const { t } = useLingui();
const secretsPath = okUserHomeLabel('secrets.yml');
const [keyInput, setKeyInput] = useState('');
const [busy, setBusy] = useState(false);
const [error, setError] = useState<string | null>(null);
async function onSave() {
const key = keyInput.trim();
if (!key || busy) return;
setBusy(true);
setError(null);
const result = await transport.setKey(key);
setBusy(false);
if (result.ok) {
setKeyInput('');
refresh();
} else {
setError(result.error ?? t`Couldn't save the key — please try again.`);
}
}
async function onClear() {
if (busy) return;
setBusy(true);
setError(null);
const result = await transport.clearKey();
setBusy(false);
if (result.ok) refresh();
else setError(result.error ?? t`Couldn't clear the key — please try again.`);
}
return (
<section className="space-y-3 rounded-md border p-3" data-testid="settings-search-key">
<div className="space-y-1">
<h4 className="text-sm font-medium">
<Trans>Embeddings API key</Trans>
</h4>
<p className="text-muted-foreground text-1sm">
{keyNotRequired ? (
<Trans>
Not required for a loopback endpoint like{' '}
<span className="font-medium">{endpointHost}</span> — most local servers ignore it.
Add one only if yours needs it.
</Trans>
) : (
<Trans>
Sent to <span className="font-medium">{endpointHost}</span> to embed your content.
Stored on this machine only (in{' '}
<code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">{secretsPath}</code>
), never in the project.
</Trans>
)}
</p>
</div>
{keySource === 'env' ? (
<p className="text-muted-foreground text-1sm" data-testid="settings-search-key-env">
<Trans>
Using the{' '}
<code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
OK_EMBEDDINGS_API_KEY
</code>{' '}
environment variable (managed outside OpenKnowledge).
</Trans>
</p>
) : (
<>
{keyPresent ? (
<div
className="flex items-center justify-between gap-3"
data-testid="settings-search-key-set"
>
<div className="min-w-0">
<div className="mb-1.5 text-sm font-medium">
<Trans>API key set</Trans>
</div>
{keyHint ? (
<p
className="truncate font-mono text-muted-foreground text-xs"
title={t`Key ending in ${keyHint}`}
data-testid="settings-search-key-hint"
>
<span aria-hidden="true">••••••••</span>
{keyHint}
</p>
) : null}
</div>
<Button
variant="outline"
onClick={() => void onClear()}
disabled={busy}
data-testid="settings-search-key-clear"
>
<Trans>Clear</Trans>
</Button>
</div>
) : null}
<div>
<label htmlFor="settings-search-key-input" className="mb-2 block text-sm font-medium">
{keyPresent ? <Trans>Replace key</Trans> : <Trans>Add a key</Trans>}
</label>
<div className="flex items-center gap-2">
<Input
id="settings-search-key-input"
type="password"
value={keyInput}
onChange={(e) => setKeyInput(e.target.value)}
onKeyDown={(e) => {
if (e.key === 'Enter') {
e.preventDefault();
void onSave();
}
}}
placeholder={t`Paste your API key`}
autoComplete="off"
spellCheck={false}
disabled={busy || !loaded}
data-testid="settings-search-key-input"
className="h-8 font-mono text-sm"
/>
<Button
onClick={() => void onSave()}
disabled={busy || keyInput.trim().length === 0}
data-testid="settings-search-key-save"
>
{busy ? <Trans>Saving</Trans> : <Trans>Save</Trans>}
</Button>
</div>
</div>
</>
)}
{error ? (
<p
role="alert"
className="text-sm text-destructive"
data-testid="settings-search-key-error"
>
{error}
</p>
) : null}
</section>
);
}
interface SemanticStatusPanelProps {
status: SemanticIndexStatus | null;
}
function SemanticStatusPanel({ status }: SemanticStatusPanelProps) {
if (!status?.enabled) {
return (
<p
role="status"
aria-live="polite"
className="text-muted-foreground text-1sm mt-2"
data-testid="settings-search-settling"
>
<Trans>Applying your change</Trans>
</p>
);
}
if (!isSemanticSearchOffered(status)) {
return (
<div
role="alert"
className="mt-2 rounded-md border border-warning/40 px-3 py-2 text-1sm text-foreground"
data-testid="settings-search-needs-key"
>
<Trans>
Semantic search is on, but no API key is set — search falls back to keyword matching. Add
one below.
</Trans>
</div>
);
}
const { ready, capable, embedded, total } = status;
const providerFailure = classifySemanticProviderError(status);
if (providerFailure === 'restart_required') {
return (
<div
role="alert"
className="mt-2 rounded-md border border-warning/40 px-3 py-2 text-1sm text-foreground"
data-testid="settings-search-restart-required"
>
<Trans>
The embeddings provider's vector size kept changing. Semantic search is off until
OpenKnowledge restarts.
</Trans>
</div>
);
}
if (providerFailure === 'incapable') {
return (
<div
role="alert"
className="mt-2 rounded-md border border-warning/40 px-3 py-2 text-1sm text-foreground"
data-testid="settings-search-dimensions-mismatch"
>
<Trans>
This endpoint ignored the vector size you configured. Remove{' '}
<code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
search.semantic.dimensions
</code>{' '}
to use the model's own size.
</Trans>
</div>
);
}
if (ready && !capable) {
return (
<div
role="alert"
className="mt-2 rounded-md border border-warning/40 px-3 py-2 text-1sm text-foreground"
data-testid="settings-search-provider-error"
>
<Trans>
A key is set, but the embeddings provider rejected it or was unreachable — search fell
back to keyword matching. Use <span className="font-medium">Test connection</span> under
Custom endpoint to see what went wrong.
</Trans>
</div>
);
}
if (!ready) {
return (
<p
role="status"
className="text-muted-foreground text-1sm mt-2"
data-testid="settings-search-pending"
>
<Trans>Semantic ranking activates the first time an agent runs a search.</Trans>
</p>
);
}
return (
<div className="mt-2 space-y-0.5" data-testid="settings-search-coverage">
<p className="text-muted-foreground text-1sm">
<Trans>
Indexed {embedded} of {total} pages.
</Trans>
</p>
{embedded === 0 ? (
<p className="text-muted-foreground text-1sm">
<Trans>Pages are embedded the first time a search needs them.</Trans>
</p>
) : null}
</div>
);
}
interface TestConnectionResultProps {
result: { response: LocalOpEmbeddingsTestResponse | null } | null;
testing: boolean;
configuredBaseUrl: string;
configuredModel: string;
}
function TestConnectionResult({
result,
testing,
configuredBaseUrl,
configuredModel,
}: TestConnectionResultProps) {
if (testing || result === null) return null;
const { response } = result;
if (response === null) {
return (
<TestConnectionMessage tone="error" testId="settings-search-test-unreachable">
<Trans>Couldn't run the test. Check that OpenKnowledge is still running.</Trans>
</TestConnectionMessage>
);
}
if (response.endpoint !== configuredBaseUrl || response.model !== configuredModel) {
return (
<TestConnectionMessage tone="warn" testId="settings-search-test-stale">
<Trans>Your change is still being saved — run the test again in a moment.</Trans>
</TestConnectionMessage>
);
}
if (response.ok) {
return (
<TestConnectionMessage tone="ok" testId="settings-search-test-ok">
<Trans>Connected — this endpoint returns {response.dimensions}-dimension vectors.</Trans>
</TestConnectionMessage>
);
}
return (
<TestConnectionMessage tone="error" testId="settings-search-test-error">
<TestConnectionFailure response={response} />
</TestConnectionMessage>
);
}
function TestConnectionFailure({
response,
}: {
response: Extract<LocalOpEmbeddingsTestResponse, { ok: false }>;
}) {
switch (response.reason) {
case 'no_key':
return <Trans>No API key is set for this endpoint. Add one above.</Trans>;
case 'invalid_endpoint':
return (
<Trans>
That endpoint can't be used. Enter an https:// URL — http:// is only allowed for loopback
endpoints.
</Trans>
);
case 'rate_limit':
return <Trans>The provider is rate-limiting this key. Try again in a moment.</Trans>;
case 'timeout':
return <Trans>The endpoint didn't respond in time.</Trans>;
case 'network':
return <Trans>Couldn't reach the endpoint. Check the URL and that the server is up.</Trans>;
case 'dims_mismatch':
return (
<Trans>
This endpoint ignored the vector size you configured. Remove{' '}
<code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
search.semantic.dimensions
</code>{' '}
to use the model's own size.
</Trans>
);
case 'malformed_response':
return (
<Trans>
The endpoint answered, but not with an OpenAI-compatible embeddings response. Check the
base URL.
</Trans>
);
default:
return response.status !== undefined ? (
<Trans>
The provider rejected the request (HTTP {response.status}). Check the API key and the
model id.
</Trans>
) : (
<Trans>The provider rejected the request. Check the API key and the model id.</Trans>
);
}
}
function TestConnectionMessage({
tone,
testId,
children,
}: {
tone: 'ok' | 'warn' | 'error';
testId: string;
children: ReactNode;
}) {
const toneClass = {
ok: 'border-success/40 text-foreground',
warn: 'border-warning/40 text-foreground',
error: 'border-destructive/50 text-destructive',
}[tone];
return (
<p
role={tone === 'error' ? 'alert' : 'status'}
aria-live={tone === 'error' ? 'assertive' : 'polite'}
className={`rounded-md border px-3 py-2 text-1sm ${toneClass}`}
data-testid={testId}
>
{children}
</p>
);
}
interface ProviderChangeConfirmDialogProps {
pending: { baseUrl: string; model: string } | null;
pageCount: number;
onCancel: () => void;
onConfirm: () => void;
}
function ProviderChangeConfirmDialog({
pending,
pageCount,
onCancel,
onConfirm,
}: ProviderChangeConfirmDialogProps) {
const host = pending ? (hostOf(pending.baseUrl) ?? pending.baseUrl) : '';
return (
<DialogRoot
open={pending !== null}
onOpenChange={(open) => {
if (!open) onCancel();
}}
>
<DialogContent className="sm:max-w-lg" data-testid="settings-search-provider-confirm">
<DialogHeader>
<DialogTitle>
<Trans>Change the embeddings provider?</Trans>
</DialogTitle>
<DialogDescription>
<Trans>
Cached embeddings belong to the endpoint and model that produced them, so this
rebuilds the index from scratch.
</Trans>
</DialogDescription>
</DialogHeader>
<DialogBody>
<div
role="alert"
className="rounded-md border border-warning/40 px-3 py-2.5 text-sm text-foreground"
>
<ul className="list-disc space-y-1.5 pl-5">
<li>
<Plural
value={pageCount}
one={
<Trans>
The full text of your 1 page will be sent to{' '}
<span className="font-medium">{host}</span> as it is re-embedded.
</Trans>
}
other={
<Trans>
The full text of all {pageCount} pages will be sent to{' '}
<span className="font-medium">{host}</span> as they are re-embedded.
</Trans>
}
/>
</li>
<li>
<Trans>
Model: <span className="font-mono">{pending?.model}</span>
</Trans>
</li>
<li>
<Trans>
Re-embedding happens as searches run, so coverage restarts at zero and refills.
</Trans>
</li>
</ul>
</div>
</DialogBody>
<DialogFooter>
<DialogClose asChild>
<Button variant="outline">
<Trans>Cancel</Trans>
</Button>
</DialogClose>
<Button onClick={onConfirm} data-testid="settings-search-provider-confirm-apply">
<Trans>Change provider</Trans>
</Button>
</DialogFooter>
</DialogContent>
</DialogRoot>
);
}
function hostOf(baseUrl: string): string | null {
try {
return new URL(baseUrl).host;
} catch {
return null;
}
}
interface EnableSemanticSearchConfirmDialogProps {
open: boolean;
onOpenChange: (open: boolean) => void;
onConfirm: () => void;
}
function EnableSemanticSearchConfirmDialog({
open,
onOpenChange,
onConfirm,
}: EnableSemanticSearchConfirmDialogProps) {
return (
<DialogRoot open={open} onOpenChange={onOpenChange}>
<DialogContent className="sm:max-w-lg" data-testid="settings-search-confirm">
<DialogHeader>
<DialogTitle>
<Trans>Turn on semantic search?</Trans>
</DialogTitle>
<DialogDescription>
<Trans>
Semantic search adds meaning-based ranking to the search tool so conceptually-related
pages surface even without shared keywords.
</Trans>
</DialogDescription>
</DialogHeader>
<DialogBody>
<div
role="alert"
className="rounded-md border border-warning/40 px-3 py-2.5 text-sm text-foreground"
>
<p className="mb-2 font-medium">
<Trans>This sends content off your machine</Trans>
</p>
<ul className="list-disc space-y-1.5 pl-5">
<li>
<Trans>
Your search queries and the full text of matching pages are sent to your
embeddings provider (OpenAI by default) to compute embeddings.
</Trans>
</li>
<li>
<Trans>
Embeddings are computed only when a search runs and are cached locally under{' '}
<code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">.ok/local</code>.
</Trans>
</li>
<li>
<Trans>
This setting is per-machine and isn't shared with collaborators. It needs an API
key (set below) unless your endpoint is a local server that doesn't require one.
</Trans>
</li>
</ul>
</div>
</DialogBody>
<DialogFooter>
<DialogClose asChild>
<Button variant="outline">
<Trans>Cancel</Trans>
</Button>
</DialogClose>
<Button onClick={onConfirm} data-testid="settings-search-confirm-enable">
<Trans>Turn on</Trans>
</Button>
</DialogFooter>
</DialogContent>
</DialogRoot>
);
}