Skip to content

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

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.py
index 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_result
logger = 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 return
the deterministic output directory it writes to (``<base>/<stem>``)."""
- from .local import parse_document_with_mineru
from .models import model_env_overrides, render_env_overrides
cli_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.EXCEPTION
raise 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.stem
if not working_dir.is_dir():
diff --git a/deeptutor/services/parsing/engines/mineru/config.py b/deeptutor/services/parsing/engines/mineru/config.py
index 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 layer
surfaces 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.py
index 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_backend
from deeptutor.services.parsing.engines.mineru import cloud as mineru_cloud
from deeptutor.services.parsing.engines.mineru import config as mineru_config
from 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.MonkeyP
def 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"),
)