dot-parser 2.0.0__py3-none-any.whl

dot_parser/__init__.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from importlib.metadata import version
+
+from dot_parser.backends import Backend, Docling, ImageBackend, Llama, Mistral, Pymu
+from dot_parser.chunking import chunk
+from dot_parser.images import (
+    VLM,
+    ExtractedImage,
+    ImageDescription,
+    PageInfo,
+    ParseResult,
+)
+from dot_parser.models import Chunk, ParseError
+from dot_parser.parsers import (
+    interpret_images,
+    parse,
+    parse_pdfs,
+    parse_with_images,
+)
+from dot_parser.pricing import cost_per_1k_pages, estimate_cost
+from dot_parser.vlms import MistralVLM
+
+__version__ = version("dot-parser")
+
+__all__ = [
+    "VLM",
+    "Backend",
+    "Chunk",
+    "Docling",
+    "ExtractedImage",
+    "ImageBackend",
+    "ImageDescription",
+    "Llama",
+    "Mistral",
+    "MistralVLM",
+    "PageInfo",
+    "ParseError",
+    "ParseResult",
+    "Pymu",
+    "chunk",
+    "cost_per_1k_pages",
+    "estimate_cost",
+    "interpret_images",
+    "parse",
+    "parse_pdfs",
+    "parse_with_images",
+]

dot_parser/backends/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from dot_parser.backends._base import (
+    Backend,
+    BatchBackend,
+    DocxImageBackend,
+    ImageBackend,
+    PptxImageBackend,
+)
+from dot_parser.backends.docling import Docling
+from dot_parser.backends.llama import Llama
+from dot_parser.backends.mistral import Mistral
+from dot_parser.backends.pymu import Pymu
+
+__all__ = [
+    "Backend",
+    "BatchBackend",
+    "Docling",
+    "DocxImageBackend",
+    "ImageBackend",
+    "Llama",
+    "Mistral",
+    "PptxImageBackend",
+    "Pymu",
+]

dot_parser/backends/_base.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from dot_parser.images import ParseResult
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """A PDF parsing backend that produces Markdown."""
+
+    def parse_pdf(self, source: str | Path | bytes) -> str: ...
+
+
+@runtime_checkable
+class BatchBackend(Protocol):
+    """A PDF backend that parses a whole list in one optimized call.
+
+    Backends implementing this protocol (e.g. ``Mistral`` via the Batch API)
+    take over ``parse_pdfs()`` entirely; the others fall back to a per-file
+    loop. Returns one Markdown string per input, in order, with ``None`` for
+    items that failed.
+    """
+
+    def parse_pdfs(self, sources: list[str | Path | bytes]) -> list[str | None]: ...
+
+
+@runtime_checkable
+class ImageBackend(Protocol):
+    """A PDF backend that can also extract and annotate images.
+
+    Backends that implement this protocol are eligible for the
+    `parse_with_images()` PDF path. The returned markdown must contain
+    `![name](name)` anchors at the position of each image, matching the
+    `ExtractedImage.name` of the corresponding image record.
+    """
+
+    def parse_pdf_with_images(
+        self,
+        source: str | Path | bytes,
+        *,
+        annotate_images: bool = True,
+        include_tables: bool = True,
+    ) -> ParseResult: ...
+
+
+@runtime_checkable
+class DocxImageBackend(Protocol):
+    """A backend that parses DOCX end-to-end through OCR.
+
+    When one is passed to `parse_with_images()`, the DOCX goes through the
+    backend directly instead of the markitdown + per-image VLM path.
+    """
+
+    def parse_docx_with_images(
+        self,
+        source: str | Path | bytes,
+        *,
+        annotate_images: bool = True,
+        include_tables: bool = True,
+    ) -> ParseResult: ...
+
+
+@runtime_checkable
+class PptxImageBackend(Protocol):
+    """A backend that parses PPTX end-to-end through OCR.
+
+    PPTX counterpart of :class:`DocxImageBackend`.
+    """
+
+    def parse_pptx_with_images(
+        self,
+        source: str | Path | bytes,
+        *,
+        annotate_images: bool = True,
+        include_tables: bool = True,
+    ) -> ParseResult: ...

dot_parser/backends/docling.py

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import tempfile
+from pathlib import Path
+
+
+class Docling:
+    """Docling backend (IBM, MIT licence).
+
+    Layout-aware ML pipeline (DocLayNet) + table parser (TableFormer) + OCR.
+    Robust on image-only and broken-encoding PDFs when ``force_full_page_ocr``
+    is enabled.
+
+    Install with::
+
+        pip install dot-parser[docling]
+    """
+
+    def __init__(
+        self,
+        *,
+        force_full_page_ocr: bool = True,
+        ocr_lang: tuple[str, ...] = ("eng", "fra"),
+    ) -> None:
+        try:
+            from docling.datamodel.base_models import InputFormat
+            from docling.datamodel.pipeline_options import (
+                PdfPipelineOptions,
+                TesseractCliOcrOptions,
+            )
+            from docling.document_converter import DocumentConverter, PdfFormatOption
+        except ImportError as e:
+            raise ImportError(
+                "Docling backend requires `docling`. Install with: pip install dot-parser[docling]"
+            ) from e
+
+        opts = PdfPipelineOptions()
+        opts.do_ocr = True
+        opts.ocr_options = TesseractCliOcrOptions(lang=list(ocr_lang))
+        opts.ocr_options.force_full_page_ocr = force_full_page_ocr
+
+        self._converter = DocumentConverter(
+            format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)}
+        )
+
+    def parse_pdf(self, source: str | Path | bytes) -> str:
+        if isinstance(source, bytes):
+            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+                tmp.write(source)
+                tmp.flush()
+                path = tmp.name
+            try:
+                result = self._converter.convert(path)
+            finally:
+                Path(path).unlink(missing_ok=True)
+        else:
+            result = self._converter.convert(str(source))
+        return result.document.export_to_markdown()

dot_parser/backends/llama.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import os
+import tempfile
+from pathlib import Path
+
+# Tiers exposed by the LlamaCloud parsing API. Single definition, shared
+# with the pricing table so the two can't drift:
+#   fast           — basic text extraction, no OCR (1 credit/page)
+#   cost_effective — OCR-capable, balanced quality (3 credits/page) — default
+#   agentic        — agent-based, higher quality (10 credits/page)
+#   agentic_plus   — premium (45 credits/page)
+from dot_parser.pricing import LlamaTier
+
+
+class Llama:
+    """LlamaParse / LlamaCloud backend.
+
+    Calls the LlamaCloud parsing API (``client.parsing.parse``). Robust on
+    image-only PDFs, but drops centered block equations (only inline math
+    is preserved at ``cost_effective`` tier).
+
+    Requires a LlamaCloud API key. Reads ``LLAMA_CLOUD_API_KEY`` (or the
+    fallback ``LLAMA_API_KEY``) from environment by default, or accepts it
+    as the ``api_key`` argument.
+
+    Install with::
+
+        pip install dot-parser[llama]
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        tier: LlamaTier = "cost_effective",
+        version: str = "latest",
+    ) -> None:
+        try:
+            from llama_cloud import LlamaCloud
+        except ImportError as e:
+            raise ImportError(
+                "Llama backend requires `llama-cloud`. Install with: pip install dot-parser[llama]"
+            ) from e
+
+        key = api_key or os.environ.get("LLAMA_CLOUD_API_KEY") or os.environ.get("LLAMA_API_KEY")
+        if not key:
+            raise ValueError(
+                "Llama backend requires an API key. Set LLAMA_CLOUD_API_KEY or pass api_key=..."
+            )
+        self._client = LlamaCloud(api_key=key)
+        self._tier = tier
+        self._version = version
+
+    def parse_pdf(self, source: str | Path | bytes) -> str:
+        if isinstance(source, bytes):
+            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+                tmp.write(source)
+                tmp.flush()
+                path = Path(tmp.name)
+            try:
+                return self._parse(path)
+            finally:
+                path.unlink(missing_ok=True)
+        return self._parse(Path(source))
+
+    def _parse(self, path: Path) -> str:
+        with path.open("rb") as fh:
+            result = self._client.parsing.parse(
+                upload_file=fh,
+                tier=self._tier,
+                version=self._version,
+                expand=["markdown_full"],
+            )
+        return result.markdown_full or ""