DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(parsing): map local MinerU failures to actionable errors (#1612)
cxzyy731736f860a1
diff --git a/deeptutor/services/parsing/engines/mineru/backend.py b/deeptutor/services/parsing/engines/mineru/backend.pyindex e262106c6..fab404ddd 100644--- a/deeptutor/services/parsing/engines/mineru/backend.py+++ b/deeptutor/services/parsing/engines/mineru/backend.py@@ -23,6 +23,7 @@ from .config import (resolve_mineru_config,)from .formats import MINERU_PDF_FORMATS, MINERU_SUPPORTED_FORMATS+from .local import LocalParseReason, parse_document_with_mineru_resultlogger = logging.getLogger(__name__)@@ -30,6 +31,41 @@ logger = logging.getLogger(__name__)# probe reports the same command the parse subprocess will actually use._LOCAL_CLI_COMMANDS = ("mineru", "magic-pdf")+#: One actionable message per local-parse failure reason. The install/cloud+#: hint is deliberately limited to ``CLI_MISSING``: a runtime failure must not+#: be reported as a missing installation (issue #1612, outcome 4).+_LOCAL_FAILURE_MESSAGES: dict[LocalParseReason, str] = {+ LocalParseReason.CLI_MISSING: (+ "Local MinerU parsing failed. Ensure MinerU is installed "+ "(`pip install -U 'mineru[all]>=3.4.5'`) or switch to cloud mode in "+ "Settings → MinerU."+ ),+ LocalParseReason.INPUT_MISSING: (+ "MinerU could not read the source file ({detail}). It may have been "+ "moved or deleted before parsing started."+ ),+ LocalParseReason.UNSUPPORTED_INPUT: (+ "MinerU does not support this input type ({detail}). Supported inputs "+ "are PDF, common raster images, DOCX, PPTX, and XLSX."+ ),+ LocalParseReason.LEGACY_CLI_INPUT: (+ "The legacy magic-pdf CLI only accepts PDF files. Install the current "+ "MinerU CLI (`pip install -U 'mineru[all]>=3.4.5'`) to parse images, "+ "DOCX, PPTX, or XLSX."+ ),+ LocalParseReason.NONZERO_EXIT: (+ "Local MinerU parsing failed at runtime (the CLI is installed). Last "+ "output:\n{detail}\nCheck the source file, local model files and "+ "available memory, or switch to cloud mode in Settings → MinerU."+ ),+ LocalParseReason.NO_ARTIFACTS: (+ "MinerU finished but produced no output files ({detail}). Check that "+ "local models are downloaded and the output directory is writable, or "+ "switch to cloud mode in Settings → MinerU."+ ),+ LocalParseReason.EXCEPTION: "Local MinerU parsing was interrupted: {detail}",+}+def parse_document_to_workdir(source_path: str | Path,@@ -154,7 +190,6 @@ def _parse_local() -> Path:"""Local-CLI branch: delegate to the existing subprocess parser and returnthe deterministic output directory it writes to (``<base>/<stem>``)."""- from .local import parse_document_with_minerufrom .models import model_env_overrides, render_env_overridescli_command = None@@ -163,7 +198,8 @@ def _parse_local(if not probe["found"]:raise MinerUError(f"Configured MinerU CLI path is not an executable file: {probe['path']}. "- "Fix it in Settings → MinerU (or clear it to auto-detect from PATH)."+ "Fix it in Settings → MinerU (or clear it to auto-detect from PATH).",+ code=str(LocalParseReason.CLI_MISSING),)cli_command = probe["path"]else:@@ -179,7 +215,8 @@ def _parse_local(raise MinerUError("The legacy magic-pdf CLI only accepts PDF files. Install the current ""MinerU CLI (`pip install -U 'mineru[all]>=3.4.5'`) to parse images, "- "DOCX, PPTX, or XLSX."+ "DOCX, PPTX, or XLSX.",+ code=str(LocalParseReason.LEGACY_CLI_INPUT),)# A lazy first-parse model download must honor the configured source and@@ -190,18 +227,19 @@ def _parse_local(subprocess_env = {**download_env, **render_env_overrides()}logger.info("Parsing %s via local MinerU CLI (%s)", source_path.name, cli_command or "PATH")- ok = parse_document_with_mineru(+ result = parse_document_with_mineru_result(str(source_path),str(output_base),on_output=on_output,cli_command=cli_command,extra_env=subprocess_env,)- if not ok:+ if not result.ok:+ reason = result.reason or LocalParseReason.EXCEPTIONraise MinerUError(- "Local MinerU parsing failed. Ensure MinerU is installed "- "(`pip install -U 'mineru[all]>=3.4.5'`) or switch to cloud mode in "- "Settings → MinerU."+ _LOCAL_FAILURE_MESSAGES[reason].format(detail=result.detail or "no output"),+ code=str(reason),+ detail=result.detail,)working_dir = output_base / source_path.stemif not working_dir.is_dir():diff --git a/deeptutor/services/parsing/engines/mineru/config.py b/deeptutor/services/parsing/engines/mineru/config.pyindex ac69a2ba3..e68dfd879 100644--- a/deeptutor/services/parsing/engines/mineru/config.py+++ b/deeptutor/services/parsing/engines/mineru/config.py@@ -25,6 +25,15 @@ class MinerUError(RuntimeError):misconfiguration). Carries a user-facing message; the capability layersurfaces it as a stream error."""+ def __init__(self, message: str, *, code: str | None = None, detail: str = "") -> None:+ super().__init__(message)+ #: Machine-readable reason when one is known (``LocalParseReason``+ #: values for local failures); ``None`` when the error is raised+ #: without a classification.+ self.code = code+ #: Bounded diagnostic excerpt backing the message; ``""`` when none.+ self.detail = detail+@dataclass(frozen=True)class MinerUConfig:diff --git a/tests/tools/test_mineru.py b/tests/tools/test_mineru.pyindex e029310ad..d6cf03d54 100644--- a/tests/tools/test_mineru.py+++ b/tests/tools/test_mineru.py@@ -12,6 +12,7 @@ from deeptutor.services.parsing.engines.mineru import backend as mineru_backendfrom deeptutor.services.parsing.engines.mineru import cloud as mineru_cloudfrom deeptutor.services.parsing.engines.mineru import config as mineru_configfrom deeptutor.services.parsing.engines.mineru.config import MinerUConfig, MinerUError+from deeptutor.services.parsing.engines.mineru.local import LocalParseReason, LocalParseResult# ---------------------------------------------------------------------------# Config resolution@@ -68,17 +69,15 @@ def test_resolve_mineru_config_preserves_token_array(monkeypatch: pytest.MonkeyPdef test_parse_pdf_to_workdir_dispatches_local(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:- from deeptutor.services.parsing.engines.mineru import local as pdf_parser-pdf = tmp_path / "exam.pdf"pdf.write_bytes(b"%PDF-1.4")out = tmp_path / "out"- def fake_local(p: str, base: str, **kwargs) -> bool: # noqa: ANN003+ def fake_local(p: str, base: str, **kwargs) -> LocalParseResult: # noqa: ANN003(Path(base) / Path(p).stem).mkdir(parents=True, exist_ok=True)- return True+ return LocalParseResult.success()- monkeypatch.setattr(pdf_parser, "parse_document_with_mineru", fake_local)+ monkeypatch.setattr(mineru_backend, "parse_document_with_mineru_result", fake_local)workdir = mineru_backend.parse_pdf_to_workdir(pdf, out, config=MinerUConfig(mode="local"))assert workdir == out / "exam"@@ -87,11 +86,13 @@ def test_parse_pdf_to_workdir_dispatches_local(def test_parse_pdf_to_workdir_local_failure_raises(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:- from deeptutor.services.parsing.engines.mineru import local as pdf_parser-pdf = tmp_path / "exam.pdf"pdf.write_bytes(b"%PDF-1.4")- monkeypatch.setattr(pdf_parser, "parse_document_with_mineru", lambda *a, **k: False)+ monkeypatch.setattr(+ mineru_backend,+ "parse_document_with_mineru_result",+ lambda *a, **k: LocalParseResult.failure(LocalParseReason.EXCEPTION, "boom"),+ )with pytest.raises(MinerUError):mineru_backend.parse_pdf_to_workdir(@@ -124,19 +125,17 @@ def test_parse_pdf_to_workdir_dispatches_cloud(def test_parse_document_to_workdir_dispatches_office_local(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:- from deeptutor.services.parsing.engines.mineru import local as local_parser-docx = tmp_path / "lesson.docx"docx.write_bytes(b"office")out = tmp_path / "out"seen: list[str] = []- def fake_local(path: str, base: str, **_kwargs) -> bool:+ def fake_local(path: str, base: str, **_kwargs) -> LocalParseResult:seen.append(Path(path).name)(Path(base) / Path(path).stem).mkdir(parents=True, exist_ok=True)- return True+ return LocalParseResult.success()- monkeypatch.setattr(local_parser, "parse_document_with_mineru", fake_local)+ monkeypatch.setattr(mineru_backend, "parse_document_with_mineru_result", fake_local)workdir = mineru_backend.parse_document_to_workdir(docx, out, config=MinerUConfig(mode="local"))@@ -222,8 +221,6 @@ def test_parse_local_rejects_bad_configured_path(def test_parse_local_explains_legacy_cli_limit_for_office(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:- from deeptutor.services.parsing.engines.mineru import local as local_parser-source = tmp_path / "lesson.docx"source.write_bytes(b"office")monkeypatch.setattr(@@ -237,8 +234,8 @@ def test_parse_local_explains_legacy_cli_limit_for_office(},)monkeypatch.setattr(- local_parser,- "parse_document_with_mineru",+ mineru_backend,+ "parse_document_with_mineru_result",lambda *_args, **_kwargs: pytest.fail("legacy CLI must not run"),)