Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

Merge issue fixes into PR synthesis

Bingxi Zhao (Frank)55490af65e31
diff --cc tests/knowledge/test_document_adder_provider.py
index 041753c39,8ab576d4a..e0cb10b57
--- a/tests/knowledge/test_document_adder_provider.py
+++ b/tests/knowledge/test_document_adder_provider.py
@@@ -1,6 -1,6 +1,7 @@@
from __future__ import annotations
import asyncio
++from collections.abc import Callable
import json
from pathlib import Path
@@@ -125,119 -124,48 +126,168 @@@ def test_document_adder_allows_empty_kb
assert adder.accepted_indexing_snapshot.vlm is None
+def test_document_adder_rejects_unready_existing_version(tmp_path: Path) -> None:
+ kb_dir = tmp_path / "kb"
+ kb_dir.mkdir()
+ version_dir = kb_dir / "version-1"
+ version_dir.mkdir()
+ (version_dir / "docstore.json").write_text("{}", encoding="utf-8")
+ (version_dir / "meta.json").write_text(
+ json.dumps({"provider": "llamaindex", "signature": "sig", "version": "version-1"}),
+ encoding="utf-8",
+ )
+
+ with pytest.raises(ValueError, match="reindex required"):
+ DocumentAdder(kb_name="kb", base_dir=str(tmp_path), rag_provider="llamaindex")
+
+
+def test_document_adder_rejects_legacy_rag_storage(tmp_path: Path) -> None:
+ kb_dir = tmp_path / "kb"
+ (kb_dir / "rag_storage").mkdir(parents=True)
+
+ with pytest.raises(ValueError, match="legacy index format"):
+ DocumentAdder(kb_name="kb", base_dir=str(tmp_path), rag_provider="llamaindex")
+
+
+def test_document_adder_allows_empty_llamaindex_kb_to_bootstrap(tmp_path: Path) -> None:
+ """Create-then-upload (no files at create time) must not look uninitialized."""
+ (tmp_path / "Medicine").mkdir()
+
+ adder = DocumentAdder(
+ kb_name="Medicine",
+ base_dir=str(tmp_path),
+ rag_provider="llamaindex",
+ )
+
+ assert adder.rag_provider == "llamaindex"
+ assert adder.raw_dir.is_dir()
+
+
[email protected]("provider", ["graphrag", "pageindex", "pageindex-oss"])
+def test_empty_provider_kb_bootstraps_on_first_upload(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, provider: str
+) -> None:
+ from deeptutor.knowledge.manager import KnowledgeBaseManager
+
+ kb_dir = tmp_path / "empty"
+ (kb_dir / "raw").mkdir(parents=True)
+ manager = KnowledgeBaseManager(base_dir=str(tmp_path))
+ manager.register_knowledge_base("empty")
+ manager.config["knowledge_bases"]["empty"]["rag_provider"] = provider
+ manager._save_config()
+ manager.update_kb_status(name="empty", status="ready")
+ assert manager.get_info("empty")["status"] == "ready"
+
+ doc = tmp_path / "lesson.md"
+ doc.write_text("Lesson", encoding="utf-8")
+ initialized: list[tuple[str, list[str]]] = []
+
+ class FakeRagService:
+ def __init__(self, *, kb_base_dir: str) -> None:
+ assert kb_base_dir == str(tmp_path)
+
- async def initialize(self, *, kb_name: str, file_paths: list[str]) -> bool:
++ async def initialize(
++ self,
++ *,
++ kb_name: str,
++ file_paths: list[str],
++ indexed_file_callback: Callable[[list[str]], None],
++ ) -> bool:
+ initialized.append((kb_name, file_paths))
++ indexed_file_callback(file_paths)
+ return True
+
+ def _resolve_provider(self, _kb_name: str) -> str:
+ return provider
+
+ monkeypatch.setattr("deeptutor.knowledge.add_documents.RAGService", FakeRagService)
+
+ assert asyncio.run(add_documents("empty", [str(doc)], base_dir=str(tmp_path))) == 1
+ assert initialized == [("empty", [str(doc)])]
+ assert KnowledgeBaseManager(base_dir=str(tmp_path)).get_info("empty")["status"] == "ready"
+
+
+def test_document_adder_unready_index_reports_probe_summary(tmp_path: Path) -> None:
+ kb_dir = tmp_path / "kb"
+ (kb_dir / "raw").mkdir(parents=True)
+ version = kb_dir / "version-1"
+ version.mkdir()
+ (version / "meta.json").write_text(
+ '{"provider": "llamaindex", "signature": "sig", "version": "version-1"}',
+ encoding="utf-8",
+ )
+
+ with pytest.raises(ValueError, match="no ready llamaindex index") as caught:
+ DocumentAdder(kb_name="kb", base_dir=str(tmp_path), rag_provider="llamaindex")
+
+ assert "not initialized" not in str(caught.value)
+ assert "docstore.json" in str(caught.value)
+
+
+def test_document_adder_unwritable_kb_is_not_reported_as_uninitialized(
+ tmp_path: Path, monkeypatch
+) -> None:
+ kb_dir = tmp_path / "Medicine"
+ kb_dir.mkdir()
+ monkeypatch.setattr(
+ "deeptutor.knowledge.add_documents.ensure_data_volume_writable",
+ lambda _path: (_ for _ in ()).throw(
+ PermissionError(
+ "Data directory is not writable by the running process "
+ "(euid=1000, egid=1000): /app/data/knowledge_bases/Medicine "
+ "is uid=99 gid=100 mode=0755."
+ )
+ ),
+ )
+
+ with pytest.raises(PermissionError, match="not writable") as caught:
+ DocumentAdder(kb_name="Medicine", base_dir=str(tmp_path), rag_provider="llamaindex")
+
+ assert "not initialized" not in str(caught.value)
+
+
+ def test_empty_kb_bootstrap_hashes_only_files_confirmed_by_index(
+ monkeypatch, tmp_path: Path
+ ) -> None:
+ from deeptutor.knowledge import add_documents as add_module
+
+ raw_dir = tmp_path / "kb" / "raw"
+ raw_dir.mkdir(parents=True)
+ indexed = raw_dir / "indexed.txt"
+ skipped = raw_dir / "skipped.txt"
+ indexed.write_text("searchable", encoding="utf-8")
+ skipped.write_text("", encoding="utf-8")
+
+ class PartialIndexService:
+ def __init__(self, *_args, **_kwargs) -> None:
+ pass
+
+ async def initialize(self, *_args, **kwargs) -> bool:
+ kwargs["indexed_file_callback"]([str(indexed)])
+ return True
+
+ def _resolve_provider(self, _name: str) -> str:
+ return "llamaindex"
+
+ statuses: list[dict] = []
+ manager = type(
+ "Manager", (), {"update_kb_status": lambda _self, **kwargs: statuses.append(kwargs)}
+ )()
+ monkeypatch.setattr(add_module, "RAGService", PartialIndexService)
+
+ count = asyncio.run(
+ add_module._bootstrap_index_from_files(
+ "kb", [str(indexed), str(skipped)], str(tmp_path), manager
+ )
+ )
+
+ metadata = json.loads((tmp_path / "kb" / "metadata.json").read_text(encoding="utf-8"))
+ assert count == 1
+ assert set(metadata["file_hashes"]) == {"indexed.txt"}
+ assert metadata["last_indexed_count"] == 1
+ assert statuses[-1]["progress"]["indexed_count"] == 1
+
+
def test_process_new_documents_returns_failures_without_marking_processed(
monkeypatch, tmp_path: Path
) -> None:
diff --cc web/components/reading/TextUnitView.tsx
index 01394e0d4,1355579d8..ad4ec0ea3
--- a/web/components/reading/TextUnitView.tsx
+++ b/web/components/reading/TextUnitView.tsx
@@@ -49,12 -37,10 +42,13 @@@ import
type ReaderHeading,
} from "@/lib/reading-outline";
import { cleanQuote } from "@/lib/reading-selection";
-import { MarkdownLine } from "@/lib/reading-inline-markdown";
+import {
+ imageMarkerNames,
+ MarkdownLine,
+} from "@/lib/reading-inline-markdown";
import { toRecogitoTextAnnotation } from "@/lib/reading-w3c-annotations";
import type { JumpRequest, SelectionPayload } from "./PdfDocumentView";
+ import { PreferenceButton, ReaderDisplayControls } from "./ReaderDisplayControls";
const COLOR_INK: Record<string, string> = {
yellow: "250 220 90",
diff --cc web/contracts/schema/openapi.json
index b06f2ad93,4c251cec4..cefa70e9d
--- a/web/contracts/schema/openapi.json
+++ b/web/contracts/schema/openapi.json
@@@ -27564,16 -27221,108 +27592,168 @@@
]
}
},
- "/api/memory/doc/{layer}/{key}/lines": {
++ "/api/mastery-paths/topics/{path_id}/review-settings": {
+ "get": {
- "description": "Return the line-numbered, footnote-stripped view of a doc.\n\nUsed by the workbench's \"show line numbers\" toggle so the same line\nindices the audit/dedup LLMs see are visible to the user. Footnote\nblock is omitted because edit ops never reference it directly.",
- "operationId": "get_doc_lines_api_memory_doc__layer___key__lines_get",
++ "operationId": "get_review_settings_api_mastery_paths_topics__path_id__review_settings_get",
+ "parameters": [
+ {
+ "in": "path",
- "name": "layer",
- "required": true,
- "schema": {
- "title": "Layer",
- "type": "string"
- }
- },
- {
- "in": "path",
- "name": "key",
++ "name": "path_id",
+ "required": true,
+ "schema": {
- "title": "Key",
++ "title": "Path Id",
+ "type": "string"
+ }
+ },
+ {
+ "in": "header",
+ "name": "Authorization",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Authorization"
+ }
+ },
+ {
+ "in": "cookie",
+ "name": "dt_token",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Dt Token"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Successful Response"
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ }
+ },
- "summary": "Get Doc Lines",
++ "summary": "Get Review Settings",
+ "tags": [
- "memory"
++ "mastery-path"
+ ]
- }
- },
- "/api/memory/doc/{layer}/{key}/reset": {
- "post": {
- "description": "Wipe the doc + its meta sidecar so the next update starts fresh.\n\nDestructive — the caller has confirmed. After this returns the .md\nfile is gone *and* the ``seen_entity_refs`` set is cleared, so a\nsubsequent ``run_update`` re-ingests every L1 entity instead of\ntreating them as already-seen.\n\nRefuses while a consolidator run is active on this doc; the caller\ncan cancel first.",
- "operationId": "reset_doc_api_memory_doc__layer___key__reset_post",
++ },
++ "put": {
++ "operationId": "update_review_settings_api_mastery_paths_topics__path_id__review_settings_put",
+ "parameters": [
+ {
+ "in": "path",
- "name": "layer",
++ "name": "path_id",
+ "required": true,
+ "schema": {
- "title": "Layer",
++ "title": "Path Id",
+ "type": "string"
+ }
+ },
++ {
++ "in": "header",
++ "name": "Authorization",
++ "required": false,
++ "schema": {
++ "anyOf": [
++ {
++ "type": "string"
++ },
++ {
++ "type": "null"
++ }
++ ],
++ "title": "Authorization"
++ }
++ },
++ {
++ "in": "cookie",
++ "name": "dt_token",
++ "required": false,
++ "schema": {
++ "anyOf": [
++ {
++ "type": "string"
++ },
++ {
++ "type": "null"
++ }
++ ],
++ "title": "Dt Token"
++ }
++ }
++ ],
++ "requestBody": {
++ "content": {
++ "application/json": {
++ "schema": {
++ "$ref": "#/components/schemas/ReviewSettingsRequest"
++ }
++ }
++ },
++ "required": true
++ },
++ "responses": {
++ "200": {
++ "content": {
++ "application/json": {
++ "schema": {}
++ }
++ },
++ "description": "Successful Response"
++ },
++ "422": {
++ "content": {
++ "application/json": {
++ "schema": {
++ "$ref": "#/components/schemas/HTTPValidationError"
++ }
++ }
++ },
++ "description": "Validation Error"
++ }
++ },
++ "summary": "Update Review Settings",
++ "tags": [
++ "mastery-path"
++ ]
++ }
++ },
+ "/api/mastery-paths/topics/{path_id}/sessions": {
+ "get": {
+ "operationId": "list_topic_sessions_api_mastery_paths_topics__path_id__sessions_get",
+ "parameters": [
{
"in": "path",
- "name": "key",
+ "name": "path_id",
"required": true,
"schema": {
- "title": "Key",
+ "title": "Path Id",
"type": "string"
}
},
diff --cc web/tests/epub-display-preferences.spec.tsx
index 000000000,64d5e73b5..cdceac9af
mode 000000,100644..100644
--- a/web/tests/epub-display-preferences.spec.tsx
+++ b/web/tests/epub-display-preferences.spec.tsx
@@@ -1,0 -1,199 +1,200 @@@
+ import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+ import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+ import { initI18n } from "@/i18n/init";
+
+ initI18n("en");
+
+ const fixture = vi.hoisted(() => {
+ const rendition = {
+ display: vi.fn(async (_target?: string) => undefined),
+ currentLocation: vi.fn(() => ({ start: { cfi: "epubcfi(/6/2)" } })),
+ next: vi.fn(async () => undefined),
+ prev: vi.fn(async () => undefined),
+ resize: vi.fn(),
+ spread: vi.fn(),
+ destroy: vi.fn(),
+ on: vi.fn(),
+ off: vi.fn(),
+ annotations: { highlight: vi.fn(), remove: vi.fn() },
+ hooks: { content: { register: vi.fn() } },
+ themes: {
+ registerCss: vi.fn(),
+ select: vi.fn(),
+ fontSize: vi.fn(),
+ override: vi.fn(),
+ },
+ };
+ return {
+ rendition,
+ renderTo: vi.fn(() => rendition),
+ apiFetch: vi.fn(async () => ({
+ ok: true,
+ arrayBuffer: async () => new ArrayBuffer(8),
+ })),
+ };
+ });
+
+ vi.mock("epubjs", () => ({
+ default: () => ({
+ open: async () => undefined,
+ ready: Promise.resolve(),
+ renderTo: fixture.renderTo,
+ spine: { get: () => ({ href: "one.xhtml" }) },
+ destroy: vi.fn(),
+ }),
+ }));
+ vi.mock("@/lib/api", () => ({ apiFetch: fixture.apiFetch }));
+ vi.mock("@/lib/reading-api", () => ({
+ rawMaterialUrl: () => "/api/reading/materials/book/raw",
++ renderMaterialUrl: () => "/api/reading/materials/book/render",
+ getReadingPosition: async () => ({ locator: 1 }),
+ saveReadingPosition: vi.fn(async () => undefined),
+ }));
+
+ import { EpubDocumentView } from "@/components/reading/EpubDocumentView";
+
+ let publisherParagraph: HTMLParagraphElement | null = null;
+ let themeStyle: HTMLStyleElement | null = null;
+
+ beforeEach(() => {
+ fixture.rendition.currentLocation.mockReturnValue({
+ start: { cfi: "epubcfi(/6/2)" },
+ });
+ fixture.rendition.themes.registerCss.mockReset();
+ vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+ x: 0,
+ y: 0,
+ top: 0,
+ left: 0,
+ right: 900,
+ bottom: 600,
+ width: 900,
+ height: 600,
+ toJSON: () => ({}),
+ });
+ });
+
+ afterEach(() => {
+ publisherParagraph?.remove();
+ themeStyle?.remove();
+ publisherParagraph = null;
+ themeStyle = null;
+ });
+
+ it("opens EPUB in single-page mode and keeps the CFI when switching spreads", async () => {
+ render(
+ <EpubDocumentView
+ materialId="book"
+ unitCount={1}
+ unitRefs={[]}
+ annotations={[]}
+ jump={null}
+ onSelection={() => undefined}
+ />,
+ );
+
+ await waitFor(() =>
+ expect(fixture.renderTo).toHaveBeenCalledWith(
+ expect.any(Element),
+ expect.objectContaining({ spread: "none" }),
+ ),
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Switch to two-page spread" }));
+
+ await waitFor(() => expect(fixture.rendition.spread).toHaveBeenCalledWith("auto"));
+ await waitFor(() =>
+ expect(fixture.rendition.resize).toHaveBeenCalledWith(900, 600),
+ );
+ expect(fixture.rendition.display).toHaveBeenCalledWith("epubcfi(/6/2)");
+ expect(JSON.parse(localStorage.getItem("dt.reader.textPreferences") || "{}"))
+ .toMatchObject({ spreadMode: "auto" });
+ });
+
+ it("overrides a publisher's explicit paragraph and span ink and font", async () => {
+ publisherParagraph = document.createElement("p");
+ publisherParagraph.style.cssText =
+ "font-family: monospace; font-size: 11px; color: #000";
+ publisherParagraph.innerHTML =
+ '<span style="font-family: monospace; font-size: 11px; color: #000">Publisher text</span>';
+ document.body.appendChild(publisherParagraph);
+ themeStyle = document.createElement("style");
+ document.head.appendChild(themeStyle);
+ fixture.rendition.themes.registerCss.mockImplementation((_name, css) => {
+ themeStyle!.textContent = css;
+ });
+ localStorage.setItem(
+ "dt.reader.textPreferences",
+ JSON.stringify({ fontSize: 23, serif: false, readerTheme: "night", spreadMode: "auto" }),
+ );
+ render(
+ <EpubDocumentView
+ materialId="book"
+ unitCount={1}
+ unitRefs={[]}
+ annotations={[]}
+ jump={null}
+ onSelection={() => undefined}
+ />,
+ );
+
+ await waitFor(() =>
+ expect(fixture.renderTo).toHaveBeenCalledWith(
+ expect.any(Element),
+ expect.objectContaining({ spread: "auto" }),
+ ),
+ );
+ const publisherSpan = publisherParagraph.querySelector("span")!;
+ await waitFor(() =>
+ expect(getComputedStyle(publisherSpan).color).toBe("rgb(232, 229, 223)"),
+ );
+ expect(getComputedStyle(publisherParagraph).fontFamily).toContain("ui-sans-serif");
+ expect(getComputedStyle(publisherSpan).fontFamily).toContain("ui-sans-serif");
+ expect(getComputedStyle(publisherSpan).fontSize).toBe("23px");
+ expect(fixture.rendition.themes.fontSize).toHaveBeenCalledWith("23px");
+ fireEvent.click(screen.getByRole("button", { name: "Reset reading display" }));
+ await waitFor(() =>
+ expect(getComputedStyle(publisherSpan).color).toBe("rgb(0, 0, 0)"),
+ );
+ expect(JSON.parse(localStorage.getItem("dt.reader.textPreferences") || "{}"))
+ .toMatchObject({ fontSize: 17, readerTheme: "auto", spreadMode: "none" });
+ });
+
+ it("drops a previous book's pending CFI before the next book relayout", async () => {
+ const onSelection = () => undefined;
+ const props = {
+ unitCount: 1,
+ unitRefs: [],
+ annotations: [],
+ jump: null,
+ onSelection,
+ };
+ fixture.rendition.currentLocation.mockReturnValue({
+ start: { cfi: "epubcfi(/6/old-book)" },
+ });
+ const { rerender } = render(
+ <EpubDocumentView materialId="old-book" {...props} />,
+ );
+ await waitFor(() => expect(fixture.renderTo).toHaveBeenCalledTimes(1));
+ fireEvent.click(screen.getByRole("button", { name: "Switch to two-page spread" }));
+ await waitFor(() => expect(fixture.rendition.spread).toHaveBeenCalledWith("auto"));
+ const oldCfiDisplays = fixture.rendition.display.mock.calls.filter(
+ ([cfi]) => cfi === "epubcfi(/6/old-book)",
+ ).length;
+
+ fixture.rendition.currentLocation.mockReturnValue({
+ start: { cfi: "epubcfi(/6/new-book)" },
+ });
+ rerender(<EpubDocumentView materialId="new-book" {...props} />);
+ await waitFor(() => expect(fixture.renderTo).toHaveBeenCalledTimes(2));
+ await waitFor(() =>
+ expect(fixture.rendition.display).toHaveBeenLastCalledWith(
+ "epubcfi(/6/new-book)",
+ ),
+ );
+ expect(
+ fixture.rendition.display.mock.calls.filter(
+ ([cfi]) => cfi === "epubcfi(/6/old-book)",
+ ),
+ ).toHaveLength(oldCfiDisplays);
+ });