DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import { useEffect, useState } from "react";
import { AlertTriangle, RefreshCcw, X, ScrollText } from "lucide-react";
import { useTranslation } from "react-i18next";
import { bookApi } from "@/lib/book-api";
import type { GenerationSummary } from "@/lib/book-types";
import Tooltip from "@/shared/ui/Tooltip";
export interface BookHealthBannerProps {
bookId: string | null;
refreshKey?: number;
expectedRevision?: number;
onRevisionChange?: (revision: number) => void;
onRecompile?: (pageId: string) => void;
/** Retrieval failed while this book was planned — it was written from the
* proposal alone, with none of the selected sources behind it. */
explorationFailed?: boolean;
}
interface KbDrift {
has_drift: boolean;
new_kbs?: string[];
removed_kbs?: string[];
changed_kbs?: string[];
stale_page_ids?: string[];
}
/** Classifier slug → what to tell the reader. See `_generation_error_category`. */
const FAILURE_CAUSES: Record<string, string> = {
quota: "Your model credit or quota ran out.",
authentication: "The model credentials were rejected.",
rate_limit: "The model provider was rate-limiting the requests.",
missing_dependency:
"Some block types need an optional package that is not installed. Leave those types out of the book, or install the extra.",
provider: "The model provider was unreachable or timed out.",
content: "The model returned something the block could not read.",
};
interface LogHealth {
total_entries: number;
error_entries: number;
block_failures: number;
repeated_failures?: { signature: string; count: number }[];
}
export default function BookHealthBanner({
bookId,
refreshKey,
expectedRevision,
onRevisionChange,
onRecompile,
explorationFailed = false,
}: BookHealthBannerProps) {
const { t } = useTranslation();
const [kbDrift, setKbDrift] = useState<KbDrift | null>(null);
const [logHealth, setLogHealth] = useState<LogHealth | null>(null);
const [generation, setGeneration] = useState<GenerationSummary | null>(null);
const [dismissed, setDismissed] = useState(false);
const [busy, setBusy] = useState(false);
const [acknowledgeError, setAcknowledgeError] = useState<string | null>(null);
const [canForce, setCanForce] = useState(false);
useEffect(() => {
let cancelled = false;
if (!bookId) {
setKbDrift(null);
setLogHealth(null);
setGeneration(null);
return;
}
// `refreshKey` is the book's `updated_at`, undefined until the book has
// loaded. Waiting for it avoids a duplicate check on every open — and this
// one is expensive: it stats every raw file in the book's knowledge bases.
if (refreshKey === undefined) return;
setDismissed(false);
(async () => {
try {
const data = await bookApi.health(bookId);
if (cancelled) return;
setKbDrift(data.kb_drift);
setLogHealth(data.log_health);
setGeneration(data.generation);
} catch {
// ignore – health is non-critical
}
})();
return () => {
cancelled = true;
};
}, [bookId, refreshKey]);
if (!bookId || dismissed) return null;
const hasDrift = !!kbDrift?.has_drift;
// Filter out repeated failures that are already represented elsewhere
// (kb_health drift logs are surfaced via the kb-drift section above).
const repeated = (logHealth?.repeated_failures || [])
.filter((r) => {
const sig = (r.signature || "").toLowerCase();
if (sig.includes("kb_health")) return false;
if (sig.includes("kb drift")) return false;
return true;
})
.slice(0, 3);
const blockFailures = logHealth?.block_failures || 0;
const hasLogIssues = blockFailures >= 3 || repeated.length > 0;
const sourceQuality = generation?.source_quality;
const hasSourceIssues =
!!sourceQuality &&
(sourceQuality.status !== "ready" || sourceQuality.warnings.length > 0);
/**
* What actually went wrong, as opposed to what has not happened yet.
*
* Deliberately not `retryable_pages`: that counts chapters still *owed*
* work as well, so every book raised a warning triangle the moment it
* started generating — "3 chapters can be retried" on a run with zero
* failures. A queue is the activity panel's business; this banner is for
* breakage. `failed_pages` and `failed_blocks` only ever count real errors,
* and falling back to the block count keeps this honest against a backend
* that predates the split rather than relabelling the queue as failures.
*/
const failedPages = generation?.failed_pages ?? 0;
const failedBlocksFromPages = generation?.failed_blocks || 0;
const hasGenerationIssues =
failedPages > 0 ||
failedBlocksFromPages > 0 ||
Object.keys(generation?.failure_categories || {}).length > 0;
/**
* Why generation failed, said in words.
*
* `unknown` is dropped rather than translated: "unknown: 4" tells the
* reader nothing they can act on, and the per-block error is already shown
* in the chapter itself. Anything the classifier *did* recognise is worth a
* sentence, because each one has a different answer — top up, wait, install
* an extra, or leave that block type out of the book.
*/
const failureCauses = Object.entries(generation?.failure_categories || {})
.filter(([category]) => category !== "unknown")
.map(([category]) => FAILURE_CAUSES[category])
.filter((key): key is string => Boolean(key))
.map((key) => t(key));
if (
!hasDrift &&
!hasLogIssues &&
!explorationFailed &&
!hasSourceIssues &&
!hasGenerationIssues
)
return null;
// Convert technical signatures into a short human label.
const humanizeSignature = (sig: string): string => {
if (!sig) return t("unknown failure");
const stripped = sig.replace(/^[a-z_]+:/i, "").trim();
return stripped.length > 80 ? `${stripped.slice(0, 80)}…` : stripped;
};
const acknowledge = async (force = false) => {
if (!bookId) return;
setBusy(true);
setAcknowledgeError(null);
try {
const result = await bookApi.refreshFingerprints(
bookId,
force,
expectedRevision,
);
onRevisionChange?.(result.book_revision);
setKbDrift({ has_drift: false });
setCanForce(false);
} catch (err) {
setAcknowledgeError(err instanceof Error ? err.message : String(err));
// The refusal is about pages still owed, not a transport failure. Stale
// detection over-marks on purpose, so offer the override rather than
// leaving a banner nothing can clear.
if (!force) setCanForce(true);
} finally {
setBusy(false);
}
};
return (
<div className="mx-6 mt-4 rounded-xl border border-amber-300/60 bg-amber-50 px-4 py-3 text-sm text-amber-900 shadow-sm dark:border-amber-500/30 dark:bg-amber-500/10 dark:text-amber-100">
<div className="flex items-start gap-3">
<AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
<div className="flex-1 space-y-1.5">
{explorationFailed && (
<div>
<strong>
{t("This book was written without reading your sources.")}
</strong>{" "}
<span>
{t(
"Retrieval failed while planning it, so the chapters come from the proposal alone. Rebuilding will try your knowledge bases again.",
)}
</span>
</div>
)}
{hasSourceIssues && (
<div>
<strong>
{t("Some selected sources were not fully covered.")}
</strong>{" "}
<span className="opacity-90">
{sourceQuality?.missing_kbs.length
? t("Missing: {{sources}}.", {
sources: sourceQuality.missing_kbs.join(", "),
})
: null}{" "}
{sourceQuality?.warnings.join(" ")}
</span>
</div>
)}
{hasGenerationIssues && (
<div className="text-xs">
<strong>
{failedPages > 0
? t("{{count}} chapters failed to generate.", {
count: failedPages,
})
: t("{{count}} blocks failed to generate.", {
count: failedBlocksFromPages,
})}
</strong>{" "}
{/* The cause, in the reader's language. This used to print the
classifier's own slugs and tallies — "unknown: 4" beside a
count of 2 — which named nothing the reader could act on and
disagreed with the number next to it. */}
<span className="opacity-90">{failureCauses.join(" · ")}</span>
</div>
)}
{hasDrift && onRecompile && (
<div>
<strong>
{t(
"Your knowledge bases changed since this book was generated.",
)}
</strong>{" "}
<span className="opacity-90">
{kbDrift?.new_kbs?.length ? (
<>
{t("Newly added")}:{" "}
<code className="rounded bg-white/40 px-1 text-[11px] dark:bg-white/10">
{kbDrift.new_kbs.join(", ")}
</code>
.{" "}
</>
) : null}
{kbDrift?.changed_kbs?.length ? (
<>
{t("Updated")}:{" "}
<code className="rounded bg-white/40 px-1 text-[11px] dark:bg-white/10">
{kbDrift.changed_kbs.join(", ")}
</code>
.{" "}
</>
) : null}
{kbDrift?.removed_kbs?.length ? (
<>
{t("Removed")}:{" "}
<code className="rounded bg-white/40 px-1 text-[11px] dark:bg-white/10">
{kbDrift.removed_kbs.join(", ")}
</code>
.{" "}
</>
) : null}
</span>
{kbDrift?.stale_page_ids?.length ? (
<div className="mt-1.5 text-xs opacity-90">
{kbDrift.stale_page_ids.length === 1
? t(
"{{count}} previously-compiled page may be out of date.",
{
count: kbDrift.stale_page_ids.length,
},
)
: t(
"{{count}} previously-compiled pages may be out of date.",
{
count: kbDrift.stale_page_ids.length,
},
)}{" "}
{onRecompile && kbDrift.stale_page_ids[0] && (
<button
onClick={() => onRecompile(kbDrift.stale_page_ids![0])}
className="ml-1 inline-flex items-center gap-1 rounded border border-current px-1.5 py-0.5 text-xs hover:bg-white/40"
>
<RefreshCcw className="h-3 w-3" />{" "}
{t("Recompile first stale page")}
</button>
)}
</div>
) : null}
</div>
)}
{hasLogIssues && (
<div className="flex flex-wrap items-center gap-2 text-xs">
<ScrollText className="h-3.5 w-3.5" />
{blockFailures > 0 && (
<span>
{blockFailures === 1
? t("{{count}} block generation failure recorded.", {
count: blockFailures,
})
: t("{{count}} block generation failures recorded.", {
count: blockFailures,
})}
</span>
)}
{repeated.length > 0 && (
<span>
{repeated.length === 1
? t("Recurring issue")
: t("Recurring issues")}
:{" "}
{repeated
.map(
(r) => `${humanizeSignature(r.signature)} (×${r.count})`,
)
.join("; ")}
.
</span>
)}
</div>
)}
</div>
<div className="flex items-center gap-1">
{hasDrift && (
<Tooltip
label={t(
"Available only after every stale page has been recompiled.",
)}
>
<button
onClick={() => acknowledge()}
disabled={busy}
className="whitespace-nowrap rounded-md border border-current px-2 py-1 text-xs font-medium hover:bg-white/40 disabled:opacity-60"
>
{busy ? "…" : t("Mark as seen")}
</button>
</Tooltip>
)}
{hasDrift && canForce && onRecompile && (
<Tooltip
label={t("Dismiss the warning without recompiling those pages.")}
>
<button
onClick={() => acknowledge(true)}
disabled={busy}
className="whitespace-nowrap rounded-md border border-current px-2 py-1 text-xs font-medium hover:bg-white/40 disabled:opacity-60"
>
{t("Mark as seen anyway")}
</button>
</Tooltip>
)}
<button
onClick={() => setDismissed(true)}
className="rounded p-1 text-amber-700 hover:bg-white/40 dark:text-amber-200"
>
<X className="h-4 w-4" />
</button>
</div>
{acknowledgeError && (
<div className="text-xs font-medium text-red-700 dark:text-red-200">
{acknowledgeError}
</div>
)}
</div>
</div>
);
}