parse-anything 0.1.0__py3-none-any.whl

parse_anything/__init__.py

@@ -0,0 +1,54 @@
+"""parse-anything: one interface over mineru, docling, unstructured, markitdown,
+lite (PyMuPDF) and raw OCR (PaddleOCR / Tesseract).
+
+    from parse_anything import parse
+
+    result = parse("report.pdf", engine="mineru")
+    print(result.content)  # markdown
+"""
+
+import logging
+from pathlib import Path
+
+from .factory import engine_names, get_engine
+from .result import ParseResult
+
+__version__ = "0.1.0"
+
+# Library convention: don't configure handlers here, just make sure "no
+# handlers found" warnings don't show up for callers who haven't set up
+# logging themselves. The CLI (cli.py) calls logging.basicConfig() instead.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+logger = logging.getLogger(__name__)
+
+
+def parse(
+    path: str | Path,
+    engine: str = "auto",
+    ocr: str = "paddle",
+    **options,
+) -> ParseResult:
+    """Parses a document and returns its extracted content.
+
+    path:    file to parse (pdf, docx, pptx, xlsx, html, images, ...)
+    engine:  "auto" (default), "mineru"/"miner-u", "docling", "unstructured",
+             "markitdown", "lite"/"liteparse", or "ocr"
+    ocr:     "paddle" (default, PP-OCRv5), "tesseract", or "none"
+    options: engine-specific knobs, e.g. strategy="hi_res" (unstructured),
+             force_ocr=True (mineru), dpi=300 (ocr), lang="ch" (ocr backends)
+    """
+    file_path = Path(path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"No such file: {file_path}")
+
+    logger.info("parsing %s (engine=%s, ocr=%s)", file_path.name, engine, ocr)
+    backend = get_engine(engine, path=file_path)
+    result = backend.parse(file_path, ocr=ocr, **options)
+    logger.info(
+        "finished %s: engine=%s ocr=%s %d chars in %.2fs",
+        file_path.name, result.engine, result.ocr, len(result.content), result.duration_s,
+    )
+    return result
+
+
+__all__ = ["parse", "ParseResult", "get_engine", "engine_names", "__version__"]

parse_anything/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

parse_anything/cli.py

@@ -0,0 +1,104 @@
+import argparse
+import logging
+import sys
+
+from . import __version__, parse
+from .factory import engine_names
+
+logger = logging.getLogger("parse_anything.cli")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="parse-anything",
+        description="Parse any document with your engine of choice and print the extracted content.",
+    )
+    p.add_argument("path", nargs="?", help="File to parse (pdf, docx, pptx, html, png, ...)")
+    p.add_argument(
+        "-e", "--engine", default="auto",
+        help="auto | mineru (miner-u) | docling | unstructured | markitdown | lite (liteparse) | ocr",
+    )
+    p.add_argument(
+        "--ocr", default="paddle", choices=["paddle", "tesseract", "none"],
+        help="OCR backend for scanned pages/images (default: paddle / PP-OCRv5)",
+    )
+    p.add_argument("-o", "--output", help="Write result here (.md/.txt for content, .json for full result)")
+    p.add_argument(
+        "-f", "--format", default="content", choices=["content", "json"],
+        help="stdout format: raw extracted content (default) or the full JSON result",
+    )
+    p.add_argument("--strategy", help="unstructured only: fast | hi_res | ocr_only | auto")
+    p.add_argument("--force-ocr", action="store_true", help="mineru only: OCR every page")
+    p.add_argument("--lang", help="OCR language (paddle: en/ch/..., tesseract: eng/deu/...)")
+    p.add_argument("--dpi", type=int, help="ocr engine only: PDF rasterization DPI (default 200)")
+    p.add_argument("--timeout", type=int, default=900, help="mineru timeout in seconds (default 900 / 15 min)")
+    p.add_argument("--list-engines", action="store_true", help="List engines and exit")
+    p.add_argument(
+        "-v", "--verbose", action="count", default=0,
+        help="raise log verbosity to debug (resolved engine names, per-page timing, ...); "
+             "progress logs (auto-selection, mineru output, OCR page progress) print by default",
+    )
+    p.add_argument("-q", "--quiet", action="store_true", help="suppress progress logs, print only errors")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def _configure_logging(verbose: int, quiet: bool) -> None:
+    if quiet:
+        level = logging.ERROR
+    elif verbose >= 1:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+        stream=sys.stderr,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    _configure_logging(args.verbose, args.quiet)
+
+    if args.list_engines:
+        print("\n".join(engine_names()))
+        return 0
+    if not args.path:
+        build_parser().print_help()
+        return 2
+
+    options = {}
+    if args.strategy:
+        options["strategy"] = args.strategy
+    if args.force_ocr:
+        options["force_ocr"] = True
+    if args.lang:
+        options["lang"] = args.lang
+    if args.dpi:
+        options["dpi"] = args.dpi
+    if args.timeout != 900:
+        options["timeout"] = args.timeout
+
+    try:
+        result = parse(args.path, engine=args.engine, ocr=args.ocr, **options)
+    except (FileNotFoundError, ValueError, ImportError, RuntimeError) as exc:
+        logger.error(str(exc))
+        return 1
+
+    if args.output:
+        saved = result.save(args.output)
+        if not args.quiet:
+            print(
+                f"[{result.engine}] {result.path} -> {saved} "
+                f"({len(result.content)} chars, {result.duration_s:.1f}s)",
+                file=sys.stderr,
+            )
+    else:
+        print(result.to_json() if args.format == "json" else result.content)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

parse_anything/engines/__init__.py

@@ -0,0 +1,3 @@
+from .base import ParserEngine
+
+__all__ = ["ParserEngine"]

parse_anything/engines/base.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from ..result import ParseResult
+
+
+class ParserEngine(ABC):
+    """Common interface every parsing backend implements.
+
+    Deliberately minimal — file path in, ParseResult out — so callers can swap
+    engines (mineru, docling, unstructured, markitdown, lite) without changing
+    any downstream code.
+    """
+
+    name: str
+
+    #: pip extra that pulls in this engine's dependencies, used in error messages.
+    extra: str
+
+    @abstractmethod
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        """Extracts content from the file.
+
+        ocr: "paddle" (default), "tesseract", or "none". Engines that bundle
+        their own OCR pipeline (mineru) or don't support choosing (markitdown)
+        document how they interpret this.
+        """
+        raise NotImplementedError
+
+    def _missing_dep(self, package: str) -> ImportError:
+        return ImportError(
+            f"Engine '{self.name}' needs '{package}'. "
+            f"Install it with: pip install parse-anything[{self.extra}]"
+        )

parse_anything/engines/docling_engine.py

@@ -0,0 +1,99 @@
+import logging
+from pathlib import Path
+
+from ..result import ParseResult, Timer
+from .base import ParserEngine
+
+logger = logging.getLogger(__name__)
+
+
+class DoclingEngine(ParserEngine):
+    """Docling (IBM) — high-fidelity structure extraction (reading order,
+    tables, headings) for PDFs and office formats, exported as markdown.
+
+    OCR backends docling supports natively: easyocr (its default), tesseract,
+    rapidocr. It has no PaddleOCR plugin, so ocr="paddle" falls back to
+    docling's default with a note in metadata — pick engine="mineru" (whose
+    pipeline is built on PaddleOCR models) when paddle-quality OCR matters.
+    """
+
+    name = "docling"
+    extra = "docling"
+
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        try:
+            from docling.document_converter import DocumentConverter
+        except ImportError:
+            raise self._missing_dep("docling") from None
+
+        converter, ocr_used, note = self._build_converter(ocr)
+        if note:
+            logger.warning(note)
+        logger.info("running docling on %s (ocr=%s)", path.name, ocr_used)
+
+        with Timer() as t:
+            result = converter.convert(str(path))
+            content = result.document.export_to_markdown()
+
+        metadata = {"pages": len(getattr(result.document, "pages", []) or [])}
+        if note:
+            metadata["ocr_note"] = note
+        logger.info("docling finished %s: %d pages, %d chars", path.name, metadata["pages"], len(content))
+        return ParseResult(
+            path=str(path),
+            engine=self.name,
+            content=content,
+            format="markdown",
+            ocr=ocr_used,
+            metadata=metadata,
+            duration_s=t.elapsed,
+        )
+
+    def _build_converter(self, ocr: str):
+        from docling.document_converter import DocumentConverter
+
+        if ocr == "tesseract":
+            try:
+                from docling.datamodel.base_models import InputFormat
+                from docling.datamodel.pipeline_options import (
+                    PdfPipelineOptions,
+                    TesseractOcrOptions,
+                )
+                from docling.document_converter import PdfFormatOption
+
+                opts = PdfPipelineOptions()
+                opts.do_ocr = True
+                opts.ocr_options = TesseractOcrOptions()
+                converter = DocumentConverter(
+                    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)}
+                )
+                return converter, "tesseract", None
+            except ImportError:
+                return (
+                    DocumentConverter(),
+                    "easyocr (docling default)",
+                    "tesseract requested but docling's tesseract option is unavailable",
+                )
+
+        if ocr == "none":
+            try:
+                from docling.datamodel.base_models import InputFormat
+                from docling.datamodel.pipeline_options import PdfPipelineOptions
+                from docling.document_converter import PdfFormatOption
+
+                opts = PdfPipelineOptions()
+                opts.do_ocr = False
+                converter = DocumentConverter(
+                    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)}
+                )
+                return converter, None, None
+            except ImportError:
+                return DocumentConverter(), None, None
+
+        note = (
+            "docling has no PaddleOCR backend; used its default (easyocr). "
+            "Use engine='mineru' for a PaddleOCR-based pipeline."
+            if ocr in ("paddle", "paddleocr")
+            else None
+        )
+        return DocumentConverter(), "easyocr (docling default)", note

parse_anything/engines/lite_engine.py

@@ -0,0 +1,67 @@
+import logging
+from pathlib import Path
+
+from ..ocr import IMAGE_SUFFIXES, get_ocr
+from ..result import ParseResult, Timer
+from .base import ParserEngine
+
+logger = logging.getLogger(__name__)
+
+
+class LiteEngine(ParserEngine):
+    """liteparse — the lightweight, fast path. PyMuPDF-based markdown for PDFs
+    (no ML models, near-instant), direct OCR for images, plain text extraction
+    for everything else PyMuPDF can open (epub, xps, txt).
+
+    Best when documents have a real text layer and speed matters more than
+    layout reconstruction.
+    """
+
+    name = "lite"
+    extra = "lite"
+
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        suffix = path.suffix.lower()
+
+        if suffix in IMAGE_SUFFIXES:
+            if ocr == "none":
+                raise ValueError(f"'{path.name}' is an image; lite needs ocr='paddle' or 'tesseract' for images.")
+            logger.info("lite: routing image %s to OCR backend '%s'", path.name, ocr)
+            backend = get_ocr(ocr, lang=options.get("lang"))
+            with Timer() as t:
+                text, meta = backend.parse_file(path)
+            return ParseResult(
+                path=str(path), engine=self.name, content=text, format="text",
+                ocr=backend.name, metadata=meta, duration_s=t.elapsed,
+            )
+
+        if suffix == ".pdf":
+            try:
+                import pymupdf4llm
+            except ImportError:
+                raise self._missing_dep("pymupdf4llm") from None
+            logger.info("lite: extracting text layer from %s via pymupdf4llm", path.name)
+            with Timer() as t:
+                content = pymupdf4llm.to_markdown(str(path))
+            logger.info("lite: finished %s, %d chars in %.2fs", path.name, len(content), t.elapsed)
+            return ParseResult(
+                path=str(path), engine=self.name, content=content, format="markdown",
+                ocr=None, metadata={}, duration_s=t.elapsed,
+            )
+
+        # Anything else PyMuPDF understands (epub, xps, cbz, txt...)
+        try:
+            import pymupdf as fitz
+        except ImportError:
+            try:
+                import fitz
+            except ImportError:
+                raise self._missing_dep("pymupdf") from None
+        with Timer() as t:
+            with fitz.open(str(path)) as doc:
+                page_count = doc.page_count
+                content = "\n\n".join(page.get_text() for page in doc)
+        return ParseResult(
+            path=str(path), engine=self.name, content=content, format="text",
+            ocr=None, metadata={"pages": page_count}, duration_s=t.elapsed,
+        )

parse_anything/engines/markitdown_engine.py

@@ -0,0 +1,41 @@
+import logging
+from pathlib import Path
+
+from ..result import ParseResult, Timer
+from .base import ParserEngine
+
+logger = logging.getLogger(__name__)
+
+
+class MarkItDownEngine(ParserEngine):
+    """MarkItDown (Microsoft) — fast conversion of office/web formats
+    (docx, pptx, xlsx, html, csv, json, zip, ...) straight to markdown.
+
+    It performs no OCR of its own, so the `ocr` parameter is ignored; route
+    scanned PDFs and images to mineru, docling, unstructured, or engine="ocr".
+    """
+
+    name = "markitdown"
+    extra = "markitdown"
+
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        try:
+            from markitdown import MarkItDown
+        except ImportError:
+            raise self._missing_dep("markitdown") from None
+
+        logger.info("running markitdown on %s", path.name)
+        with Timer() as t:
+            converter = MarkItDown(enable_plugins=options.get("enable_plugins", False))
+            result = converter.convert(str(path))
+        logger.info("markitdown finished %s: %d chars", path.name, len(result.text_content))
+
+        return ParseResult(
+            path=str(path),
+            engine=self.name,
+            content=result.text_content,
+            format="markdown",
+            ocr=None,
+            metadata={"title": getattr(result, "title", None)},
+            duration_s=t.elapsed,
+        )

parse_anything/engines/mineru_engine.py

@@ -0,0 +1,121 @@
+import logging
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+from ..result import ParseResult, Timer
+from .base import ParserEngine
+
+logger = logging.getLogger(__name__)
+
+
+class MinerUEngine(ParserEngine):
+    """MinerU — layout-aware PDF-to-markdown, strongest choice for scanned or
+    complex scientific PDFs (formulas, multi-column, tables).
+
+    Driven through the `mineru` CLI because its Python API churns between
+    releases while the CLI contract stays stable. MinerU ships its own OCR
+    pipeline built on PaddleOCR models, so the `ocr` parameter only controls
+    *whether* OCR runs, not which backend does it:
+      ocr="none"        -> text-layer extraction only  (mineru -m txt)
+      anything else     -> auto-detect per page        (mineru -m auto)
+      options force_ocr -> OCR every page              (mineru -m ocr)
+    """
+
+    name = "mineru"
+    extra = "mineru"
+
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        exe = shutil.which("mineru")
+        if exe is None:
+            raise self._missing_dep("mineru (CLI not found on PATH)")
+
+        if options.get("force_ocr"):
+            method = "ocr"
+        elif ocr == "none":
+            method = "txt"
+        else:
+            method = "auto"
+
+        timeout = options.get("timeout", 900)
+
+        with Timer() as t, tempfile.TemporaryDirectory(prefix="parse_anything_mineru_") as tmp:
+            cmd = [exe, "-p", str(path), "-o", tmp, "-m", method]
+            if options.get("lang"):
+                cmd += ["--lang", options["lang"]]
+            logger.info("running mineru (method=%s, timeout=%ss): %s", method, timeout, " ".join(cmd))
+
+            self._run_with_live_logs(cmd, timeout=timeout, path=path)
+
+            # Output lands at <tmp>/<stem>/<method>/<stem>.md; rglob keeps us
+            # robust to layout changes across MinerU versions.
+            md_files = sorted(Path(tmp).rglob("*.md"), key=lambda p: p.stat().st_size)
+            if not md_files:
+                raise RuntimeError(f"mineru produced no markdown output for {path}")
+            content = md_files[-1].read_text(encoding="utf-8")
+            logger.info("mineru wrote %s (%d chars)", md_files[-1].name, len(content))
+
+        return ParseResult(
+            path=str(path),
+            engine=self.name,
+            content=content,
+            format="markdown",
+            ocr=None if method == "txt" else "mineru-builtin (PaddleOCR models)",
+            metadata={"method": method},
+            duration_s=t.elapsed,
+        )
+
+    @staticmethod
+    def _run_with_live_logs(cmd: list[str], timeout: int, path: Path) -> None:
+        """Runs mineru streaming its stdout/stderr to the logger as it happens.
+
+        mineru can take minutes on large or scanned PDFs with no output at
+        all if captured all-at-once, which made a hung/slow run indistinguishable
+        from a silently-progressing one. Streaming line-by-line plus a periodic
+        "still running" heartbeat fixes that.
+        """
+        proc = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1
+        )
+        tail: list[str] = []
+
+        def _pump():
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                line = line.rstrip()
+                if line:
+                    tail.append(line)
+                    del tail[:-40]
+                    logger.info("[mineru] %s", line)
+
+        pump = threading.Thread(target=_pump, daemon=True)
+        pump.start()
+
+        start = time.monotonic()
+        last_heartbeat = start
+        while True:
+            try:
+                returncode = proc.wait(timeout=5)
+                break
+            except subprocess.TimeoutExpired:
+                elapsed = time.monotonic() - start
+                if elapsed > timeout:
+                    proc.kill()
+                    proc.wait()
+                    raise RuntimeError(
+                        f"mineru timed out after {timeout}s parsing {path.name}. "
+                        "Pass a larger timeout=... (or --timeout on the CLI), "
+                        "or try engine='docling'/'lite' instead."
+                    ) from None
+                if time.monotonic() - last_heartbeat > 30:
+                    logger.info("[mineru] still running... %.0fs elapsed", elapsed)
+                    last_heartbeat = time.monotonic()
+
+        pump.join(timeout=5)
+        if returncode != 0:
+            raise RuntimeError(
+                f"mineru failed (exit {returncode}):\n" + "\n".join(tail)
+            )

parse_anything/engines/ocr_engine.py

@@ -0,0 +1,34 @@
+import logging
+from pathlib import Path
+
+from ..ocr import get_ocr
+from ..result import ParseResult, Timer
+from .base import ParserEngine
+
+logger = logging.getLogger(__name__)
+
+
+class OCROnlyEngine(ParserEngine):
+    """Pure OCR: no layout analysis, just recognized text from images or
+    rasterized PDF pages — via PaddleOCR (default) or Tesseract."""
+
+    name = "ocr"
+    extra = "ocr"
+
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        backend_name = "paddle" if ocr in (None, "", "none") else ocr
+        dpi = options.get("dpi", 200)
+        logger.info("running OCR on %s with backend '%s' (dpi=%d)", path.name, backend_name, dpi)
+        backend = get_ocr(backend_name, lang=options.get("lang"))
+        with Timer() as t:
+            text, meta = backend.parse_file(path, dpi=dpi)
+        logger.info("OCR finished %s: %s pages, %d chars in %.2fs", path.name, meta.get("pages"), len(text), t.elapsed)
+        return ParseResult(
+            path=str(path),
+            engine=self.name,
+            content=text,
+            format="text",
+            ocr=backend.name,
+            metadata=meta,
+            duration_s=t.elapsed,
+        )

parse_anything/engines/unstructured_engine.py

@@ -0,0 +1,81 @@
+import logging
+import os
+from pathlib import Path
+
+from ..result import ParseResult, Timer
+from .base import ParserEngine
+
+logger = logging.getLogger(__name__)
+
+# unstructured selects its OCR agent via this env var at partition time.
+_OCR_AGENTS = {
+    "paddle": "unstructured.partition.utils.ocr_models.paddle_ocr.OCRAgentPaddle",
+    "tesseract": "unstructured.partition.utils.ocr_models.tesseract_ocr.OCRAgentTesseract",
+}
+
+
+class UnstructuredEngine(ParserEngine):
+    """unstructured.io — broadest format coverage (emails, html, office, pdf...),
+    returns typed elements which we render to markdown.
+
+    ocr="paddle" needs the `unstructured.paddleocr` package; ocr="tesseract"
+    uses unstructured's default tesseract agent.
+    """
+
+    name = "unstructured"
+    extra = "unstructured"
+
+    def parse(self, path: Path, ocr: str = "paddle", **options) -> ParseResult:
+        try:
+            from unstructured.partition.auto import partition
+        except ImportError:
+            raise self._missing_dep("unstructured") from None
+
+        strategy = options.get("strategy", "auto")
+        if ocr == "none":
+            strategy = options.get("strategy", "fast")
+
+        previous_agent = os.environ.get("OCR_AGENT")
+        if ocr in _OCR_AGENTS:
+            os.environ["OCR_AGENT"] = _OCR_AGENTS[ocr]
+        logger.info("running unstructured on %s (strategy=%s, ocr=%s)", path.name, strategy, ocr)
+        try:
+            with Timer() as t:
+                elements = partition(filename=str(path), strategy=strategy)
+        finally:
+            if ocr in _OCR_AGENTS:
+                if previous_agent is None:
+                    os.environ.pop("OCR_AGENT", None)
+                else:
+                    os.environ["OCR_AGENT"] = previous_agent
+
+        logger.info("unstructured finished %s: %d elements", path.name, len(elements))
+        content = self._to_markdown(elements)
+        return ParseResult(
+            path=str(path),
+            engine=self.name,
+            content=content,
+            format="markdown",
+            ocr=ocr if ocr in _OCR_AGENTS else None,
+            metadata={"strategy": strategy, "elements": len(elements)},
+            duration_s=t.elapsed,
+        )
+
+    @staticmethod
+    def _to_markdown(elements) -> str:
+        lines: list[str] = []
+        for el in elements:
+            category = getattr(el, "category", "")
+            text = str(el).strip()
+            if not text:
+                continue
+            if category == "Title":
+                lines.append(f"## {text}")
+            elif category == "ListItem":
+                lines.append(f"- {text}")
+            elif category == "Table":
+                html = getattr(getattr(el, "metadata", None), "text_as_html", None)
+                lines.append(html if html else text)
+            else:
+                lines.append(text)
+        return "\n\n".join(lines)

parse_anything/factory.py

@@ -0,0 +1,117 @@
+import importlib.util
+import logging
+import shutil
+from pathlib import Path
+
+from .engines.base import ParserEngine
+from .ocr.base import IMAGE_SUFFIXES
+
+logger = logging.getLogger(__name__)
+
+# Canonical engine name -> (module, class). Imported lazily so that having one
+# backend installed is enough to use it — the others can stay uninstalled.
+_ENGINES: dict[str, tuple[str, str]] = {
+    "mineru": ("parse_anything.engines.mineru_engine", "MinerUEngine"),
+    "docling": ("parse_anything.engines.docling_engine", "DoclingEngine"),
+    "unstructured": ("parse_anything.engines.unstructured_engine", "UnstructuredEngine"),
+    "markitdown": ("parse_anything.engines.markitdown_engine", "MarkItDownEngine"),
+    "lite": ("parse_anything.engines.lite_engine", "LiteEngine"),
+    "ocr": ("parse_anything.engines.ocr_engine", "OCROnlyEngine"),
+}
+
+_ALIASES = {
+    "miner-u": "mineru",
+    "miner_u": "mineru",
+    "magic-pdf": "mineru",
+    "unstructured.io": "unstructured",
+    "markitdown": "markitdown",
+    "mark-it-down": "markitdown",
+    "liteparse": "lite",
+    "lite-parse": "lite",
+    "pymupdf": "lite",
+}
+
+# Python package whose presence means the engine is usable (for auto mode).
+_AVAILABILITY_PROBE = {
+    "mineru": "mineru",
+    "docling": "docling",
+    "unstructured": "unstructured",
+    "markitdown": "markitdown",
+    "lite": "pymupdf",
+}
+
+OFFICE_SUFFIXES = {".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls"}
+MARKUP_SUFFIXES = {".html", ".htm", ".csv", ".json", ".xml", ".epub", ".md", ".txt", ".zip", ".msg", ".eml"}
+
+
+def engine_names() -> list[str]:
+    return list(_ENGINES)
+
+
+def resolve_engine_name(name: str) -> str:
+    key = name.strip().lower()
+    key = _ALIASES.get(key, key)
+    if key not in _ENGINES and key != "auto":
+        supported = ", ".join(["auto", *_ENGINES])
+        raise ValueError(f"Unknown engine '{name}'. Supported: {supported}")
+    return key
+
+
+def get_engine(name: str, path: Path | None = None) -> ParserEngine:
+    key = resolve_engine_name(name)
+    if key == "auto":
+        if path is None:
+            raise ValueError("engine='auto' needs a file path to pick from")
+        key = _pick_engine_for(path)
+    else:
+        logger.debug("resolved engine '%s' -> '%s'", name, key)
+
+    module_name, class_name = _ENGINES[key]
+    import importlib
+
+    module = importlib.import_module(module_name)
+    logger.debug("loaded engine class %s from %s", class_name, module_name)
+    return getattr(module, class_name)()
+
+
+def _is_available(engine: str) -> bool:
+    if engine == "mineru":
+        # mineru is driven via its CLI; either the package or binary suffices.
+        return shutil.which("mineru") is not None or importlib.util.find_spec("mineru") is not None
+    probe = _AVAILABILITY_PROBE.get(engine)
+    return probe is not None and importlib.util.find_spec(probe) is not None
+
+
+def _ocr_available() -> bool:
+    return (
+        importlib.util.find_spec("paddleocr") is not None
+        or importlib.util.find_spec("pytesseract") is not None
+    )
+
+
+def _pick_engine_for(path: Path) -> str:
+    """Best installed engine for the file type; preference orders reflect each
+    engine's strengths (mineru on PDFs, docling on office docs, etc.)."""
+    suffix = path.suffix.lower()
+
+    if suffix in IMAGE_SUFFIXES and _ocr_available():
+        return "ocr"
+    if suffix == ".pdf":
+        order = ["mineru", "docling", "unstructured", "lite"]
+    elif suffix in OFFICE_SUFFIXES:
+        order = ["docling", "markitdown", "unstructured"]
+    elif suffix in MARKUP_SUFFIXES:
+        order = ["markitdown", "unstructured", "lite"]
+    else:
+        order = ["unstructured", "markitdown", "docling", "lite"]
+
+    logger.debug("auto-selection order for '%s' (%s): %s", path.name, suffix, order)
+    for engine in order:
+        if _is_available(engine):
+            logger.info("auto-selected engine '%s' for %s", engine, path.name)
+            return engine
+
+    raise ImportError(
+        f"No parsing engine installed that can handle '{path.name}'. "
+        f"Tried: {', '.join(order)}. Install one, e.g.: pip install parse-anything[docling]"
+    )

parse_anything/ocr/__init__.py

@@ -0,0 +1,18 @@
+from .base import IMAGE_SUFFIXES, OCREngine
+
+
+def get_ocr(name: str = "paddle", lang: str | None = None) -> OCREngine:
+    """Returns the requested OCR backend: 'paddle' (default) or 'tesseract'."""
+    key = (name or "paddle").lower()
+    if key in ("paddle", "paddleocr", "pp-ocr", "ppocr"):
+        from .paddle_engine import PaddleOCREngine
+
+        return PaddleOCREngine(lang=lang or "en")
+    if key in ("tesseract", "pytesseract"):
+        from .tesseract_engine import TesseractEngine
+
+        return TesseractEngine(lang=lang or "eng")
+    raise ValueError(f"Unknown OCR backend '{name}'. Supported: paddle, tesseract")
+
+
+__all__ = ["OCREngine", "IMAGE_SUFFIXES", "get_ocr"]

parse_anything/ocr/base.py

@@ -0,0 +1,59 @@
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp", ".webp", ".gif"}
+
+
+class OCREngine(ABC):
+    """Text recognition backend: image (or scanned PDF) in, plain text out."""
+
+    name: str
+
+    @abstractmethod
+    def image_to_text(self, image_path: Path) -> str:
+        raise NotImplementedError
+
+    def parse_file(self, path: Path, dpi: int = 200) -> tuple[str, dict]:
+        """OCRs an image directly, or renders each PDF page to an image first.
+
+        Returns (text, metadata).
+        """
+        if path.suffix.lower() == ".pdf":
+            pages = []
+            logger.info("[%s] rasterizing %s at %d dpi", self.name, path.name, dpi)
+            for i, image_path in enumerate(render_pdf_pages(path, dpi=dpi), start=1):
+                logger.info("[%s] OCR page %d of %s", self.name, i, path.name)
+                pages.append(self.image_to_text(image_path))
+            text = "\n\n".join(pages)
+            logger.info("[%s] finished %s: %d pages", self.name, path.name, len(pages))
+            return text, {"pages": len(pages), "dpi": dpi}
+        logger.info("[%s] OCR %s", self.name, path.name)
+        return self.image_to_text(path), {"pages": 1}
+
+
+def render_pdf_pages(path: Path, dpi: int = 200):
+    """Yields temporary PNG paths, one per PDF page, for OCR backends that want files."""
+    import tempfile
+
+    try:
+        import pymupdf  # noqa: F401  (>= 1.24 exposes the new name)
+        import pymupdf as fitz
+    except ImportError:
+        try:
+            import fitz  # older PyMuPDF releases
+        except ImportError as exc:
+            raise ImportError(
+                "OCR on PDFs needs PyMuPDF to rasterize pages. "
+                "Install it with: pip install parse-anything[ocr]"
+            ) from exc
+
+    tmpdir = Path(tempfile.mkdtemp(prefix="parse_anything_ocr_"))
+    with fitz.open(path) as doc:
+        for i, page in enumerate(doc, start=1):
+            pix = page.get_pixmap(dpi=dpi)
+            out = tmpdir / f"page_{i:04d}.png"
+            pix.save(out)
+            yield out

parse_anything/ocr/paddle_engine.py

@@ -0,0 +1,66 @@
+import logging
+from pathlib import Path
+
+from .base import OCREngine
+
+logger = logging.getLogger(__name__)
+
+
+class PaddleOCREngine(OCREngine):
+    """PaddleOCR (PP-OCRv5) — the default OCR backend.
+
+    Chosen as default because PP-OCRv5 currently posts the strongest open-source
+    accuracy benchmarks across printed, handwritten, and multilingual text.
+    Works with both the PaddleOCR 3.x `predict` API and the legacy 2.x `ocr` API.
+    """
+
+    name = "paddle"
+
+    def __init__(self, lang: str = "en"):
+        try:
+            from paddleocr import PaddleOCR
+        except ImportError as exc:
+            raise ImportError(
+                "PaddleOCR is not installed. Install it with: pip install parse-anything[paddle]"
+            ) from exc
+
+        logger.info("loading PaddleOCR (PP-OCRv5, lang=%s) — first run downloads model weights", lang)
+        try:
+            # 3.x: turn off document-rotation/unwarp preprocessing — we feed
+            # clean rasterized pages, and these extra models slow cold start.
+            # enable_mkldnn=False: PaddleX's default oneDNN + new-IR (PIR) CPU
+            # path can't convert some double-array attributes used by the
+            # PP-OCRv5 detection model, raising "ConvertPirAttribute2Runtime
+            # Attribute not support" — falling back to the plain Paddle
+            # executor avoids that unimplemented path.
+            self._ocr = PaddleOCR(
+                lang=lang,
+                use_doc_orientation_classify=False,
+                use_doc_unwarping=False,
+                use_textline_orientation=False,
+                enable_mkldnn=False,
+            )
+        except TypeError:
+            self._ocr = PaddleOCR(lang=lang)
+        logger.info("PaddleOCR ready")
+
+    def image_to_text(self, image_path: Path) -> str:
+        if hasattr(self._ocr, "predict"):  # PaddleOCR >= 3.0
+            lines: list[str] = []
+            for res in self._ocr.predict(input=str(image_path)):
+                texts = None
+                try:
+                    texts = res["rec_texts"]
+                except (TypeError, KeyError, IndexError):
+                    texts = getattr(res, "rec_texts", None)
+                if texts:
+                    lines.extend(texts)
+            return "\n".join(lines)
+
+        # PaddleOCR 2.x: list of [box, (text, confidence)] per page
+        lines = []
+        for page in self._ocr.ocr(str(image_path)) or []:
+            for entry in page or []:
+                if entry and len(entry) > 1:
+                    lines.append(entry[1][0])
+        return "\n".join(lines)

parse_anything/ocr/tesseract_engine.py

@@ -0,0 +1,47 @@
+import logging
+import shutil
+from pathlib import Path
+
+from .base import OCREngine
+
+logger = logging.getLogger(__name__)
+
+
+class TesseractEngine(OCREngine):
+    """Tesseract via pytesseract — ubiquitous, CPU-light fallback OCR.
+
+    Needs the tesseract binary on PATH (Windows: UB-Mannheim installer or
+    `choco install tesseract`; Linux: `apt install tesseract-ocr`).
+    """
+
+    name = "tesseract"
+
+    def __init__(self, lang: str = "eng"):
+        try:
+            import pytesseract
+            from PIL import Image  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "pytesseract/Pillow are not installed. "
+                "Install them with: pip install parse-anything[tesseract]"
+            ) from exc
+
+        self._pytesseract = pytesseract
+        self._lang = lang
+
+        if shutil.which("tesseract") is None and not getattr(
+            pytesseract.pytesseract, "tesseract_cmd", None
+        ):
+            raise RuntimeError(
+                "The tesseract binary was not found on PATH. Install it "
+                "(Windows: https://github.com/UB-Mannheim/tesseract/wiki, "
+                "or `choco install tesseract`) or set "
+                "pytesseract.pytesseract.tesseract_cmd to its location."
+            )
+        logger.info("Tesseract OCR ready (lang=%s)", lang)
+
+    def image_to_text(self, image_path: Path) -> str:
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            return self._pytesseract.image_to_string(img, lang=self._lang).strip()

parse_anything/result.py

@@ -0,0 +1,60 @@
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ParseResult:
+    """What every engine returns: extracted content plus enough metadata to trace it.
+
+    `content` is markdown whenever the engine can produce it (headings, tables),
+    plain text otherwise — `format` says which one you got.
+    """
+
+    path: str
+    engine: str
+    content: str
+    format: str = "markdown"  # "markdown" | "text"
+    ocr: str | None = None  # OCR backend used, if any ("paddle", "tesseract")
+    metadata: dict = field(default_factory=dict)
+    duration_s: float = 0.0
+
+    @property
+    def text(self) -> str:
+        return self.content
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "engine": self.engine,
+            "format": self.format,
+            "ocr": self.ocr,
+            "duration_s": round(self.duration_s, 3),
+            "metadata": self.metadata,
+            "content": self.content,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def save(self, out_path: str | Path) -> Path:
+        out = Path(out_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if out.suffix == ".json":
+            out.write_text(self.to_json(), encoding="utf-8")
+        else:
+            out.write_text(self.content, encoding="utf-8")
+        return out
+
+
+class Timer:
+    """Tiny context manager so engines can fill ParseResult.duration_s uniformly."""
+
+    def __enter__(self):
+        self.start = time.perf_counter()
+        return self
+
+    def __exit__(self, *exc):
+        self.elapsed = time.perf_counter() - self.start
+        return False

parse_anything-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: parse-anything
+Version: 0.1.0
+Summary: One interface to parse any document: pick an engine (mineru, docling, unstructured, markitdown, lite) and get clean markdown out.
+Author: Yugesh
+License: MIT
+Project-URL: Homepage, https://github.com/yugeshsr13/parse-anything
+Project-URL: Repository, https://github.com/yugeshsr13/parse-anything
+Project-URL: Issues, https://github.com/yugeshsr13/parse-anything/issues
+Keywords: pdf,parsing,ocr,docling,mineru,unstructured,markitdown,paddleocr,tesseract
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: lite
+Requires-Dist: pymupdf4llm>=0.0.17; extra == "lite"
+Provides-Extra: docling
+Requires-Dist: docling>=2.15; extra == "docling"
+Provides-Extra: unstructured
+Requires-Dist: unstructured[all-docs]>=0.16; extra == "unstructured"
+Provides-Extra: markitdown
+Requires-Dist: markitdown[all]>=0.1.1; extra == "markitdown"
+Provides-Extra: mineru
+Requires-Dist: mineru[core]>=2.0; extra == "mineru"
+Provides-Extra: tesseract
+Requires-Dist: pytesseract>=0.3.10; extra == "tesseract"
+Requires-Dist: Pillow>=10.0; extra == "tesseract"
+Requires-Dist: pymupdf>=1.24; extra == "tesseract"
+Provides-Extra: paddle
+Requires-Dist: paddleocr>=3.0; extra == "paddle"
+Requires-Dist: paddlepaddle>=3.0; extra == "paddle"
+Requires-Dist: pymupdf>=1.24; extra == "paddle"
+Provides-Extra: ocr
+Requires-Dist: parse-anything[paddle,tesseract]; extra == "ocr"
+Provides-Extra: all
+Requires-Dist: parse-anything[docling,lite,markitdown,mineru,ocr,unstructured]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# parse-anything
+
+One interface to parse any document. Pick an engine — **MinerU**, **Docling**, **unstructured**, **MarkItDown**, or the PyMuPDF **lite** path — pass a file path, get clean markdown/text back. OCR runs on **PaddleOCR (PP-OCRv5, default)** or **Tesseract**.
+
+```python
+from parse_anything import parse
+
+result = parse("report.pdf", engine="miner-u")
+print(result.content)          # markdown
+print(result.duration_s)       # seconds
+```
+
+```bash
+parse-anything report.pdf --engine miner-u -o report.md
+parse-anything scan.png  --engine ocr --ocr paddle
+parse-anything deck.pptx                     # auto-picks the best installed engine
+```
+
+## Install
+
+Core has **zero dependencies**; each engine is an optional extra:
+
+```bash
+pip install -e .[all]                        # everything
+pip install -e .[mineru]                     # MinerU (scanned/complex PDFs)
+pip install -e .[docling]                    # Docling (structure fidelity)
+pip install -e .[unstructured]               # unstructured (broadest formats)
+pip install -e .[markitdown]                 # MarkItDown (office/web -> md)
+pip install -e .[lite]                       # PyMuPDF fast path
+pip install -e .[paddle]                     # PaddleOCR (PP-OCRv5)
+pip install -e .[tesseract]                  # pytesseract (+ install the tesseract binary)
+```
+
+Windows Tesseract binary: [UB-Mannheim build](https://github.com/UB-Mannheim/tesseract/wiki) or `choco install tesseract`.
+
+## Engines
+
+| `--engine` | Backed by | Reach for it when |
+|------------|-----------|-------------------|
+| `mineru` / `miner-u` | [MinerU](https://github.com/opendatalab/MinerU) | scanned or complex PDFs — formulas, tables, multi-column; OCR built on PaddleOCR models |
+| `docling` | [Docling](https://github.com/docling-project/docling) | you care about reading order, tables, office formats |
+| `unstructured` | [unstructured](https://github.com/Unstructured-IO/unstructured) | odd formats: email, html, mixed batches |
+| `markitdown` | [MarkItDown](https://github.com/microsoft/markitdown) | fast docx/pptx/xlsx/html → markdown (no OCR) |
+| `lite` / `liteparse` | [PyMuPDF4LLM](https://github.com/pymupdf/RAG) | speed on PDFs that already have a text layer |
+| `ocr` | PaddleOCR / Tesseract | images or fully scanned docs, raw text out |
+| `auto` (default) | — | picks the best installed engine for the file type |
+
+## OCR
+
+`--ocr paddle` (default) uses **PaddleOCR PP-OCRv5** — the current open-source benchmark leader. `--ocr tesseract` is the portable fallback. `--ocr none` skips OCR (text-layer extraction only).
+
+## Logging
+
+Progress prints to stderr by default (auto-selected engine, OCR page-by-page, live MinerU subprocess output with a heartbeat on long runs). `-v` for debug detail, `-q` to silence it. As a library, nothing prints unless you call `logging.basicConfig(...)` yourself.
+
+See [SKILLS.md](SKILLS.md) for the full skill contract (inputs, outputs, failure modes).
+
+## Layout
+
+```
+src/parse_anything/
+├── __init__.py        # parse(path, engine=..., ocr=...) public API
+├── factory.py         # engine registry, aliases, auto-selection
+├── result.py          # ParseResult
+├── cli.py             # parse-anything CLI
+├── engines/           # one module per backend (lazy imports)
+└── ocr/               # paddle + tesseract backends, PDF rasterization
+```
+
+## Tests
+
+```bash
+pip install -e .[dev]
+pytest
+```

parse_anything-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+parse_anything/__init__.py,sha256=zEH3giD9uei5oQefVCHejGKok9qrFTofRg5KWV-AkL4,1918
+parse_anything/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+parse_anything/cli.py,sha256=fKoPsHBjDtQa0EGVim6v6Mh4zVDmT3mN7XZexSgh0ZM,3836
+parse_anything/factory.py,sha256=8b5cw8Z-L0XFsjMx1ylXaoYQndwL7znwqEZd4pYUdII,4114
+parse_anything/result.py,sha256=Gm1HpSlocGiZm1KbFUj_eAzGhjd9gl1bhHir46j0UMw,1744
+parse_anything/engines/__init__.py,sha256=ouLF6kn4xU515kBDJFgeEFCkbWz5PE8-X-OArnvMyNU,59
+parse_anything/engines/base.py,sha256=X-cBvJej18wMz7ZzKv4ALMGXKuXIHj6nnQ4tE1PbpHM,1104
+parse_anything/engines/docling_engine.py,sha256=nFOF9O_B9lSIveUbG_9p6m8vJbzMm9ihAlDhXzS2VNk,3768
+parse_anything/engines/lite_engine.py,sha256=2mB15MKhJBlx_TM2Q5ygWirAvCMKwadkVDq6Wyirvq0,2641
+parse_anything/engines/markitdown_engine.py,sha256=vAV5iziUXToKWoygLMvANCMS3QJ3vn4k3jnFjqyBYxE,1383
+parse_anything/engines/mineru_engine.py,sha256=nlFjbX_coNFK7a6jpiqJwVEZ6Y01YU6CrxuOYiZ_lYk,4653
+parse_anything/engines/ocr_engine.py,sha256=gE9Si_skvrbWp7n2Jr4wCo-7vNKtmRtpobP1YKxcsUs,1191
+parse_anything/engines/unstructured_engine.py,sha256=IpZL7qJY05nL_fUE7oU1gSqJzzCfNERZLYSQXZ-y3Zs,2892
+parse_anything/ocr/__init__.py,sha256=_XTcDas7bp5xJbjwBz_WKi51uDXyHLpmbck1sgiLJDo,685
+parse_anything/ocr/base.py,sha256=OWlNEZ0d8i3TRAoKvtKYY9P65HZDysF9w3eZ-7as1Ys,2165
+parse_anything/ocr/paddle_engine.py,sha256=2PcaCtmNA5pTlJ4rDihozWPvHIT945YUdl3FW_DvJ9Y,2592
+parse_anything/ocr/tesseract_engine.py,sha256=a4DBsLPw1lT-PvmdJYFnb22uY8_tr9283VCgwbFOKEg,1559
+parse_anything-0.1.0.dist-info/licenses/LICENSE,sha256=brhk1hp9uq9FHo4jpQv6JY5FzWamZ9rp3O9QgfU_L1w,1063
+parse_anything-0.1.0.dist-info/METADATA,sha256=tz1vNgO4FOupo9PIhBoxeaaRrYseU-hoI3_626AWiis,5732
+parse_anything-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+parse_anything-0.1.0.dist-info/entry_points.txt,sha256=5Kwj9SMu3dr-H7plRU6wSPzJI1Ek3yV261Oy-lwkcJg,59
+parse_anything-0.1.0.dist-info/top_level.txt,sha256=C9cS-cX-LF54R-82U7UFSQWGGu1-DIUVPktRlMIoOpQ,15
+parse_anything-0.1.0.dist-info/RECORD,,

parse_anything-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

parse_anything-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+parse-anything = parse_anything.cli:main

parse_anything-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yugesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parse_anything-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+parse_anything