DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import { useEffect, useState } from "react";
import { useTranslation } from "react-i18next";
import { FolderInput, Loader2, RefreshCw, Upload } from "lucide-react";
import {
listKnowledgeBaseFiles,
type KnowledgeUploadPolicy,
} from "@/features/knowledge/api/files";
import {
kbCanUploadDocuments,
kbNeedsReindex,
kbRequiresLightRagRebuildBeforeAppend,
providerUsesEmbeddingMetadata,
resolveKbStatus,
uploadPolicyForProvider,
validateFiles,
type KnowledgeBase,
} from "@/lib/knowledge-helpers";
import type { TaskState } from "@/hooks/useKnowledgeProgress";
import type { HistoryEntry } from "@/hooks/useKnowledgeHistory";
import FileDropZone from "./FileDropZone";
import KbIndexFailureBanner from "./KbIndexFailureBanner";
import KbUpdateHistory from "./KbUpdateHistory";
import LightRagIndexingProvenance from "./LightRagIndexingProvenance";
interface KbDocumentsSectionProps {
kb: KnowledgeBase;
uploadPolicy: KnowledgeUploadPolicy;
task?: TaskState;
history: HistoryEntry[];
onClearHistory: () => void;
onRetry?: () => Promise<void>;
onUpload: (files: File[], destSubdir?: string) => Promise<void>;
}
/**
* The "Add documents" tab. Focused on the incremental-upload flow: drop
* zone, upload button, live process logs while a task runs, and a list of
* past update events. The file list and preview live under the separate
* "Files" tab to keep each surface single-purpose.
*/
export default function KbDocumentsSection({
kb,
uploadPolicy,
task,
history,
onClearHistory,
onRetry,
onUpload,
}: KbDocumentsSectionProps) {
const { t } = useTranslation();
const [files, setFiles] = useState<File[]>([]);
const [submitting, setSubmitting] = useState(false);
const [retrySubmitting, setRetrySubmitting] = useState(false);
// Existing folders in this KB, offered as a destination for the batch.
const [folders, setFolders] = useState<string[]>([]);
const [destSubdir, setDestSubdir] = useState("");
useEffect(() => {
let cancelled = false;
void listKnowledgeBaseFiles(kb.name)
.then((entries) => {
if (cancelled) return;
setFolders(
entries
.filter((entry) => entry.type === "folder")
.map((entry) => entry.name)
.sort((a, b) => a.localeCompare(b)),
);
})
.catch(() => {
// A destination picker is an optional convenience; failing to list
// folders just means the batch goes to the root as it always did.
if (!cancelled) setFolders([]);
});
return () => {
cancelled = true;
};
}, [kb.name]);
const needsReindex = kbNeedsReindex(kb);
const requiresLightRagRebuild = kbRequiresLightRagRebuildBeforeAppend(kb);
const status = resolveKbStatus(kb);
const isError = status === "error";
const provider =
kb.statistics?.rag_provider || kb.metadata?.rag_provider || "llamaindex";
const policyForProvider = uploadPolicyForProvider(uploadPolicy, provider);
const publishedLightRagVersion =
provider === "lightrag"
? kb.statistics?.index_versions?.find(
(version) =>
version.provider === "lightrag" &&
version.ready &&
(!kb.metadata?.embedding_selection ||
version.version === kb.metadata.indexed_version),
)
: undefined;
const isUploadingHere =
(task?.kind === "upload" || task?.kind === "sync") && task.executing;
const isIndexingHere =
(task?.kind === "reindex" || task?.kind === "retry") && task.executing;
const isRetryingHere = task?.kind === "retry" && task.executing;
// An error-state KB is not locked: the user can drop the file(s) that failed
// (Files tab) and upload replacements here, instead of being forced to
// delete and rebuild the whole base. Uploads stay open unless a rebuild is
// actively running; legacy/transition states remain genuinely blocked.
const canUpload = kbCanUploadDocuments(kb, isIndexingHere);
const blockedReason = canUpload
? null
: kb.metadata?.indexing_model_unavailable
? t(
"Restore access to the pinned indexing models in Settings before adding documents.",
)
: requiresLightRagRebuild
? kb.metadata?.embedding_mismatch
? t(
"The current embedding configuration does not match this index. Restore the original configuration or rebuild with the current embedding before querying or adding documents.",
)
: t(
"This legacy LightRAG index remains queryable, but it must be fully rebuilt before incremental uploads.",
)
: needsReindex
? t(
"This knowledge base is in legacy index format and needs reindex before upload.",
)
: status !== "ready"
? t(
"This knowledge base is currently {{status}} and cannot accept uploads yet.",
{
status: status.replaceAll("_", " "),
},
)
: null;
const selection = validateFiles(files, policyForProvider, t);
const canRetry = Boolean(onRetry) && isError && !isIndexingHere;
// Unsupported files are skipped (shown in the drop zone), not blocking, so a
// picked folder with mixed content still uploads its supported members.
const canSubmit =
canUpload &&
selection.validFiles.length > 0 &&
!submitting &&
!isUploadingHere;
const handleSubmit = async () => {
if (!canSubmit) return;
setSubmitting(true);
try {
await onUpload(selection.validFiles, destSubdir || undefined);
setFiles([]);
} finally {
setSubmitting(false);
}
};
const handleRetry = async () => {
if (!onRetry || !canRetry || retrySubmitting) return;
setRetrySubmitting(true);
try {
await onRetry();
} finally {
setRetrySubmitting(false);
}
};
return (
<div className="space-y-5">
<div>
<div className="text-[13px] font-medium text-[var(--foreground)]">
{t("Add documents")}
</div>
<p className="mt-0.5 text-[11.5px] text-[var(--muted-foreground)]">
{t(
providerUsesEmbeddingMetadata(provider)
? "Drop files here to add them to this knowledge base. New files use its bound embedding model."
: "Drop files here",
)}
</p>
<p className="mt-1 text-[11px] leading-relaxed text-[var(--muted-foreground)]">
{t(
"Choosing a folder here is a one-time import. For a folder that stays in sync, use Linked folders.",
)}
</p>
</div>
{provider === "lightrag" && publishedLightRagVersion && (
<LightRagIndexingProvenance
policy={kb.metadata?.indexing_policy}
version={publishedLightRagVersion}
compact
/>
)}
{blockedReason && (
<div className="rounded-lg border border-amber-200 bg-amber-50 px-3 py-2 text-[12px] text-amber-700 dark:border-amber-900 dark:bg-amber-950/30 dark:text-amber-300">
{blockedReason}
</div>
)}
{isError && !blockedReason && (
<KbIndexFailureBanner
kb={kb}
action={
onRetry ? (
<button
type="button"
onClick={handleRetry}
disabled={!canRetry || retrySubmitting}
className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-red-300 bg-red-100 px-2 py-1 text-[11.5px] font-medium text-red-800 transition-colors hover:bg-red-200 disabled:opacity-50 dark:border-red-800 dark:bg-red-950/50 dark:text-red-200"
>
{retrySubmitting || isRetryingHere ? (
<Loader2 className="h-3 w-3 animate-spin" />
) : (
<RefreshCw className="h-3 w-3" />
)}
{retrySubmitting || isRetryingHere
? t("Retrying…")
: t(
provider === "lightrag"
? "Review rebuild"
: "Retry indexing",
)}
</button>
) : undefined
}
/>
)}
<FileDropZone
files={files}
onChange={setFiles}
uploadPolicy={policyForProvider}
disabled={!canUpload || isUploadingHere}
/>
{folders.length > 0 && files.length > 0 && (
<label className="flex items-center gap-2 text-[12px] text-[var(--muted-foreground)]">
<FolderInput size={13} strokeWidth={1.7} />
<span>{t("Add to folder")}</span>
<select
value={destSubdir}
onChange={(event) => setDestSubdir(event.target.value)}
disabled={!canUpload || isUploadingHere}
className="min-w-0 flex-1 rounded-md border border-[var(--border)] bg-[var(--background)] px-2 py-1 text-[12px] text-[var(--foreground)] disabled:opacity-40"
>
<option value="">{t("Knowledge base root")}</option>
{folders.map((folder) => (
<option key={folder} value={folder}>
{folder}
</option>
))}
</select>
</label>
)}
<div className="flex items-center justify-end">
<button
type="button"
onClick={handleSubmit}
disabled={!canSubmit}
className="inline-flex items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3.5 py-1.5 text-[13px] font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
>
{submitting || isUploadingHere ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" />
) : (
<Upload size={14} />
)}
{t("Upload")}
</button>
</div>
<KbUpdateHistory entries={history} onClear={onClearHistory} />
</div>
);
}