DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import { useCallback, useEffect, useMemo, useState } from "react";
import { useTranslation } from "react-i18next";
import {
ArrowLeft,
Boxes,
Check,
CheckCircle2,
ChevronDown,
CircleSlash,
Copy,
Database,
ExternalLink,
KeyRound,
Loader2,
RefreshCw,
Server,
Settings2,
ShieldCheck,
Workflow,
XCircle,
type LucideIcon,
} from "lucide-react";
import Link from "next/link";
import {
getEngineModelOptions,
getEnginePreflight,
getGraphRagConfig,
getLightRagConfig,
getLightRagModelOptions,
getLightRagServerConfig,
getImaConfig,
getLlamaIndexConfig,
setEngineActiveModel,
probeLightRagServer,
testGraphRagModelCompatibility,
updateGraphRagConfig,
updateImaConfig,
updateLightRagConfig,
updateLightRagServerConfig,
updateLlamaIndexConfig,
type EnginePreflight,
type GraphRagModelCompatibility,
type GraphRagConfig,
type ImaAccountConfig,
type LightRagConfig,
type LightRagServerConfig,
type LightRagServerProbe,
type LlamaIndexConfig,
type ModelOptionsByKind,
type RagProviderSummary,
} from "@/features/knowledge/api/engines";
import { canApplyGraphRagModelCandidate } from "@/lib/graphrag-model-compatibility";
import { copyText } from "@/lib/clipboard";
import {
kbDocCount,
kbProvider,
providerConnectionStatus,
resolveKbStatus,
type KnowledgeBase,
type ProviderConnectionStatus,
} from "@/lib/knowledge-helpers";
import { PageIndexConfigForm } from "@/components/knowledge/PageIndexSettingsModal";
import KnowledgeEngineIcon from "@/components/knowledge/KnowledgeEngineIcon";
import { useAuthStatus } from "@/hooks/useAuthStatus";
import { useLLMOptions } from "@/hooks/useLLMOptions";
import LightRagRoleModelsEditor, {
newRoleModels,
roleModelsValidationError,
} from "@/components/knowledge/LightRagRoleModelsEditor";
import { selectionFromLightRagDefault } from "@/components/knowledge/IndexingModelSelector";
export interface EngineDetailProps {
provider: RagProviderSummary;
kbs: KnowledgeBase[];
onBack: () => void;
onOpenKb: (name: string) => void;
onSelectMode: (providerId: string, mode: string) => Promise<void> | void;
/** Called after a config change so the parent can refresh provider state. */
onChanged: () => void;
onError: (message: string) => void;
}
const INSTALL_HINTS: Record<string, string> = {
graphrag: "pip install 'deeptutor[graphrag]'",
lightrag: "pip install 'deeptutor[rag-lightrag]'",
};
// Mode one-liners, keyed by `${engineId}:${mode}`. English source strings double
// as i18n keys (zh translations live in locales/zh/app.json).
const MODE_DESCRIPTIONS: Record<string, string> = {
"graphrag:local":
"Entity-focused retrieval over the relevant local subgraph — fast and economical.",
"graphrag:global":
"Map-reduce over global community summaries — best for broad, thematic questions.",
"graphrag:drift":
"Local retrieval with dynamic follow-ups — balances precision and coverage.",
"graphrag:basic": "Plain vector retrieval — the lightest option.",
"lightrag:naive": "Plain vector retrieval, without the knowledge graph.",
"lightrag:local": "Local context focused on the most relevant entities.",
"lightrag:global": "Theme-level retrieval over global relationships.",
"lightrag:hybrid":
"Combines local and global retrieval — a solid general default.",
"lightrag:mix": "Fuses knowledge-graph and vector retrieval.",
"lightrag-server:naive":
"Plain vector retrieval, without the knowledge graph.",
"lightrag-server:local":
"Local context focused on the most relevant entities.",
"lightrag-server:global": "Theme-level retrieval over global relationships.",
"lightrag-server:hybrid":
"Combines local and global retrieval — a solid general default.",
"lightrag-server:mix":
"Fuses knowledge-graph and vector retrieval — the server's default.",
};
// Model kinds each engine needs (for the in-place pickers). "vision" isn't a
// catalog service — it rides on the active chat model. LightRAG owns its role
// models separately and only uses the shared embedding selection here.
const ENGINE_MODEL_KINDS: Record<string, ("llm" | "embedding")[]> = {
llamaindex: ["embedding"],
pageindex: [],
"pageindex-oss": ["llm"],
graphrag: ["llm", "embedding"],
lightrag: ["embedding"],
"lightrag-server": [],
weknora: [],
};
const MODEL_KIND_LABEL: Record<string, string> = {
llm: "Chat model",
embedding: "Embedding model",
};
// Free-form GraphRAG/LightRAG answer styles. Any string is accepted server-side;
// these are the common presets.
const RESPONSE_TYPE_PRESETS = [
"Multiple Paragraphs",
"Single Paragraph",
"Single Sentence",
"List of 3-7 Points",
"Multiple-Page Report",
];
// Prerequisites prose per engine (English source doubles as i18n key).
const ENGINE_PREREQUISITES: Record<string, string> = {
llamaindex:
"Local vector engine — works out of the box. Each knowledge base uses its selected embedding model; install the optional BM25 package to enable hybrid retrieval.",
pageindex:
"Hosted engine: documents are uploaded to PageIndex's servers and the chat agent reads them through the PageIndex MCP tools. Requires an API key; PDF, Office, text and Markdown formats.",
"pageindex-oss":
"Local chunkless and vectorless indexing. Accepts PDF files and uses the globally active chat model credential for indexing; the index remains readable after model changes.",
graphrag:
"Local knowledge-graph retrieval. Needs the optional dependency installed; indexing is LLM-heavy. Requires an active chat model and embedding model.",
lightrag:
"Graph + vector retrieval with multimodal parsing. Needs the optional dependency installed; indexing is LLM-heavy. Requires active chat and embedding models; multimodal also needs a vision model.",
"lightrag-server":
"Server engine: retrieval runs on a standalone LightRAG service you operate. Save a reusable URL here, test it, then override it only when a knowledge base needs another server.",
ima: "Hosted engine: the library lives in Tencent IMA and DeepTutor keeps no copy. Requires an IMA Client ID and API key. Chat searches it, browses its documents, reads full sources, and — only when you ask — collects a web page or saves a note.",
};
function StatusBadge({ status }: { status: ProviderConnectionStatus }) {
const { t } = useTranslation();
if (status === "ready") {
return (
<span className="inline-flex items-center gap-1 rounded-full bg-emerald-100 px-2 py-0.5 text-[10.5px] font-medium text-emerald-700 dark:bg-emerald-950/30 dark:text-emerald-300">
<Check className="h-3 w-3" />
{t("Ready")}
</span>
);
}
if (status === "needs_key") {
return (
<span className="inline-flex items-center rounded-full bg-amber-100 px-2 py-0.5 text-[10.5px] font-medium text-amber-700 dark:bg-amber-950/30 dark:text-amber-300">
{t("Needs key")}
</span>
);
}
if (status === "needs_setup") {
return (
<span className="inline-flex items-center rounded-full bg-sky-100 px-2 py-0.5 text-[10.5px] font-medium text-sky-700 dark:bg-sky-950/30 dark:text-sky-300">
{t("Needs setup")}
</span>
);
}
return (
<span className="inline-flex items-center rounded-full bg-[var(--muted)] px-2 py-0.5 text-[10.5px] font-medium text-[var(--muted-foreground)]">
{t("Not installed")}
</span>
);
}
/** Section shell: small uppercase label + bordered card body. */
function Section({
label,
icon: Icon,
children,
}: {
label: string;
icon: LucideIcon;
children: React.ReactNode;
}) {
return (
<section className="mt-7">
<h2 className="mb-3 flex items-center gap-2 text-[11px] font-medium uppercase tracking-wide text-[var(--muted-foreground)]">
<Icon className="h-3.5 w-3.5" />
{label}
</h2>
{children}
</section>
);
}
function CopyableCommand({ command }: { command: string }) {
const { t } = useTranslation();
const [outcome, setOutcome] = useState<"idle" | "copied" | "failed">("idle");
return (
<div className="flex items-center justify-between gap-2 rounded-lg border border-[var(--border)] bg-[var(--muted)]/40 px-3 py-2">
<code className="truncate font-mono text-[12px] text-[var(--foreground)]">
{command}
</code>
<button
type="button"
onClick={() => {
// The write is awaited before the label changes. This used to be
// `void navigator.clipboard?.writeText(...)` followed by an
// unconditional `setCopied(true)` — where the `?.` meant a missing
// Clipboard API did not even throw, and the label said 已复制 anyway.
void copyText(command).then(
() => setOutcome("copied"),
() => setOutcome("failed"),
);
window.setTimeout(() => setOutcome("idle"), 1500);
}}
className="inline-flex shrink-0 items-center gap-1 rounded-md px-1.5 py-1 text-[11px] font-medium text-[var(--muted-foreground)] transition-colors hover:text-[var(--foreground)]"
>
{outcome === "copied" ? (
<Check className="h-3 w-3" />
) : (
<Copy className="h-3 w-3" />
)}
{outcome === "copied"
? t("Copied")
: outcome === "failed"
? t("Could not copy")
: t("Copy")}
</button>
</div>
);
}
/** Number field used by the LlamaIndex tuning form. */
function NumberField({
label,
hint,
value,
min,
max,
onChange,
disabled,
}: {
label: string;
hint?: string;
value: number;
min: number;
max: number;
onChange: (next: number) => void;
disabled?: boolean;
}) {
return (
<label className="flex flex-col gap-1">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{label}
</span>
<input
type="number"
min={min}
max={max}
value={value}
disabled={disabled}
onChange={(e) => onChange(Number(e.target.value))}
className="w-full rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-1.5 text-[13px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25 disabled:opacity-50"
/>
{hint && (
<span className="text-[11px] text-[var(--muted-foreground)]">
{hint}
</span>
)}
</label>
);
}
function TextField({
label,
hint,
value,
maxLength,
onChange,
}: {
label: string;
hint?: string;
value: string;
maxLength: number;
onChange: (next: string) => void;
}) {
return (
<label className="flex flex-col gap-1">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{label}
</span>
<input
type="text"
value={value}
maxLength={maxLength}
onChange={(e) => onChange(e.target.value)}
className="w-full rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-1.5 text-[13px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25"
/>
{hint && (
<span className="text-[11px] text-[var(--muted-foreground)]">
{hint}
</span>
)}
</label>
);
}
/* ----------------------------- Mode selector ----------------------------- */
function ModeSelector({
provider,
onSelectMode,
}: {
provider: RagProviderSummary;
onSelectMode: (providerId: string, mode: string) => Promise<void> | void;
}) {
const { t } = useTranslation();
const modes = useMemo(() => provider.modes ?? [], [provider.modes]);
const [selected, setSelected] = useState(
provider.default_mode || modes[0] || "",
);
const [pending, setPending] = useState<string | null>(null);
useEffect(() => {
setSelected(provider.default_mode || modes[0] || "");
}, [provider.default_mode, modes]);
const pick = async (mode: string) => {
if (mode === selected) return;
setSelected(mode);
setPending(mode);
try {
await onSelectMode(provider.id, mode);
} finally {
setPending(null);
}
};
return (
<div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
{modes.map((mode) => {
const active = mode === selected;
const desc = MODE_DESCRIPTIONS[`${provider.id}:${mode}`];
return (
<button
key={mode}
type="button"
onClick={() => void pick(mode)}
className={`flex flex-col gap-1 rounded-xl border p-3 text-left transition-colors ${
active
? "border-[var(--primary)] bg-[var(--primary)]/5"
: "border-[var(--border)] hover:border-[var(--ring)]"
}`}
>
<div className="flex items-center justify-between gap-2">
<span className="font-mono text-[12.5px] font-medium text-[var(--foreground)]">
{mode}
</span>
{pending === mode ? (
<Loader2 className="h-3.5 w-3.5 animate-spin text-[var(--muted-foreground)]" />
) : active ? (
<Check className="h-3.5 w-3.5 text-[var(--primary)]" />
) : null}
</div>
{desc && (
<span className="text-[11.5px] leading-snug text-[var(--muted-foreground)]">
{t(desc)}
</span>
)}
</button>
);
})}
</div>
);
}
/* -------------------------- LlamaIndex config form ------------------------ */
export function LlamaIndexForm({
onChanged,
onError,
}: {
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const [loaded, setLoaded] = useState<LlamaIndexConfig | null>(null);
const [form, setForm] = useState<LlamaIndexConfig | null>(null);
const [saving, setSaving] = useState(false);
useEffect(() => {
let cancelled = false;
getLlamaIndexConfig({ force: true })
.then((cfg) => {
if (cancelled) return;
setLoaded(cfg);
setForm(cfg);
})
.catch((err) =>
onError(err instanceof Error ? err.message : String(err)),
);
return () => {
cancelled = true;
};
// onError is stable enough; we only want this on mount.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
const dirty = useMemo(
() => !!form && !!loaded && JSON.stringify(form) !== JSON.stringify(loaded),
[form, loaded],
);
if (!form) {
return (
<div className="flex items-center justify-center rounded-2xl border border-[var(--border)] py-10">
<Loader2 className="h-4 w-4 animate-spin text-[var(--muted-foreground)]" />
</div>
);
}
const set = (patch: Partial<LlamaIndexConfig>) =>
setForm((prev) => (prev ? { ...prev, ...patch } : prev));
const save = async () => {
if (!form) return;
setSaving(true);
try {
const next = await updateLlamaIndexConfig({
retrieval_profile: form.retrieval_profile,
top_k: form.top_k,
vector_top_k_multiplier: form.vector_top_k_multiplier,
bm25_top_k_multiplier: form.bm25_top_k_multiplier,
reranker_model: form.reranker_model,
rerank_top_k: form.rerank_top_k,
vector_index_type: form.vector_index_type,
hnsw_m: form.hnsw_m,
hnsw_ef_construction: form.hnsw_ef_construction,
hnsw_ef_search: form.hnsw_ef_search,
chunk_size: form.chunk_size,
chunk_overlap: form.chunk_overlap,
image_description_concurrency: form.image_description_concurrency,
image_description_timeout_seconds:
form.image_description_timeout_seconds,
});
setLoaded(next);
setForm(next);
onChanged();
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setSaving(false);
}
};
const isHybrid = form.retrieval_profile === "hybrid";
const isHnsw = form.vector_index_type === "hnsw";
const profiles: {
id: LlamaIndexConfig["retrieval_profile"];
desc: string;
}[] = [
{
id: "hybrid",
desc: "BM25 keyword + vector semantic retrieval, fused and re-ranked. More robust recall.",
},
{
id: "vector",
desc: "Vector semantic retrieval only. Faster, but leans entirely on embedding quality.",
},
];
const vectorIndexes: {
id: LlamaIndexConfig["vector_index_type"];
desc: string;
}[] = [
{
id: "flat",
desc: "Exact nearest-neighbor search. Best for small and medium knowledge bases.",
},
{
id: "hnsw",
desc: "Approximate graph search for large knowledge bases. Faster at scale with a small recall trade-off.",
},
];
return (
<div className="space-y-6 rounded-2xl border border-[var(--border)] p-4">
{/* Retrieval profile */}
<div>
<div className="mb-2 text-[12px] font-medium text-[var(--foreground)]">
{t("Retrieval profile")}
</div>
<div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
{profiles.map((p) => {
const active = form.retrieval_profile === p.id;
return (
<button
key={p.id}
type="button"
onClick={() => set({ retrieval_profile: p.id })}
className={`flex flex-col gap-1 rounded-xl border p-3 text-left transition-colors ${
active
? "border-[var(--primary)] bg-[var(--primary)]/5"
: "border-[var(--border)] hover:border-[var(--ring)]"
}`}
>
<div className="flex items-center justify-between gap-2">
<span className="font-mono text-[12.5px] font-medium text-[var(--foreground)]">
{p.id}
</span>
{active && (
<Check className="h-3.5 w-3.5 text-[var(--primary)]" />
)}
</div>
<span className="text-[11.5px] leading-snug text-[var(--muted-foreground)]">
{t(p.desc)}
</span>
</button>
);
})}
</div>
</div>
{/* Retrieval breadth */}
<div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
<NumberField
label={t("Results per query")}
value={form.top_k}
min={1}
max={50}
onChange={(v) => set({ top_k: v })}
/>
<NumberField
label={t("Vector candidate ×")}
hint={isHybrid ? undefined : t("Used by hybrid only")}
value={form.vector_top_k_multiplier}
min={1}
max={10}
disabled={!isHybrid}
onChange={(v) => set({ vector_top_k_multiplier: v })}
/>
<NumberField
label={t("Keyword candidate ×")}
hint={isHybrid ? undefined : t("Used by hybrid only")}
value={form.bm25_top_k_multiplier}
min={1}
max={10}
disabled={!isHybrid}
onChange={(v) => set({ bm25_top_k_multiplier: v })}
/>
</div>
{/* Reranking */}
<div>
<div className="mb-2 flex items-baseline justify-between gap-2">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t("Reranking")}
</span>
<span className="text-[11px] text-[var(--muted-foreground)]">
{t("Applies on the next query")}
</span>
</div>
<div className="grid grid-cols-1 gap-4 sm:grid-cols-[2fr_1fr]">
<TextField
label={t("Reranker model")}
hint={t(
"Leave empty to disable. Example: BAAI/bge-reranker-base. Requires the optional rag-rerank extra.",
)}
value={form.reranker_model}
maxLength={200}
onChange={(v) => set({ reranker_model: v })}
/>
<NumberField
label={t("Rerank candidates")}
value={form.rerank_top_k}
min={1}
max={100}
onChange={(v) => set({ rerank_top_k: v })}
/>
</div>
</div>
{/* Vector index */}
<div>
<div className="mb-2 flex items-baseline justify-between gap-2">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t("Vector index")}
</span>
<span className="text-[11px] text-[var(--muted-foreground)]">
{t("Applies on the next full re-index")}
</span>
</div>
<div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
{vectorIndexes.map((indexType) => {
const active = form.vector_index_type === indexType.id;
return (
<button
key={indexType.id}
type="button"
onClick={() => set({ vector_index_type: indexType.id })}
className={`flex flex-col gap-1 rounded-xl border p-3 text-left transition-colors ${
active
? "border-[var(--primary)] bg-[var(--primary)]/5"
: "border-[var(--border)] hover:border-[var(--ring)]"
}`}
>
<div className="flex items-center justify-between gap-2">
<span className="font-mono text-[12.5px] font-medium text-[var(--foreground)]">
{indexType.id}
</span>
{active && (
<Check className="h-3.5 w-3.5 text-[var(--primary)]" />
)}
</div>
<span className="text-[11.5px] leading-snug text-[var(--muted-foreground)]">
{t(indexType.desc)}
</span>
</button>
);
})}
</div>
{isHnsw && (
<div className="mt-3 grid grid-cols-1 gap-4 sm:grid-cols-3">
<NumberField
label={t("HNSW graph degree")}
value={form.hnsw_m}
min={4}
max={64}
onChange={(v) => set({ hnsw_m: v })}
/>
<NumberField
label={t("HNSW construction candidates")}
value={form.hnsw_ef_construction}
min={16}
max={512}
onChange={(v) => set({ hnsw_ef_construction: v })}
/>
<NumberField
label={t("HNSW search candidates")}
value={form.hnsw_ef_search}
min={1}
max={512}
onChange={(v) => set({ hnsw_ef_search: v })}
/>
</div>
)}
</div>
{/* Chunking */}
<div>
<div className="mb-2 flex items-baseline justify-between gap-2">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t("Chunking")}
</span>
<span className="text-[11px] text-[var(--muted-foreground)]">
{t("Applies on the next re-index")}
</span>
</div>
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
<NumberField
label={t("Chunk size")}
value={form.chunk_size}
min={64}
max={8192}
onChange={(v) => set({ chunk_size: v })}
/>
<NumberField
label={t("Chunk overlap")}
value={form.chunk_overlap}
min={0}
max={Math.max(0, form.chunk_size - 1)}
onChange={(v) => set({ chunk_overlap: v })}
/>
</div>
</div>
{/* Image descriptions */}
<div>
<div className="mb-2 flex items-baseline justify-between gap-2">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t("Image descriptions")}
</span>
<span className="text-[11px] text-[var(--muted-foreground)]">
{t("Applies on the next image indexing run")}
</span>
</div>
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
<NumberField
label={t("Concurrent image descriptions")}
value={form.image_description_concurrency}
min={1}
max={16}
onChange={(v) => set({ image_description_concurrency: v })}
/>
<NumberField
label={t("Per-image timeout (seconds)")}
value={form.image_description_timeout_seconds}
min={5}
max={600}
onChange={(v) => set({ image_description_timeout_seconds: v })}
/>
</div>
</div>
<div className="flex justify-end">
<button
type="button"
onClick={() => void save()}
disabled={!dirty || saving}
className="inline-flex items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3.5 py-1.5 text-[12.5px] font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
>
{saving && <Loader2 className="h-3.5 w-3.5 animate-spin" />}
{t("Save changes")}
</button>
</div>
</div>
);
}
/* ------------------------- Tencent IMA credentials ------------------------ */
export function ImaForm({
onChanged,
onError,
}: {
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const [config, setConfig] = useState<ImaAccountConfig | null>(null);
const [clientId, setClientId] = useState("");
const [apiKey, setApiKey] = useState("");
const [saving, setSaving] = useState(false);
useEffect(() => {
let cancelled = false;
getImaConfig({ force: true })
.then((cfg) => {
if (cancelled) return;
setConfig(cfg);
setClientId(cfg.client_id || "");
})
.catch((err) =>
onError(err instanceof Error ? err.message : String(err)),
);
return () => {
cancelled = true;
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
const persist = async (payload: { client_id?: string; api_key?: string }) => {
setSaving(true);
try {
const next = await updateImaConfig(payload);
setConfig(next);
setClientId(next.client_id || "");
setApiKey("");
onChanged();
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setSaving(false);
}
};
const keySet = config?.api_key_set ?? false;
return (
<div className="space-y-4 rounded-2xl border border-[var(--border)] p-4">
<p className="text-[12px] leading-relaxed text-[var(--muted-foreground)]">
{t(
"One IMA account reaches every library in it, so this pair is shared by all your Tencent IMA knowledge bases. Connecting one then only asks which library to point at. A knowledge base can still carry its own credentials to reach a second account.",
)}
</p>
<div>
<label className="mb-1 block text-[11px] font-medium uppercase tracking-wide text-[var(--muted-foreground)]">
{t("Client ID")}
</label>
<input
value={clientId}
onChange={(e) => setClientId(e.target.value)}
disabled={saving}
autoComplete="off"
placeholder={t("Enter your IMA Client ID")}
className="w-full rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-2 font-mono text-[13px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25 disabled:opacity-50"
/>
</div>
<div>
<label className="mb-1 block text-[11px] font-medium uppercase tracking-wide text-[var(--muted-foreground)]">
{t("API key")}
</label>
<input
type="password"
value={apiKey}
onChange={(e) => setApiKey(e.target.value)}
disabled={saving}
autoComplete="off"
placeholder={
keySet
? t("•••••••• (configured — leave blank to keep)")
: t("Enter your IMA API key")
}
className="w-full rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-2 text-[13px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25 disabled:opacity-50"
/>
{keySet && (
<button
type="button"
onClick={() => void persist({ api_key: "" })}
disabled={saving}
className="mt-1.5 text-[11px] font-medium text-red-600 transition-colors hover:text-red-700 disabled:opacity-40 dark:text-red-400"
>
{t("Remove stored key")}
</button>
)}
</div>
<div className="flex items-center justify-between gap-2">
<a
href="https://ima.qq.com/agent-interface"
target="_blank"
rel="noreferrer"
className="inline-flex items-center gap-1 text-[11.5px] text-[var(--muted-foreground)] transition-colors hover:text-[var(--foreground)]"
>
{t("Get an API key")}
<ExternalLink className="h-3 w-3" />
</a>
<button
type="button"
onClick={() =>
void persist({
client_id: clientId.trim(),
...(apiKey.trim() ? { api_key: apiKey.trim() } : {}),
})
}
disabled={saving}
className="inline-flex items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3.5 py-1.5 text-[12.5px] font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
>
{saving && <Loader2 className="h-3.5 w-3.5 animate-spin" />}
{t("Save changes")}
</button>
</div>
</div>
);
}
/* --------------------------- Shared form controls ------------------------- */
function ResponseTypeSelect({
value,
onChange,
}: {
value: string;
onChange: (next: string) => void;
}) {
const { t } = useTranslation();
const known = RESPONSE_TYPE_PRESETS.includes(value);
return (
<label className="flex flex-col gap-1">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t("Response style")}
</span>
<select
value={value}
onChange={(e) => onChange(e.target.value)}
className="w-full cursor-pointer rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-1.5 text-[13px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25"
>
{RESPONSE_TYPE_PRESETS.map((p) => (
<option key={p} value={p}>
{p}
</option>
))}
{!known && <option value={value}>{value}</option>}
</select>
</label>
);
}
function ToggleField({
label,
hint,
checked,
onChange,
}: {
label: string;
hint?: string;
checked: boolean;
onChange: (next: boolean) => void;
}) {
return (
<div className="flex items-center justify-between gap-3">
<div className="flex flex-col">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{label}
</span>
{hint && (
<span className="text-[11px] text-[var(--muted-foreground)]">
{hint}
</span>
)}
</div>
<button
type="button"
role="switch"
aria-checked={checked}
onClick={() => onChange(!checked)}
className={`relative h-5 w-9 shrink-0 rounded-full transition-colors ${
checked ? "bg-[var(--primary)]" : "bg-[var(--border)]"
}`}
>
<span
className={`absolute top-0.5 h-4 w-4 rounded-full bg-white transition-transform ${
checked ? "translate-x-4" : "translate-x-0.5"
}`}
/>
</button>
</div>
);
}
function SaveButton({
dirty,
saving,
invalid = false,
onSave,
}: {
dirty: boolean;
saving: boolean;
invalid?: boolean;
onSave: () => void;
}) {
const { t } = useTranslation();
return (
<div className="flex justify-end">
<button
type="button"
onClick={onSave}
disabled={!dirty || saving || invalid}
className="inline-flex items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3.5 py-1.5 text-[12.5px] font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
>
{saving && <Loader2 className="h-3.5 w-3.5 animate-spin" />}
{t("Save changes")}
</button>
</div>
);
}
/** Shared loader + dirty-tracking scaffold for the small engine config forms. */
function useEngineForm<T>(
load: () => Promise<T>,
onError: (m: string) => void,
) {
const [loaded, setLoaded] = useState<T | null>(null);
const [form, setForm] = useState<T | null>(null);
const [saving, setSaving] = useState(false);
useEffect(() => {
let cancelled = false;
load()
.then((cfg) => {
if (cancelled) return;
setLoaded(cfg);
setForm(cfg);
})
.catch((err) =>
onError(err instanceof Error ? err.message : String(err)),
);
return () => {
cancelled = true;
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
const dirty = useMemo(
() => !!form && !!loaded && JSON.stringify(form) !== JSON.stringify(loaded),
[form, loaded],
);
const patch = (p: Partial<T>) =>
setForm((prev) => (prev ? { ...prev, ...p } : prev));
return { loaded, form, setLoaded, setForm, saving, setSaving, dirty, patch };
}
/* -------------------------- GraphRAG config form -------------------------- */
export function GraphRagForm({
onChanged,
onError,
}: {
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const { form, setLoaded, setForm, saving, setSaving, dirty, patch } =
useEngineForm<GraphRagConfig>(
() => getGraphRagConfig({ force: true }),
onError,
);
if (!form) return <FormSkeleton />;
const save = async () => {
setSaving(true);
try {
const next = await updateGraphRagConfig({
response_type: form.response_type,
community_level: form.community_level,
dynamic_community_selection: form.dynamic_community_selection,
});
setLoaded(next);
setForm(next);
onChanged();
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setSaving(false);
}
};
return (
<div className="space-y-5 rounded-2xl border border-[var(--border)] p-4">
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
<ResponseTypeSelect
value={form.response_type}
onChange={(v) => patch({ response_type: v })}
/>
<NumberField
label={t("Community level")}
hint={t("Graph traversal granularity (local / drift)")}
value={form.community_level}
min={0}
max={5}
onChange={(v) => patch({ community_level: v })}
/>
</div>
<ToggleField
label={t("Dynamic community selection")}
hint={t("Global mode only")}
checked={form.dynamic_community_selection}
onChange={(v) => patch({ dynamic_community_selection: v })}
/>
<SaveButton dirty={dirty} saving={saving} onSave={() => void save()} />
</div>
);
}
/* -------------------------- LightRAG config form -------------------------- */
export function LightRagForm({
onChanged,
onError,
}: {
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const auth = useAuthStatus();
const canEdit = auth.statusAvailable && (!auth.enabled || auth.isAdmin);
const { form, setLoaded, setForm, saving, setSaving, dirty, patch } =
useEngineForm<LightRagConfig>(
() => getLightRagConfig({ force: true }),
onError,
);
if (!form) return <FormSkeleton />;
const save = async () => {
setSaving(true);
try {
const next = await updateLightRagConfig({
top_k: form.top_k,
response_type: form.response_type,
max_concurrent_files: form.max_concurrent_files,
entity_extract_max_gleaning: form.entity_extract_max_gleaning,
llm_timeout: form.llm_timeout,
});
setLoaded(next);
setForm(next);
onChanged();
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setSaving(false);
}
};
return (
<fieldset
disabled={!canEdit || saving}
className="space-y-5 rounded-2xl border border-[var(--border)] p-4"
>
{!auth.loading && !canEdit && (
<p className="text-xs text-[var(--muted-foreground)]">
{t("Only administrators can change shared LightRAG engine settings.")}
</p>
)}
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
<NumberField
label={t("Results per query")}
value={form.top_k}
min={1}
max={200}
onChange={(v) => patch({ top_k: v })}
/>
<ResponseTypeSelect
value={form.response_type}
onChange={(v) => patch({ response_type: v })}
/>
</div>
{/* Indexing knobs are a separate axis from the two above: they shape how
a knowledge base is built, so changing them only affects the next
build — the divider and note keep that from surprising anyone. */}
<div className="space-y-4 border-t border-[var(--border)] pt-4">
<div className="space-y-0.5">
<div className="text-[12px] font-medium text-[var(--foreground)]">
{t("Indexing")}
</div>
<div className="text-[11px] text-[var(--muted-foreground)]">
{t("Applies the next time a knowledge base is built or rebuilt.")}
</div>
</div>
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
<NumberField
label={t("Files in parallel")}
hint={t("Higher finishes sooner but uses more memory")}
value={form.max_concurrent_files}
min={1}
max={16}
onChange={(v) => patch({ max_concurrent_files: v })}
/>
<NumberField
label={t("Extra extraction passes")}
hint={t("Recovers missed entities; each pass costs another call")}
value={form.entity_extract_max_gleaning}
min={0}
max={5}
onChange={(v) => patch({ entity_extract_max_gleaning: v })}
/>
<NumberField
label={t("LLM timeout (seconds)")}
hint={t("Maximum time per LightRAG LLM call")}
value={form.llm_timeout}
min={60}
max={3600}
onChange={(v) => patch({ llm_timeout: v })}
/>
</div>
</div>
<SaveButton dirty={dirty} saving={saving} onSave={() => void save()} />
</fieldset>
);
}
export function LightRagModelsForm({
onChanged,
onError,
}: {
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const catalog = useLLMOptions(getLightRagModelOptions);
const auth = useAuthStatus();
const canEdit = auth.statusAvailable && (!auth.enabled || auth.isAdmin);
const { form, setLoaded, setForm, saving, setSaving, dirty, patch } =
useEngineForm<LightRagConfig>(
() => getLightRagConfig({ force: true }),
onError,
);
if (!form) return <FormSkeleton />;
const legacyBase = selectionFromLightRagDefault(
catalog.options,
form,
catalog.activeDefault,
);
const legacyOption = catalog.options.find(
(option) =>
option.profile_id === legacyBase?.profile_id &&
option.model_id === legacyBase?.model_id,
);
const roleModels =
form.role_models ??
(legacyBase
? newRoleModels(
legacyBase,
form.version !== 2 && legacyOption?.supports_vision === true,
form.llm_model_max_async,
)
: null);
const validationError = roleModelsValidationError(
roleModels,
catalog.options,
);
const save = async () => {
if (!roleModels) {
onError(t("Choose a LightRAG base model before saving."));
return;
}
setSaving(true);
try {
const next = await updateLightRagConfig({ role_models: roleModels });
setLoaded(next);
setForm(next);
onChanged();
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setSaving(false);
}
};
return (
<fieldset
disabled={!canEdit || saving}
className="space-y-4 rounded-2xl border border-[var(--border)] p-4"
>
{!auth.loading && !canEdit && (
<p className="text-xs text-[var(--muted-foreground)]">
{t("Only administrators can change shared LightRAG engine settings.")}
</p>
)}
<LightRagRoleModelsEditor
models={roleModels}
options={catalog.options}
initialMaxAsync={form.llm_model_max_async}
loading={catalog.loading}
error={catalog.error}
disabled={saving}
onChange={(role_models) => patch({ role_models })}
/>
<p className="text-xs text-[var(--muted-foreground)]">
{t(
"KEYWORD and QUERY apply to subsequent queries. EXTRACT and VLM apply to new or fully rebuilt indexes; published indexes keep their pinned models.",
)}
</p>
{validationError && (
<p className="text-xs text-red-600">{t(validationError)}</p>
)}
<SaveButton
dirty={dirty || (!form.role_models && roleModels !== null)}
saving={saving}
invalid={validationError !== null}
onSave={() => void save()}
/>
</fieldset>
);
}
/* --------------------- LightRAG Server defaults form -------------------- */
function LightRagServerForm({
onChanged,
onError,
}: {
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const [loaded, setLoaded] = useState<LightRagServerConfig | null>(null);
const [serverUrl, setServerUrl] = useState("");
const [apiKey, setApiKey] = useState("");
const [probe, setProbe] = useState<LightRagServerProbe | null>(null);
const [probing, setProbing] = useState(false);
const [saving, setSaving] = useState(false);
useEffect(() => {
let cancelled = false;
getLightRagServerConfig({ force: true })
.then((config) => {
if (cancelled) return;
setLoaded(config);
setServerUrl(config.server_url);
})
.catch((err) =>
onError(err instanceof Error ? err.message : String(err)),
);
return () => {
cancelled = true;
};
}, [onError]);
if (!loaded) return <FormSkeleton />;
const normalizedUrl = serverUrl.trim().replace(/\/+$/, "");
const dirty = normalizedUrl !== loaded.server_url || apiKey.length > 0;
const testedCurrentUrl = probe?.ok && probe.base_url === normalizedUrl;
const test = async () => {
if (!normalizedUrl) return;
setProbing(true);
setProbe(null);
try {
setProbe(
await probeLightRagServer({
serverUrl: normalizedUrl,
apiKey,
useSavedApiKey: !apiKey && loaded.api_key_set,
}),
);
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setProbing(false);
}
};
const save = async () => {
if (!testedCurrentUrl) return;
setSaving(true);
try {
const next = await updateLightRagServerConfig({
server_url: normalizedUrl,
...(apiKey ? { api_key: apiKey } : {}),
});
setLoaded(next);
setServerUrl(next.server_url);
setApiKey("");
onChanged();
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setSaving(false);
}
};
return (
<div className="space-y-4 rounded-2xl border border-[var(--border)] p-4">
<div>
<label className="mb-1 block text-[12px] font-medium text-[var(--foreground)]">
{t("Server URL")}
</label>
<div className="flex flex-col gap-2 sm:flex-row">
<input
value={serverUrl}
onChange={(event) => {
setServerUrl(event.target.value);
setProbe(null);
}}
placeholder={t("LightRAG server URL placeholder")}
className="min-w-0 flex-1 rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-2 font-mono text-[12.5px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25"
/>
<button
type="button"
onClick={() => void test()}
disabled={!normalizedUrl || probing || saving}
className="inline-flex shrink-0 items-center justify-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-2 text-[12px] font-medium text-[var(--foreground)] transition-colors hover:border-[var(--ring)] disabled:opacity-40"
>
{probing ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" />
) : (
<Server className="h-3.5 w-3.5" />
)}
{t("Test connection")}
</button>
</div>
</div>
<label className="flex flex-col gap-1">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t("API key")} · {t("optional")}
</span>
<input
type="password"
autoComplete="off"
value={apiKey}
onChange={(event) => {
setApiKey(event.target.value);
setProbe(null);
}}
placeholder={
loaded.api_key_set
? t("Saved key · leave blank to keep")
: t("Only if your server requires one")
}
className="w-full rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-2 text-[12.5px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25"
/>
</label>
{probe && (
<div
className={`flex items-start gap-2 rounded-lg border px-3 py-2 text-[11.5px] leading-relaxed ${
probe.ok
? "border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-900 dark:bg-emerald-950/30 dark:text-emerald-300"
: "border-red-200 bg-red-50 text-red-700 dark:border-red-900 dark:bg-red-950/30 dark:text-red-300"
}`}
>
{probe.ok ? (
<CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0" />
) : (
<XCircle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
)}
<span>
{probe.ok
? t("Connected to LightRAG server")
: probe.error || t("Could not connect")}
</span>
</div>
)}
<div className="flex items-center justify-between gap-3 border-t border-[var(--border)] pt-4">
<p className="text-[11px] leading-relaxed text-[var(--muted-foreground)]">
{t(
"New knowledge bases inherit this connection. You can override it without changing the saved default.",
)}
</p>
<button
type="button"
onClick={() => void save()}
disabled={!dirty || !testedCurrentUrl || saving}
className="inline-flex shrink-0 items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3.5 py-1.5 text-[12.5px] font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
>
{saving && <Loader2 className="h-3.5 w-3.5 animate-spin" />}
{t("Save as default")}
</button>
</div>
</div>
);
}
function FormSkeleton() {
return (
<div className="flex items-center justify-center rounded-2xl border border-[var(--border)] py-10">
<Loader2 className="h-4 w-4 animate-spin text-[var(--muted-foreground)]" />
</div>
);
}
/* ------------------------------ Model pickers ----------------------------- */
function ModelsSection({
providerId,
onChanged,
onError,
}: {
providerId: string;
onChanged: () => void;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const kinds = useMemo(
() => ENGINE_MODEL_KINDS[providerId] ?? [],
[providerId],
);
const [data, setData] = useState<ModelOptionsByKind | null>(null);
const [failed, setFailed] = useState(false);
const [busyKind, setBusyKind] = useState<string | null>(null);
const [testingKind, setTestingKind] = useState<string | null>(null);
const [draftSelections, setDraftSelections] = useState<
Record<string, string>
>({});
const [compatibility, setCompatibility] = useState<{
testedKey: string;
result: GraphRagModelCompatibility;
} | null>(null);
useEffect(() => {
if (kinds.length === 0) return;
let cancelled = false;
setData(null);
setFailed(false);
setDraftSelections({});
setCompatibility(null);
getEngineModelOptions(kinds)
.then((d) => !cancelled && setData(d))
.catch(() => !cancelled && setFailed(true));
return () => {
cancelled = true;
};
}, [kinds]);
const select = useCallback(
async (kind: string, profileId: string, modelId: string) => {
setBusyKind(kind);
try {
const updated = await setEngineActiveModel(kind, profileId, modelId);
setData((prev) => (prev ? { ...prev, [kind]: updated } : prev));
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setBusyKind(null);
}
},
[onError],
);
const testCandidate = useCallback(
async (kind: string, candidateKey: string) => {
const [profileId, modelId] = candidateKey.split("::");
setTestingKind(kind);
try {
const result = await testGraphRagModelCompatibility(profileId, modelId);
setCompatibility({ testedKey: candidateKey, result });
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setTestingKind(null);
}
},
[onError],
);
if (kinds.length === 0) return null;
return (
<Section label={t("Models")} icon={Boxes}>
{failed ? (
<div className="flex items-center justify-between gap-3 rounded-2xl border border-[var(--border)] p-4">
<p className="text-[12px] leading-relaxed text-[var(--muted-foreground)]">
{t(
"This engine uses your active chat and embedding models. Manage them in the model catalog.",
)}
</p>
<Link
href="/settings"
className="inline-flex shrink-0 items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-1.5 text-[12px] font-medium text-[var(--foreground)] transition-colors hover:border-[var(--ring)]"
>
{t("Open catalog")}
<ExternalLink className="h-3 w-3" />
</Link>
</div>
) : !data ? (
<FormSkeleton />
) : (
<div className="space-y-4 rounded-2xl border border-[var(--border)] p-4">
{kinds.map((kind) => {
const entry = data[kind];
const activeKey = `${entry?.active.profile_id ?? ""}::${entry?.active.model_id ?? ""}`;
const value = draftSelections[kind] ?? activeKey;
const hasOptions = (entry?.options.length ?? 0) > 0;
const isGraphRagChat = providerId === "graphrag" && kind === "llm";
const visibleCompatibility =
isGraphRagChat && compatibility?.testedKey === value
? compatibility.result
: null;
const canApply = canApplyGraphRagModelCandidate({
activeKey,
candidateKey: value,
testedKey: compatibility?.testedKey ?? null,
result: compatibility?.result ?? null,
});
return (
<div key={kind} className="flex flex-col gap-1">
<div className="flex items-center gap-2">
<span className="text-[12px] font-medium text-[var(--foreground)]">
{t(MODEL_KIND_LABEL[kind] ?? kind)}
</span>
{busyKind === kind && (
<Loader2 className="h-3 w-3 animate-spin text-[var(--muted-foreground)]" />
)}
</div>
{hasOptions ? (
<select
value={value}
disabled={busyKind === kind || testingKind === kind}
onChange={(e) => {
const candidateKey = e.target.value;
if (isGraphRagChat) {
setDraftSelections((prev) => ({
...prev,
[kind]: candidateKey,
}));
setCompatibility(null);
return;
}
const [pid, mid] = candidateKey.split("::");
void select(kind, pid, mid);
}}
className="w-full cursor-pointer rounded-lg border border-[var(--border)] bg-[var(--background)] px-3 py-1.5 text-[13px] text-[var(--foreground)] outline-none transition-colors focus:border-[var(--foreground)]/25 disabled:opacity-50"
>
{entry!.options.map((o) => (
<option
key={`${o.profile_id}::${o.model_id}`}
value={`${o.profile_id}::${o.model_id}`}
>
{o.label}
{o.detail ? ` · ${o.detail}` : ""}
</option>
))}
</select>
) : (
<Link
href="/settings"
className="inline-flex w-fit items-center gap-1.5 rounded-lg border border-dashed border-[var(--border)] px-3 py-1.5 text-[12px] text-[var(--muted-foreground)] transition-colors hover:text-[var(--foreground)]"
>
{t("No models configured — open catalog")}
<ExternalLink className="h-3 w-3" />
</Link>
)}
{hasOptions && isGraphRagChat && (
<div className="mt-1.5 space-y-2">
<div className="flex flex-wrap items-center gap-2">
<button
type="button"
onClick={() => void testCandidate(kind, value)}
disabled={testingKind === kind || busyKind === kind}
className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-1.5 text-[12px] font-medium text-[var(--foreground)] transition-colors hover:border-[var(--ring)] disabled:opacity-50"
>
{testingKind === kind ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" />
) : (
<ShieldCheck className="h-3.5 w-3.5" />
)}
{t(
testingKind === kind
? "Testing compatibility…"
: "Test compatibility",
)}
</button>
{canApply && (
<button
type="button"
onClick={() => {
const [pid, mid] = value.split("::");
void select(kind, pid, mid);
}}
disabled={busyKind === kind}
className="inline-flex items-center gap-1.5 rounded-lg bg-[var(--foreground)] px-3 py-1.5 text-[12px] font-medium text-[var(--background)] transition-opacity hover:opacity-90 disabled:opacity-50"
>
{busyKind === kind ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" />
) : (
<Check className="h-3.5 w-3.5" />
)}
{t("Use this model")}
</button>
)}
</div>
<p className="text-[11px] leading-relaxed text-[var(--muted-foreground)]">
{t(
"Runs one small structured-output request and may incur provider charges. The global active chat model changes only after you choose Use this model.",
)}
</p>
{visibleCompatibility && (
<div
className={`flex items-start gap-2 rounded-lg border px-3 py-2 text-[11.5px] leading-relaxed ${
visibleCompatibility.status === "compatible"
? "border-emerald-500/25 bg-emerald-500/5 text-emerald-700 dark:text-emerald-300"
: visibleCompatibility.status === "incompatible"
? "border-red-500/25 bg-red-500/5 text-red-700 dark:text-red-300"
: "border-amber-500/25 bg-amber-500/5 text-amber-700 dark:text-amber-300"
}`}
>
{visibleCompatibility.status === "compatible" ? (
<CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0" />
) : visibleCompatibility.status === "incompatible" ? (
<XCircle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
) : (
<CircleSlash className="mt-0.5 h-3.5 w-3.5 shrink-0" />
)}
<div>
<p className="font-medium">
{t(
visibleCompatibility.status === "compatible"
? "Compatible with GraphRAG"
: visibleCompatibility.status === "incompatible"
? "Incompatible with GraphRAG"
: "Compatibility could not be verified",
)}
</p>
<p className="mt-0.5 opacity-90">
{t(visibleCompatibility.message)}
</p>
</div>
</div>
)}
</div>
)}
{kind === "llm" && providerId === "lightrag" && (
<span className="text-[11px] text-[var(--muted-foreground)]">
{t(
"Multimodal documents need a vision-capable chat model.",
)}
</span>
)}
</div>
);
})}
</div>
)}
{providerId === "lightrag" && (
<div className="mt-4">
<LightRagModelsForm onChanged={onChanged} onError={onError} />
</div>
)}
</Section>
);
}
/* ----------------------- Requirements & environment ----------------------- */
function CheckRow({
ok,
optional,
label,
detail,
}: {
ok: boolean;
optional: boolean;
label: string;
detail: string;
}) {
const { t } = useTranslation();
const Icon = ok ? CheckCircle2 : optional ? CircleSlash : XCircle;
const tone = ok
? "text-emerald-600 dark:text-emerald-400"
: optional
? "text-[var(--muted-foreground)]"
: "text-red-600 dark:text-red-400";
return (
<li className="flex items-start gap-2">
<Icon className={`mt-0.5 h-3.5 w-3.5 shrink-0 ${tone}`} />
<div className="min-w-0">
<span className="text-[12px] text-[var(--foreground)]">{t(label)}</span>
{optional && (
<span className="ml-1.5 text-[10px] text-[var(--muted-foreground)]">
({t("optional")})
</span>
)}
{detail && (
<div className="text-[11px] leading-snug text-[var(--muted-foreground)]">
{t(detail)}
</div>
)}
</div>
</li>
);
}
function EnvRequirements({
providerId,
installHint,
defaultOpen,
onError,
}: {
providerId: string;
installHint?: string;
defaultOpen: boolean;
onError: (message: string) => void;
}) {
const { t } = useTranslation();
const [open, setOpen] = useState(defaultOpen);
const [report, setReport] = useState<EnginePreflight | null>(null);
const [checking, setChecking] = useState(false);
const prereq = ENGINE_PREREQUISITES[providerId];
const runCheck = async () => {
setChecking(true);
try {
setReport(await getEnginePreflight(providerId));
} catch (err) {
onError(err instanceof Error ? err.message : String(err));
} finally {
setChecking(false);
}
};
return (
<section className="mt-7">
<button
type="button"
onClick={() => setOpen((v) => !v)}
className="flex w-full items-center justify-between rounded-lg py-1 text-left"
aria-expanded={open}
>
<span className="flex items-center gap-2 text-[11px] font-medium uppercase tracking-wide text-[var(--muted-foreground)]">
<ShieldCheck className="h-3.5 w-3.5" />
{t("Requirements & environment")}
</span>
<ChevronDown
className={`h-4 w-4 text-[var(--muted-foreground)] transition-transform ${
open ? "rotate-180" : ""
}`}
/>
</button>
{open && (
<div className="mt-3 space-y-3 rounded-2xl border border-[var(--border)] p-4">
{prereq && (
<p className="text-[12px] leading-relaxed text-[var(--muted-foreground)]">
{t(prereq)}
</p>
)}
{installHint && <CopyableCommand command={installHint} />}
<div className="flex items-center gap-2.5">
<button
type="button"
onClick={() => void runCheck()}
disabled={checking}
className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-1.5 text-[12px] font-medium text-[var(--foreground)] transition-colors hover:border-[var(--ring)] disabled:opacity-50"
>
{checking ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" />
) : (
<RefreshCw className="h-3.5 w-3.5" />
)}
{t("Check environment")}
</button>
{report && (
<span
className={`inline-flex items-center gap-1 text-[11.5px] font-medium ${
report.ok
? "text-emerald-600 dark:text-emerald-400"
: "text-amber-600 dark:text-amber-400"
}`}
>
{report.ok ? t("Ready to use") : t("Not ready")}
</span>
)}
</div>
{report && (
<ul className="space-y-1.5 border-t border-[var(--border)] pt-3">
{report.checks.map((c) => (
<CheckRow
key={c.key}
ok={c.ok}
optional={c.optional}
label={c.label}
detail={c.detail}
/>
))}
</ul>
)}
</div>
)}
</section>
);
}
/* ------------------------------ Main component ---------------------------- */
export default function EngineDetail({
provider,
kbs,
onBack,
onOpenKb,
onSelectMode,
onChanged,
onError,
}: EngineDetailProps) {
const { t } = useTranslation();
const status = providerConnectionStatus(provider);
const installHint = INSTALL_HINTS[provider.id];
const hasModes = (provider.modes?.length ?? 0) > 0;
const engineKbs = useMemo(
() => kbs.filter((kb) => kbProvider(kb) === provider.id),
[kbs, provider.id],
);
return (
<div className="flex-1 overflow-y-auto bg-[var(--background)]">
<div className="mx-auto max-w-3xl px-6 py-8">
<button
type="button"
onClick={onBack}
className="mb-3 inline-flex items-center gap-1 text-[11.5px] font-medium text-[var(--muted-foreground)] transition-colors hover:text-[var(--foreground)]"
>
<ArrowLeft className="h-3.5 w-3.5" />
{t("Knowledge Center")}
</button>
{/* Header */}
<div className="flex items-start gap-3">
<KnowledgeEngineIcon
engine={provider.id}
size={38}
className="mt-0.5"
/>
<div className="min-w-0 flex-1">
<div className="flex flex-wrap items-center gap-2">
<h1 className="font-serif text-[20px] font-semibold tracking-tight text-[var(--foreground)]">
{provider.name}
</h1>
<StatusBadge status={status} />
</div>
<p className="mt-1 text-[12.5px] leading-relaxed text-[var(--muted-foreground)]">
{provider.description}
</p>
</div>
</div>
{/* Requirements & environment — collapsible, unified across engines.
Auto-opens when the engine isn't ready so the gap is obvious. */}
<EnvRequirements
providerId={provider.id}
installHint={installHint}
defaultOpen={status !== "ready"}
onError={onError}
/>
{provider.id === "lightrag-server" && (
<Section label={t("Connection defaults")} icon={Server}>
<LightRagServerForm onChanged={onChanged} onError={onError} />
</Section>
)}
{/* Retrieval modes (graphrag / lightrag) */}
{hasModes && (
<Section label={t("Retrieval mode")} icon={Workflow}>
<p className="-mt-1 mb-3 text-[11.5px] leading-snug text-[var(--muted-foreground)]">
{t(
"The default for new searches. A knowledge base can still override it per-KB.",
)}
</p>
<ModeSelector provider={provider} onSelectMode={onSelectMode} />
</Section>
)}
{/* LlamaIndex tuning */}
{provider.id === "llamaindex" && (
<Section label={t("Retrieval & chunking")} icon={Settings2}>
<LlamaIndexForm onChanged={onChanged} onError={onError} />
</Section>
)}
{/* GraphRAG query knobs */}
{provider.id === "graphrag" && (
<Section label={t("Retrieval parameters")} icon={Settings2}>
<GraphRagForm onChanged={onChanged} onError={onError} />
</Section>
)}
{/* LightRAG query knobs */}
{provider.id === "lightrag" && (
<Section label={t("Retrieval parameters")} icon={Settings2}>
<LightRagForm onChanged={onChanged} onError={onError} />
</Section>
)}
{/* PageIndex credentials */}
{provider.id === "pageindex" && (
<Section label={t("Credentials")} icon={KeyRound}>
<PageIndexConfigForm onChanged={onChanged} onError={onError} />
</Section>
)}
{/* Tencent IMA credentials */}
{provider.id === "ima" && (
<Section label={t("Credentials")} icon={KeyRound}>
<ImaForm onChanged={onChanged} onError={onError} />
</Section>
)}
{/* Models — in-place pickers for the kinds this engine needs */}
<ModelsSection
providerId={provider.id}
onChanged={onChanged}
onError={onError}
/>
{/* Knowledge bases on this engine */}
<Section
label={`${t("Knowledge bases")} · ${engineKbs.length}`}
icon={Database}
>
{engineKbs.length === 0 ? (
<div className="rounded-2xl border border-dashed border-[var(--border)] px-4 py-8 text-center text-[12px] text-[var(--muted-foreground)]">
{t("No knowledge bases use this engine yet.")}
</div>
) : (
<div className="overflow-hidden rounded-2xl border border-[var(--border)]">
{engineKbs.map((kb, i) => {
const docs = kbDocCount(kb);
const ready = resolveKbStatus(kb) === "ready";
return (
<button
key={kb.name}
type="button"
onClick={() => onOpenKb(kb.name)}
className={`flex w-full items-center justify-between gap-3 px-4 py-2.5 text-left transition-colors hover:bg-[var(--muted)]/40 ${
i > 0 ? "border-t border-[var(--border)]" : ""
}`}
>
<div className="flex min-w-0 items-center gap-2">
<KnowledgeEngineIcon engine={provider.id} size={24} />
<span
className={`inline-block h-1.5 w-1.5 shrink-0 rounded-full ${
ready
? "bg-emerald-500"
: "bg-[var(--muted-foreground)]"
}`}
/>
<span className="truncate text-[13px] font-medium text-[var(--foreground)]">
{kb.name}
</span>
</div>
{docs !== null && (
<span className="shrink-0 text-[11px] text-[var(--muted-foreground)]">
{docs} {t("docs")}
</span>
)}
</button>
);
})}
</div>
)}
</Section>
</div>
</div>
);
}