DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import { useSettings } from "@/features/settings/store/SettingsStore";
import { useStagedSettings } from "@/features/settings/store/useStagedSettings";
import { useCallback, useEffect, useRef, useState } from "react";
import { CheckCircle2, Download, Loader2, XCircle } from "lucide-react";
import { useTranslation } from "react-i18next";
import {
SettingRow,
SettingSection,
SettingsPageHeader,
inputClass,
nativeSelectClass,
selectOptionClass,
} from "@/components/settings/shared";
import { MinerUEngineSettings } from "@/components/settings/MinerUEngineSettings";
import { Toggle } from "@/components/settings/Toggle";
import { apiFetch, apiUrl } from "@/lib/api";
import { ImageDescriptionModelSetting } from "./ImageDescriptionModelSetting";
type EngineMeta = {
id: string;
name: string;
description: string;
needs_local_models: boolean;
available: boolean;
};
type Readiness = { ready: boolean; reason: string; message: string };
type DocumentParsingPayload = {
engine: string;
image_description_model?: { profile_id: string; model_id: string } | null;
engines: Record<string, Record<string, unknown>>;
available_engines: EngineMeta[];
readiness: Record<string, Readiness>;
installable: string[];
mineru: { api_token_set: boolean; local_cli?: unknown };
docling?: { api_token_set: boolean };
};
const PIP_HINT: Record<string, string> = {
docling: "pip install deeptutor[parse-docling]",
markitdown: "pip install deeptutor[parse-markitdown]",
pymupdf4llm: "pip install deeptutor[parse-pymupdf4llm]",
liteparse: "pip install deeptutor[parse-liteparse]",
};
// Engine names and descriptions are returned by the backend so unknown or
// future engines can still render. Known descriptions use locale keys to keep
// the settings page translated without changing the API metadata contract.
const ENGINE_NAME_KEYS: Record<string, string> = {
text_only: "Text-only",
};
const ENGINE_DESCRIPTION_KEYS: Record<string, string> = {
text_only:
"Built-in plain text extraction for PDF/Office/text files. No optional parser package, no model download, no layout structure.",
mineru:
"Highest-fidelity multimodal parsing (layout, tables, formulas). Local CLI downloads models, or use the hosted cloud API. Supports PDF, common images, DOCX, PPTX, and XLSX.",
docling:
"Structured document conversion (layout/tables). Runs the in-process docling package (downloads models on first run) or points at a remote Docling Serve server. PDF/Office/HTML/images.",
markitdown:
"Lightweight, no model downloads — broad format support, Markdown output. Works out of the box.",
pymupdf4llm:
"Lightweight, no model downloads or CUDA — runs on low-end / GPU-less machines. PDF/e-book → Markdown and can extract images. PDF and e-book formats only.",
liteparse:
"Fast, lightweight PDF parser with spatial text extraction. Markdown output, optional image extraction. No model downloads. Developed by LlamaIndex.",
tika: "Remote Apache Tika server. Broad format support, no local install or model downloads. Point at an existing tika-server container.",
};
export default function DocumentParsingSettingsPage() {
const { t } = useTranslation();
const [liveData, setLiveData] = useState<DocumentParsingPayload | null>(null);
const [data, setData] = useStagedSettings("document-parsing", liveData, setLiveData);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const { applying: busy, draftRevision } = useSettings();
const load = useCallback(async () => {
setError(null);
try {
const response = await apiFetch(apiUrl("/api/settings/document-parsing"));
const payload = (await response.json().catch(() => ({}))) as
| DocumentParsingPayload
| { detail?: string };
if (!response.ok) {
throw new Error(
"detail" in payload && payload.detail
? payload.detail
: t("Failed to load document parsing settings."),
);
}
setLiveData(payload as DocumentParsingPayload);
} catch (err) {
setError(err instanceof Error ? err.message : String(err));
} finally {
setLoading(false);
}
}, [t]);
useEffect(() => {
void load();
}, [load, draftRevision]);
const putDocumentParsing = async (body: Record<string, unknown>) => {
setData((current) => {
if (!current) return current;
const engines = { ...current.engines };
for (const [name, patch] of Object.entries((body.engines ?? {}) as Record<string, Record<string, unknown>>)) {
engines[name] = { ...engines[name], ...patch };
}
return { ...current, ...body, engines } as DocumentParsingPayload;
});
return true;
};
return (
<div>
<SettingsPageHeader
title={t("Document Parsing")}
description={t(
"How uploaded documents are converted into text for knowledge bases and question generation. Pick an engine and its options. Local model downloads are off by default — they only happen when you explicitly allow them.",
)}
/>
{loading && (
<div className="flex items-center gap-2 text-[13px] text-[var(--muted-foreground)]">
<Loader2 className="h-4 w-4 animate-spin" />
{t("Loading...")}
</div>
)}
{!loading && error && (
<div className="mb-5 rounded-xl border border-red-500/30 bg-red-500/10 px-4 py-3 text-[13px] text-red-600 dark:text-red-300">
{error}
</div>
)}
{!loading && data && (
<>
<ImageDescriptionModelSetting
value={data.image_description_model ?? null}
disabled={busy}
onChange={(selection) => putDocumentParsing({ image_description_model: selection })}
/>
<section className="mb-10">
<header className="mb-3">
<h2 className="text-[15px] font-semibold tracking-tight text-[var(--foreground)]">
{t("Engine")}
</h2>
<p className="mt-1 text-[12.5px] leading-relaxed text-[var(--muted-foreground)]">
{t(
"The active engine handles all parsing. Text-only is built in and extracts plain text; markitdown is lightweight and optional; MinerU and Docling produce richer structure, while Tika provides broad remote text extraction.",
)}
</p>
</header>
<div className="flex flex-col gap-2">
{data.available_engines.map((engine) => {
const active = engine.id === data.engine;
const nameKey = ENGINE_NAME_KEYS[engine.id];
const descriptionKey = ENGINE_DESCRIPTION_KEYS[engine.id];
return (
<button
key={engine.id}
type="button"
disabled={busy}
onClick={() =>
!active && putDocumentParsing({ engine: engine.id })
}
className={`flex items-start justify-between gap-4 rounded-xl border px-4 py-3 text-left transition-colors disabled:opacity-60 ${
active
? "border-[var(--foreground)] bg-[var(--card)]"
: "border-[var(--border)] hover:border-[var(--foreground)]/40"
}`}
>
<div className="min-w-0">
<div className="flex items-center gap-2">
<span className="text-[13px] font-medium text-[var(--foreground)]">
{nameKey ? t(nameKey) : engine.name}
</span>
{active && (
<span className="rounded-full bg-[var(--foreground)] px-2 py-0.5 text-[10px] font-medium text-[var(--background)]">
{t("Active")}
</span>
)}
{!engine.available && (
<span className="rounded-full border border-[var(--border)] px-2 py-0.5 text-[10px] text-[var(--muted-foreground)]">
{t("Not installed")}
</span>
)}
</div>
<p className="mt-1 text-[12px] text-[var(--muted-foreground)]">
{descriptionKey
? t(descriptionKey)
: engine.description}
</p>
</div>
</button>
);
})}
</div>
</section>
{data.engine === "text_only" && <TextOnlyPanel />}
{data.engine === "mineru" && <MinerUEngineSettings />}
{data.engine === "docling" && (
<DoclingPanel
slice={data.engines.docling || {}}
readiness={data.readiness.docling}
available={
data.available_engines.find((e) => e.id === "docling")
?.available ?? false
}
busy={busy}
onInstalled={load}
tokenSet={data.docling?.api_token_set ?? false}
onSave={(patch) =>
putDocumentParsing({ engines: { docling: patch } })
}
/>
)}
{data.engine === "markitdown" && (
<MarkItDownPanel
slice={data.engines.markitdown || {}}
available={
data.available_engines.find((e) => e.id === "markitdown")
?.available ?? false
}
busy={busy}
onInstalled={load}
onSave={(patch) =>
putDocumentParsing({ engines: { markitdown: patch } })
}
/>
)}
{data.engine === "pymupdf4llm" && (
<PyMuPDF4LLMPanel
slice={data.engines.pymupdf4llm || {}}
available={
data.available_engines.find((e) => e.id === "pymupdf4llm")
?.available ?? false
}
busy={busy}
onInstalled={load}
onSave={(patch) =>
putDocumentParsing({ engines: { pymupdf4llm: patch } })
}
/>
)}
{data.engine === "liteparse" && (
<LiteParsePanel
slice={data.engines.liteparse || {}}
available={
data.available_engines.find((e) => e.id === "liteparse")
?.available ?? false
}
busy={busy}
onInstalled={load}
onSave={(patch) =>
putDocumentParsing({ engines: { liteparse: patch } })
}
/>
)}
{data.engine === "tika" && (
<TikaPanel
slice={data.engines.tika || {}}
readiness={data.readiness.tika}
busy={busy}
onSave={(patch) =>
putDocumentParsing({ engines: { tika: patch } })
}
/>
)}
</>
)}
</div>
);
}
function TextOnlyPanel() {
const { t } = useTranslation();
return (
<SettingSection
title={t("Text-only")}
description={t(
"Built-in plain text extraction for PDF, Office, and text files. No optional parser package, model download, OCR, or layout reconstruction.",
)}
>
<SettingRow
title={t("Model status")}
control={
<ReadinessBadge
readiness={{ ready: true, reason: "ready", message: "" }}
/>
}
/>
</SettingSection>
);
}
function ReadinessBadge({ readiness }: { readiness?: Readiness }) {
const { t } = useTranslation();
if (!readiness) return null;
return (
<span
className={`inline-flex items-center gap-1 text-[12px] ${
readiness.ready
? "text-emerald-600 dark:text-emerald-400"
: "text-amber-600 dark:text-amber-400"
}`}
>
{readiness.ready ? (
<CheckCircle2 className="h-3.5 w-3.5 shrink-0" />
) : (
<XCircle className="h-3.5 w-3.5 shrink-0" />
)}
{readiness.ready ? t("Ready to parse.") : t(readiness.message)}
</span>
);
}
// Full-width readiness line for engines whose "not ready" guidance is a
// multi-sentence message (e.g. Docling's "models not downloaded" hint). A long
// message must wrap full-width — it doesn't fit a SettingRow's compact,
// non-shrinking control slot (which overflows and squeezes the title).
function ReadinessNotice({ readiness }: { readiness?: Readiness }) {
const { t } = useTranslation();
if (!readiness) return null;
if (readiness.ready) {
return (
<div className="flex items-center gap-1.5 py-3.5 text-[12px] text-emerald-600 dark:text-emerald-400">
<CheckCircle2 className="h-3.5 w-3.5 shrink-0" />
{t("Ready to parse.")}
</div>
);
}
return (
<div className="py-3.5">
<div className="flex items-start gap-2 rounded-lg border border-amber-500/30 bg-amber-500/10 px-3 py-2.5 text-[12px] leading-relaxed text-amber-700 dark:text-amber-300">
<XCircle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
<span className="min-w-0">{t(readiness.message)}</span>
</div>
</div>
);
}
const DOCLING_MODES = ["local", "remote"] as const;
const DEFAULT_DOCLING_URL = "http://localhost:5001";
const TOKEN_MASK = "••••••••••••";
function DoclingPanel({
slice,
readiness,
available,
busy,
tokenSet,
onInstalled,
onSave,
}: {
slice: Record<string, unknown>;
readiness?: Readiness;
available: boolean;
busy: boolean;
tokenSet: boolean;
onInstalled: () => void;
onSave: (patch: Record<string, unknown>) => Promise<boolean>;
}) {
const { t } = useTranslation();
const mode =
slice.mode === "remote"
? "remote"
: slice.mode === "local"
? "local"
: "local";
const isRemote = mode === "remote";
const doOcr = Boolean(slice.do_ocr);
const doTables = slice.do_table_structure !== false;
const allowDownload = Boolean(slice.allow_local_model_download);
const remoteDraft = { url: String(slice.api_base_url ?? "") };
const tokenDraft = String(slice.api_token ?? "");
const tokenTouched = slice.api_token !== undefined;
const [testing, setTesting] = useState(false);
const [testResult, setTestResult] = useState<{
ok: boolean;
message: string;
} | null>(null);
async function testConnection() {
setTesting(true);
setTestResult(null);
try {
const body: Record<string, unknown> = {
api_base_url: remoteDraft.url.trim() || DEFAULT_DOCLING_URL,
};
if (tokenTouched) body.api_token = tokenDraft;
const response = await apiFetch(
apiUrl("/api/settings/document-parsing/docling/test"),
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
},
);
const data = (await response.json().catch(() => ({}))) as {
ok?: boolean;
message?: string;
detail?: string;
};
if (!response.ok) {
setTestResult({
ok: false,
message: data.detail || t("Connection test failed."),
});
return;
}
setTestResult({
ok: Boolean(data.ok),
message:
data.message ||
(data.ok ? t("Ready to parse.") : t("Connection test failed.")),
});
} catch (err) {
setTestResult({
ok: false,
message: err instanceof Error ? err.message : String(err),
});
} finally {
setTesting(false);
}
}
const notInstalled = !available && !isRemote;
return (
<>
<SettingSection
title={t("Docling backend")}
description={t(
"Choose where parsing runs: the in-process docling package (local) or a Docling Serve server (remote).",
)}
>
<SettingRow
title={t("Mode")}
description={
isRemote
? t(
"Documents are sent to a Docling Serve server for conversion.",
)
: t(
"Parsing runs on this machine using the installed docling package.",
)
}
control={
<div className="inline-flex rounded-lg border border-[var(--border)] p-0.5">
{DOCLING_MODES.map((m) => (
<button
key={m}
type="button"
disabled={busy}
onClick={() => {
if (m !== mode) {
onSave({ mode: m });
setTestResult(null);
}
}}
className={`rounded-md px-3 py-1 text-[12px] font-medium transition-colors disabled:opacity-40 ${
mode === m
? "bg-[var(--foreground)] text-[var(--background)]"
: "text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
}`}
>
{m === "local" ? t("Local") : t("Remote server")}
</button>
))}
</div>
}
/>
</SettingSection>
{isRemote && (
<SettingSection
title={t("Remote server")}
description={t(
"Point at a Docling Serve server (e.g. `docling serve` or the docker image). No local docling install or models needed.",
)}
>
<SettingRow
title={t("Server base URL")}
control={
<input
className={`${inputClass} w-[320px] max-w-[48vw] font-mono text-[12px]`}
placeholder={DEFAULT_DOCLING_URL}
value={remoteDraft.url}
onChange={(e) => {
void onSave({ api_base_url: e.target.value });
setTestResult(null);
}}
/>
}
/>
<SettingRow
title={t("API key")}
description={
tokenSet
? t(
"A key is saved. Type to replace it; leave blank to keep it.",
)
: t(
"Optional. Sent as the X-Api-Key header for a secured server.",
)
}
control={
<input
type="password"
className={`${inputClass} w-[320px] max-w-[48vw]`}
placeholder={tokenSet ? TOKEN_MASK : t("Optional API key")}
value={tokenDraft}
onChange={(e) => {
void onSave({ api_token: e.target.value });
}}
/>
}
/>
<SettingRow
title={t("Test connection")}
description={t("Pings the server health + version endpoints.")}
control={
<div className="flex items-center gap-3">
{testResult && (
<span
className={`inline-flex max-w-[40vw] items-center gap-1 text-[12px] ${
testResult.ok
? "text-emerald-600 dark:text-emerald-400"
: "text-red-600 dark:text-red-400"
}`}
>
{testResult.ok ? (
<CheckCircle2 className="h-3.5 w-3.5 shrink-0" />
) : (
<XCircle className="h-3.5 w-3.5 shrink-0" />
)}
{testResult.message}
</span>
)}
<button
type="button"
onClick={testConnection}
disabled={testing || busy}
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-opacity hover:opacity-80 disabled:opacity-40"
>
{testing && <Loader2 className="h-3 w-3 animate-spin" />}
{t("Test")}
</button>
</div>
}
/>
<div className="px-1 pb-4">
<span className="text-[12px] text-[var(--muted-foreground)]">
{t(
"Apply pending settings using the bar below.",
)}
</span>
</div>
</SettingSection>
)}
{isRemote && (
<SettingSection
title={t("Parsing options")}
description={t("Forwarded to the Docling server for each document.")}
>
<SettingRow
title={t("Recognize tables")}
control={
<Toggle
checked={doTables}
disabled={busy}
onChange={(v) => onSave({ do_table_structure: v })}
/>
}
/>
<SettingRow
title={t("OCR scanned pages")}
description={t("Slower; enable for image-only PDFs.")}
control={
<Toggle
checked={doOcr}
disabled={busy}
onChange={(v) => onSave({ do_ocr: v })}
/>
}
/>
</SettingSection>
)}
{!isRemote && notInstalled && (
<NotInstalledSection
engineId="docling"
title={t("Docling (local)")}
onInstalled={onInstalled}
/>
)}
{!isRemote && !notInstalled && (
<SettingSection
title={t("Docling (local)")}
description={t(
"Structured conversion of PDF/Office/HTML/images. Downloads layout/table models on first run.",
)}
>
<ReadinessNotice readiness={readiness} />
{readiness && !readiness.ready && (
<ModelDownloadRow
engineId="docling"
title={t("Docling")}
onDownloaded={onInstalled}
/>
)}
<SettingRow
title={t("Allow automatic model download")}
description={t(
"Off by default. When off, parsing fails with guidance instead of silently downloading models. Or pre-fetch with `docling-tools models download`.",
)}
control={
<Toggle
checked={allowDownload}
disabled={busy}
onChange={(v) => onSave({ allow_local_model_download: v })}
/>
}
/>
<SettingRow
title={t("Recognize tables")}
control={
<Toggle
checked={doTables}
disabled={busy}
onChange={(v) => onSave({ do_table_structure: v })}
/>
}
/>
<SettingRow
title={t("OCR scanned pages")}
description={t("Slower; enable for image-only PDFs.")}
control={
<Toggle
checked={doOcr}
disabled={busy}
onChange={(v) => onSave({ do_ocr: v })}
/>
}
/>
</SettingSection>
)}
</>
);
}
const DEFAULT_TIKA_URL = "http://localhost:9998";
function TikaPanel({
slice,
readiness,
busy,
onSave,
}: {
slice: Record<string, unknown>;
readiness?: Readiness;
busy: boolean;
onSave: (patch: Record<string, unknown>) => Promise<boolean>;
}) {
const { t } = useTranslation();
const draftUrl = String(slice.server_url ?? "");
const setDraftUrl = (server_url: string) => { void onSave({ server_url }); };
const [testing, setTesting] = useState(false);
const [testResult, setTestResult] = useState<{
ok: boolean;
message: string;
} | null>(null);
async function testConnection() {
setTesting(true);
setTestResult(null);
try {
const response = await apiFetch(
apiUrl("/api/settings/document-parsing/tika/test"),
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
server_url: draftUrl.trim() || DEFAULT_TIKA_URL,
}),
},
);
const data = (await response.json().catch(() => ({}))) as {
ok?: boolean;
message?: string;
detail?: string;
};
if (!response.ok) {
setTestResult({
ok: false,
message: data.detail || t("Connection test failed."),
});
return;
}
setTestResult({
ok: Boolean(data.ok),
message:
data.message ||
(data.ok ? t("Ready to parse.") : t("Connection test failed.")),
});
} catch (err) {
setTestResult({
ok: false,
message: err instanceof Error ? err.message : String(err),
});
} finally {
setTesting(false);
}
}
return (
<SettingSection
title={t("Tika")}
description={t(
"Point at an Apache Tika server (e.g. the apache/tika docker image). No local install or models needed.",
)}
>
<ReadinessNotice readiness={readiness} />
<SettingRow
title={t("Server base URL")}
control={
<input
className={`${inputClass} w-[320px] max-w-[48vw] font-mono text-[12px]`}
placeholder={DEFAULT_TIKA_URL}
value={draftUrl}
onChange={(e) => {
setDraftUrl(e.target.value);
setTestResult(null);
}}
/>
}
/>
<SettingRow
title={t("Test connection")}
description={t("Pings the server /version endpoint.")}
control={
<div className="flex items-center gap-3">
{testResult && (
<span
className={`inline-flex max-w-[40vw] items-center gap-1 text-[12px] ${
testResult.ok
? "text-emerald-600 dark:text-emerald-400"
: "text-red-600 dark:text-red-400"
}`}
>
{testResult.ok ? (
<CheckCircle2 className="h-3.5 w-3.5 shrink-0" />
) : (
<XCircle className="h-3.5 w-3.5 shrink-0" />
)}
{testResult.message}
</span>
)}
<button
type="button"
onClick={testConnection}
disabled={testing || busy}
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-opacity hover:opacity-80 disabled:opacity-40"
>
{testing && <Loader2 className="h-3 w-3 animate-spin" />}
{t("Test")}
</button>
</div>
}
/>
<div className="px-1 pb-4">
<span className="text-[12px] text-[var(--muted-foreground)]">
{t(
"Apply pending settings using the bar below.",
)}
</span>
</div>
</SettingSection>
);
}
function MarkItDownPanel({
slice,
available,
busy,
onInstalled,
onSave,
}: {
slice: Record<string, unknown>;
available: boolean;
busy: boolean;
onInstalled: () => void;
onSave: (patch: Record<string, unknown>) => void;
}) {
const { t } = useTranslation();
const llmImages = Boolean(slice.enable_llm_image_description);
if (!available) {
return (
<NotInstalledSection
engineId="markitdown"
title={t("markitdown")}
onInstalled={onInstalled}
/>
);
}
return (
<SettingSection
title={t("markitdown")}
description={t(
"Lightweight Markdown conversion with broad format support. No model downloads.",
)}
>
<SettingRow
title={t("Describe images with the vision model")}
description={t(
"Reserved — uses DeepTutor's vision model to caption images during conversion.",
)}
control={
<Toggle
checked={llmImages}
disabled={busy}
onChange={(v) => onSave({ enable_llm_image_description: v })}
/>
}
/>
</SettingSection>
);
}
const PYMUPDF4LLM_IMAGE_FORMATS = ["png", "jpg", "jpeg", "webp"];
function PyMuPDF4LLMPanel({
slice,
available,
busy,
onInstalled,
onSave,
}: {
slice: Record<string, unknown>;
available: boolean;
busy: boolean;
onInstalled: () => void;
onSave: (patch: Record<string, unknown>) => void;
}) {
const { t } = useTranslation();
const writeImages = slice.write_images !== false;
const imageFormat =
typeof slice.image_format === "string" ? slice.image_format : "png";
const imageDpi = typeof slice.image_dpi === "number" ? slice.image_dpi : 150;
if (!available) {
return (
<NotInstalledSection
engineId="pymupdf4llm"
title={t("PyMuPDF4LLM")}
onInstalled={onInstalled}
/>
);
}
return (
<SettingSection
title={t("PyMuPDF4LLM")}
description={t(
"Lightweight PDF/e-book → Markdown built on PyMuPDF. No model downloads or CUDA, so it runs on low-end machines.",
)}
>
<SettingRow
title={t("Extract images")}
description={t(
"Save embedded images and rendered vector graphics into the parse, referenced from the Markdown.",
)}
control={
<Toggle
checked={writeImages}
disabled={busy}
onChange={(v) => onSave({ write_images: v })}
/>
}
/>
{writeImages && (
<>
<SettingRow
title={t("Image format")}
control={
<select
className={`${nativeSelectClass} w-28`}
value={imageFormat}
disabled={busy}
onChange={(e) => onSave({ image_format: e.target.value })}
>
{PYMUPDF4LLM_IMAGE_FORMATS.map((f) => (
<option key={f} className={selectOptionClass} value={f}>
{f}
</option>
))}
</select>
}
/>
<SettingRow
title={t("Image resolution (DPI)")}
description={t("Higher is sharper but larger. 72–600.")}
control={
<input
type="number"
min={72}
max={600}
step={1}
value={imageDpi}
disabled={busy}
onChange={(e) => {
const v = Number(e.target.value);
if (Number.isFinite(v)) onSave({ image_dpi: v });
}}
className="w-24 rounded-lg border border-[var(--border)] bg-transparent px-2 py-1 text-[12px] text-[var(--foreground)]"
/>
}
/>
</>
)}
</SettingSection>
);
}
function LiteParsePanel({
slice,
available,
busy,
onInstalled,
onSave,
}: {
slice: Record<string, unknown>;
available: boolean;
busy: boolean;
onInstalled: () => void;
onSave: (patch: Record<string, unknown>) => void;
}) {
const { t } = useTranslation();
const imageMode =
typeof slice.image_mode === "string" ? slice.image_mode : "placeholder";
const extractLinks = slice.extract_links !== false;
const extractImages = Boolean(slice.extract_images);
const maxPages = typeof slice.max_pages === "number" ? slice.max_pages : 0;
if (!available) {
return (
<NotInstalledSection
engineId="liteparse"
title={t("LiteParse")}
onInstalled={onInstalled}
/>
);
}
return (
<SettingSection
title={t("LiteParse")}
description={t(
"Fast Rust-backed PDF/Office/image parser from LlamaIndex. Markdown output, no model downloads.",
)}
>
<SettingRow
title={t("Image mode")}
description={t("How images are represented in the output.")}
control={
<select
className={nativeSelectClass + " w-32"}
value={imageMode}
disabled={busy}
onChange={(e) => onSave({ image_mode: e.target.value })}
>
{["placeholder", "off", "embed"].map((m) => (
<option key={m} className={selectOptionClass} value={m}>
{m}
</option>
))}
</select>
}
/>
<SettingRow
title={t("Extract links")}
description={t("Render [text](url) links in markdown output.")}
control={
<Toggle
checked={extractLinks}
disabled={busy}
onChange={(v) => onSave({ extract_links: v })}
/>
}
/>
<SettingRow
title={t("Extract images")}
description={t("Save embedded images alongside the parsed Markdown.")}
control={
<Toggle
checked={extractImages}
disabled={busy}
onChange={(v) => onSave({ extract_images: v })}
/>
}
/>
<SettingRow
title={t("Max pages")}
description={t("0 = unlimited. Limit pages parsed per document.")}
control={
<input
type="number"
min={0}
step={1}
value={maxPages}
disabled={busy}
onChange={(e) => {
const v = Number(e.target.value);
if (Number.isFinite(v) && v >= 0) onSave({ max_pages: v });
}}
className="w-24 rounded-lg border border-[var(--border)] bg-transparent px-2 py-1 text-[12px] text-[var(--foreground)]"
/>
}
/>
</SettingSection>
);
}
type JobKind = "install" | "models";
type JobStatus = {
state: "running" | "done" | "failed" | "cancelled" | string;
kind: JobKind;
lines: string[];
message: string;
};
// Shared driver for the page's one-click background jobs (pip install / model
// download). Mirrors the MinerU model-download UI: POST to start → poll a shared
// cursor-based log filtered by `kind` → call onDone once on success. Only one
// job runs server-side at a time, so the kind filter keeps each card's view to
// its own job.
function useBackgroundJob(
kind: JobKind,
startUrl: string,
engineId: string,
onDone: () => void,
) {
const { t } = useTranslation();
const [job, setJob] = useState<JobStatus | null>(null);
const [starting, setStarting] = useState(false);
const cursor = useRef(0);
const notifiedDone = useRef(false);
useEffect(() => {
if (job?.state !== "running") return;
const timer = setInterval(async () => {
try {
const response = await apiFetch(
apiUrl(
`/api/settings/document-parsing/job/status?cursor=${cursor.current}`,
),
);
if (!response.ok) return;
const data = (await response.json()) as {
state?: string;
kind?: string;
lines?: string[];
next_cursor?: number;
message?: string;
};
// A different kind of job is running — leave our view alone.
if (data.kind && data.kind !== kind) return;
cursor.current = data.next_cursor ?? cursor.current;
setJob((current) =>
current
? {
state: data.state || current.state,
kind,
lines: [...current.lines, ...(data.lines || [])].slice(-100),
message: data.message || "",
}
: current,
);
if (data.state === "done" && !notifiedDone.current) {
notifiedDone.current = true;
onDone();
}
} catch {
// transient network error — keep polling
}
}, 1000);
return () => clearInterval(timer);
}, [job?.state, kind, onDone]);
async function start() {
setStarting(true);
notifiedDone.current = false;
try {
const response = await apiFetch(apiUrl(startUrl), {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ engine: engineId }),
});
const data = (await response.json().catch(() => ({}))) as {
ok?: boolean;
message?: string;
detail?: string;
};
if (!response.ok || !data.ok) {
setJob({
state: "failed",
kind,
lines: [],
message: data.message || data.detail || t("Failed."),
});
return;
}
cursor.current = 0;
setJob({ state: "running", kind, lines: [], message: "" });
} finally {
setStarting(false);
}
}
async function cancel() {
try {
await apiFetch(apiUrl("/api/settings/document-parsing/job/cancel"), {
method: "POST",
});
} catch {
// status polling surfaces the final state either way
}
}
return { job, starting, start, cancel };
}
// Status line + streamed log for a background job, shared by install / download.
function JobLog({
job,
runningLabel,
doneLabel,
}: {
job: JobStatus | null;
runningLabel: string;
doneLabel: string;
}) {
if (!job) return null;
return (
<div className="px-1 pb-1">
<div
className={`mb-2 inline-flex items-center gap-1.5 text-[12px] ${
job.state === "done"
? "text-emerald-600 dark:text-emerald-400"
: job.state === "running"
? "text-[var(--muted-foreground)]"
: "text-red-600 dark:text-red-400"
}`}
>
{job.state === "running" ? (
<Loader2 className="h-3 w-3 animate-spin" />
) : job.state === "done" ? (
<CheckCircle2 className="h-3.5 w-3.5" />
) : (
<XCircle className="h-3.5 w-3.5" />
)}
{job.state === "running"
? runningLabel
: job.state === "done"
? doneLabel
: job.message || job.state}
</div>
{job.lines.length > 0 && (
<pre className="max-h-40 overflow-y-auto whitespace-pre-wrap rounded-lg border border-[var(--border)]/60 bg-[var(--card)] px-3 py-2 font-mono text-[11px] leading-relaxed text-[var(--muted-foreground)]">
{job.lines.join("\n")}
</pre>
)}
</div>
);
}
function JobButton({
running,
starting,
label,
onStart,
onCancel,
}: {
running: boolean;
starting: boolean;
label: string;
onStart: () => void;
onCancel: () => void;
}) {
const { t } = useTranslation();
if (running) {
return (
<button
type="button"
onClick={onCancel}
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-opacity hover:opacity-80"
>
{t("Cancel")}
</button>
);
}
return (
<button
type="button"
onClick={onStart}
disabled={starting}
className="inline-flex shrink-0 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-80 disabled:opacity-40"
>
{starting ? (
<Loader2 className="h-3 w-3 animate-spin" />
) : (
<Download className="h-3 w-3" />
)}
{label}
</button>
);
}
// The active engine's panel when its optional package isn't installed: a clean
// section with the pip hint and a one-click installer. Keeps install in ONE
// place per engine; reloads on success so the engine flips to available.
function NotInstalledSection({
engineId,
title,
onInstalled,
}: {
engineId: string;
title: string;
onInstalled: () => void;
}) {
const { t } = useTranslation();
const { job, starting, start, cancel } = useBackgroundJob(
"install",
"/api/settings/document-parsing/install",
engineId,
onInstalled,
);
return (
<SettingSection
title={title}
description={t(
"Not installed yet. Install the package to use this engine — runs on the server, no terminal needed.",
)}
>
<SettingRow
title={t("Install package")}
description={PIP_HINT[engineId]}
control={
<JobButton
running={job?.state === "running"}
starting={starting}
label={t("Download & install")}
onStart={start}
onCancel={cancel}
/>
}
/>
<JobLog
job={job}
runningLabel={t("Installing {{name}}…", { name: title })}
doneLabel={t("Installed. Reloading…")}
/>
</SettingSection>
);
}
// One-click model-weight download for an installed engine that still needs its
// models (e.g. Docling). Mirrors MinerU's "Download models"; reloads readiness
// on success so the gate clears.
function ModelDownloadRow({
engineId,
title,
onDownloaded,
}: {
engineId: string;
title: string;
onDownloaded: () => void;
}) {
const { t } = useTranslation();
const { job, starting, start, cancel } = useBackgroundJob(
"models",
"/api/settings/document-parsing/models/download",
engineId,
onDownloaded,
);
return (
<>
<SettingRow
title={t("Download models")}
description={t(
"Fetch the model weights onto the server now — no terminal needed.",
)}
control={
<JobButton
running={job?.state === "running"}
starting={starting}
label={t("Download models")}
onStart={start}
onCancel={cancel}
/>
}
/>
<JobLog
job={job}
runningLabel={t("Downloading {{name}} models…", { name: title })}
doneLabel={t("Downloaded. Reloading…")}
/>
</>
);
}