kreuzberg 2.1.2__py3-none-any.whl → 3.0.1__py3-none-any.whl

kreuzberg/_extractors/_pdf.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from multiprocessing import cpu_count
+from re import Pattern
+from re import compile as compile_regex
+from typing import TYPE_CHECKING, ClassVar, cast
+
+import anyio
+import pypdfium2
+from anyio import Path as AsyncPath
+
+from kreuzberg._extractors._base import Extractor
+from kreuzberg._mime_types import PDF_MIME_TYPE, PLAIN_TEXT_MIME_TYPE
+from kreuzberg._ocr import get_ocr_backend
+from kreuzberg._playa import extract_pdf_metadata
+from kreuzberg._types import ExtractionResult, OcrBackendType
+from kreuzberg._utils._string import normalize_spaces
+from kreuzberg._utils._sync import run_sync, run_taskgroup_batched
+from kreuzberg._utils._tmp import create_temp_file
+from kreuzberg.exceptions import ParsingError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from pathlib import Path
+
+    from PIL.Image import Image
+
+
+class PDFExtractor(Extractor):
+    SUPPORTED_MIME_TYPES: ClassVar[set[str]] = {PDF_MIME_TYPE}
+    CORRUPTED_PATTERN: ClassVar[Pattern[str]] = compile_regex(r"[\x00-\x08\x0B-\x0C\x0E-\x1F]|\uFFFD")
+    SHORT_TEXT_THRESHOLD: ClassVar[int] = 50
+    MINIMUM_CORRUPTED_RESULTS: ClassVar[int] = 2
+
+    async def extract_bytes_async(self, content: bytes) -> ExtractionResult:
+        file_path, unlink = await create_temp_file(".pdf")
+        await AsyncPath(file_path).write_bytes(content)
+        try:
+            metadata = await extract_pdf_metadata(content)
+            result = await self.extract_path_async(file_path)
+
+            result.metadata = metadata
+            return result
+        finally:
+            await unlink()
+
+    async def extract_path_async(self, path: Path) -> ExtractionResult:
+        content_bytes = await AsyncPath(path).read_bytes()
+        metadata = await extract_pdf_metadata(content_bytes)
+
+        if not self.config.force_ocr:
+            content = await self._extract_pdf_searchable_text(path)
+            if self._validate_extracted_text(content):
+                return ExtractionResult(content=content, mime_type=PLAIN_TEXT_MIME_TYPE, metadata=metadata, chunks=[])
+
+        if self.config.ocr_backend is not None:
+            result = await self._extract_pdf_text_with_ocr(path, self.config.ocr_backend)
+
+            result.metadata = metadata
+            return result
+
+        return ExtractionResult(content="", mime_type=PLAIN_TEXT_MIME_TYPE, metadata=metadata, chunks=[])
+
+    def extract_bytes_sync(self, content: bytes) -> ExtractionResult:
+        return anyio.run(self.extract_bytes_async, content)
+
+    def extract_path_sync(self, path: Path) -> ExtractionResult:
+        return anyio.run(self.extract_path_async, path)
+
+    def _validate_extracted_text(self, text: str, corruption_threshold: float = 0.05) -> bool:
+        """Check if text extracted from PDF is valid or corrupted.
+
+        This checks for indicators of corrupted PDF text extraction:
+        1. Empty or whitespace-only text
+        2. High concentration of control characters and null bytes
+        3. High concentration of Unicode replacement characters
+
+        Args:
+            text: The extracted text to validate
+            corruption_threshold: Maximum allowed percentage (0.0-1.0) of corrupted
+                characters (default: 0.05 or 5%)
+
+        Returns:
+            True if the text appears valid, False if it seems corrupted
+        """
+        if not text or not text.strip():
+            return False
+
+        corruption_matches = self.CORRUPTED_PATTERN.findall(text)
+
+        if len(text) < self.SHORT_TEXT_THRESHOLD:
+            return len(corruption_matches) <= self.MINIMUM_CORRUPTED_RESULTS
+
+        return (len(corruption_matches) / len(text)) < corruption_threshold
+
+    async def _convert_pdf_to_images(self, input_file: Path) -> list[Image]:
+        """Convert a PDF file to images.
+
+        Args:
+            input_file: The path to the PDF file.
+
+        Raises:
+            ParsingError: If the PDF file could not be converted to images.
+
+        Returns:
+            A list of Pillow Images.
+        """
+        document: pypdfium2.PdfDocument | None = None
+        try:
+            document = await run_sync(pypdfium2.PdfDocument, str(input_file))
+            return [page.render(scale=4.25).to_pil() for page in cast("pypdfium2.PdfDocument", document)]
+        except pypdfium2.PdfiumError as e:
+            raise ParsingError(
+                "Could not convert PDF to images", context={"file_path": str(input_file), "error": str(e)}
+            ) from e
+        finally:
+            if document:
+                await run_sync(document.close)
+
+    async def _extract_pdf_text_with_ocr(self, input_file: Path, ocr_backend: OcrBackendType) -> ExtractionResult:
+        """Extract text from a scanned PDF file using OCR.
+
+        Args:
+            input_file: The path to the PDF file.
+            ocr_backend: The OCR backend to use.
+
+        Returns:
+            The extraction result with text content and metadata.
+        """
+        images = await self._convert_pdf_to_images(input_file)
+        backend = get_ocr_backend(ocr_backend)
+        ocr_results = await run_taskgroup_batched(
+            *[backend.process_image(image, **self.config.get_config_dict()) for image in images],
+            batch_size=cpu_count(),
+        )
+        return ExtractionResult(
+            content="\n".join([v.content for v in ocr_results]), mime_type=PLAIN_TEXT_MIME_TYPE, metadata={}, chunks=[]
+        )
+
+    @staticmethod
+    async def _extract_pdf_searchable_text(input_file: Path) -> str:
+        """Extract text from a searchable PDF file using pypdfium2.
+
+        Args:
+            input_file: The path to the PDF file.
+
+        Raises:
+            ParsingError: If the text could not be extracted from the PDF file.
+
+        Returns:
+            The extracted text.
+        """
+        document: pypdfium2.PdfDocument | None = None
+        try:
+            document = await run_sync(pypdfium2.PdfDocument, str(input_file))
+            text = "\n".join(page.get_textpage().get_text_bounded() for page in cast("pypdfium2.PdfDocument", document))
+            return normalize_spaces(text)
+        except pypdfium2.PdfiumError as e:
+            raise ParsingError(
+                "Could not extract text from PDF file", context={"file_path": str(input_file), "error": str(e)}
+            ) from e
+        finally:
+            if document:
+                await run_sync(document.close)

kreuzberg/_extractors/_presentation.py

@@ -0,0 +1,233 @@
+"""This module provides functions to extract textual content from files.
+
+It includes vendored code:
+
+- The extract PPTX logic is based on code vendored from `markitdown` to extract text from PPTX files.
+    See: https://github.com/microsoft/markitdown/blob/main/src/markitdown/_markitdown.py
+    Refer to the markitdown repository for it's license (MIT).
+"""
+
+from __future__ import annotations
+
+import re
+from contextlib import suppress
+from html import escape
+from io import BytesIO
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar
+
+import pptx
+from anyio import Path as AsyncPath
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+from kreuzberg._extractors._base import Extractor
+from kreuzberg._mime_types import MARKDOWN_MIME_TYPE, POWER_POINT_MIME_TYPE
+from kreuzberg._types import ExtractionResult
+from kreuzberg._utils._string import normalize_spaces
+
+if TYPE_CHECKING:  # pragma: no cover
+    from pptx.presentation import Presentation
+
+    from kreuzberg._types import Metadata
+
+
+class PresentationExtractor(Extractor):
+    """Extractor for PowerPoint (.pptx) files.
+
+    This extractor processes PowerPoint presentations and converts their content into Markdown format.
+    It handles slides, shapes, images, tables, and slide notes, preserving the structure and content
+    of the presentation in a readable text format.
+
+    The extractor provides both synchronous and asynchronous methods for processing files either
+    from disk or from bytes in memory.
+    """
+
+    SUPPORTED_MIME_TYPES: ClassVar[set[str]] = {POWER_POINT_MIME_TYPE}
+
+    async def extract_bytes_async(self, content: bytes) -> ExtractionResult:
+        """Asynchronously extract content from PowerPoint file bytes.
+
+        Args:
+            content: Raw bytes of the PowerPoint file to process.
+
+        Returns:
+            ExtractionResult: Contains the extracted content in Markdown format,
+                the MIME type, and any additional metadata.
+        """
+        return self._extract_pptx(content)
+
+    async def extract_path_async(self, path: Path) -> ExtractionResult:
+        """Asynchronously extract content from a PowerPoint file on disk.
+
+        Args:
+            path: Path to the PowerPoint file to process.
+
+        Returns:
+            ExtractionResult: Contains the extracted content in Markdown format,
+                the MIME type, and any additional metadata.
+        """
+        content = await AsyncPath(path).read_bytes()
+        return self._extract_pptx(content)
+
+    def extract_bytes_sync(self, content: bytes) -> ExtractionResult:
+        """Synchronously extract content from PowerPoint file bytes.
+
+        Args:
+            content: Raw bytes of the PowerPoint file to process.
+
+        Returns:
+            ExtractionResult: Contains the extracted content in Markdown format,
+                the MIME type, and any additional metadata.
+        """
+        return self._extract_pptx(content)
+
+    def extract_path_sync(self, path: Path) -> ExtractionResult:
+        """Synchronously extract content from a PowerPoint file on disk.
+
+        Args:
+            path: Path to the PowerPoint file to process.
+
+        Returns:
+            ExtractionResult: Contains the extracted content in Markdown format,
+                the MIME type, and any additional metadata.
+        """
+        content = Path(path).read_bytes()
+        return self._extract_pptx(content)
+
+    def _extract_pptx(self, file_contents: bytes) -> ExtractionResult:
+        """Process PowerPoint file contents and convert to Markdown.
+
+        This method handles the core logic of extracting content from a PowerPoint file.
+        It processes:
+        - Slide titles and content
+        - Images (with alt text if available)
+        - Tables (converted to HTML format)
+        - Text frames
+        - Slide notes
+
+        Args:
+            file_contents: Raw bytes of the PowerPoint file to process.
+
+        Returns:
+            ExtractionResult: Contains the extracted content in Markdown format,
+                the MIME type, and any additional metadata.
+
+        Notes:
+            The extraction preserves the following elements:
+            - Slide numbers (as HTML comments)
+            - Images (converted to Markdown image syntax with alt text)
+            - Tables (converted to HTML table syntax)
+            - Text content (with titles properly formatted)
+            - Slide notes (under a dedicated section for each slide)
+        """
+        md_content = ""
+        presentation = pptx.Presentation(BytesIO(file_contents))
+
+        for index, slide in enumerate(presentation.slides):
+            md_content += f"\n\n<!-- Slide number: {index + 1} -->\n"
+
+            title = None
+            if hasattr(slide.shapes, "title"):
+                title = slide.shapes.title
+
+            for shape in slide.shapes:
+                if not hasattr(shape, "shape_type"):
+                    continue
+
+                if shape.shape_type == MSO_SHAPE_TYPE.PICTURE or (
+                    shape.shape_type == MSO_SHAPE_TYPE.PLACEHOLDER and hasattr(shape, "image")
+                ):
+                    alt_text = ""
+                    with suppress(AttributeError):
+                        alt_text = shape._element._nvXxPr.cNvPr.attrib.get("descr", "")  # noqa: SLF001
+
+                    filename = re.sub(r"\W", "", shape.name) + ".jpg"
+                    md_content += f"\n![{alt_text if alt_text else shape.name}]({filename})\n"
+
+                elif shape.shape_type == MSO_SHAPE_TYPE.TABLE:
+                    html_table = "<table>"
+                    first_row = True
+
+                    for row in shape.table.rows:
+                        html_table += "<tr>"
+
+                        for cell in row.cells:
+                            tag = "th" if first_row else "td"
+                            html_table += f"<{tag}>{escape(cell.text)}</{tag}>"
+
+                        html_table += "</tr>"
+                        first_row = False
+
+                    html_table += "</table>"
+                    md_content += "\n" + html_table + "\n"
+
+                elif shape.has_text_frame:
+                    md_content += "# " + shape.text.lstrip() + "\n" if shape == title else shape.text + "\n"
+
+            md_content = md_content.strip()
+            if slide.has_notes_slide:
+                md_content += "\n\n### Notes:\n"
+                notes_frame = slide.notes_slide.notes_text_frame
+
+                if notes_frame is not None:  # pragma: no branch
+                    md_content += notes_frame.text
+
+                md_content = md_content.strip()
+
+        return ExtractionResult(
+            content=normalize_spaces(md_content),
+            mime_type=MARKDOWN_MIME_TYPE,
+            metadata=self._extract_presentation_metadata(presentation),
+            chunks=[],
+        )
+
+    @staticmethod
+    def _extract_presentation_metadata(presentation: Presentation) -> Metadata:
+        """Extract metadata from a presentation instance.
+
+        Args:
+            presentation: A `Presentation` object representing the PowerPoint file.
+
+        Returns:
+            PresentationMetadata: Object containing presentation-specific metadata fields.
+        """
+        metadata: Metadata = {}
+
+        for metadata_key, core_property_key in [
+            ("authors", "author"),
+            ("comments", "comments"),
+            ("status", "content_status"),
+            ("created_by", "created"),
+            ("identifier", "identifier"),
+            ("keywords", "keywords"),
+            ("modified_by", "last_modified_by"),
+            ("modified_at", "modified"),
+            ("version", "revision"),  # if version and revision are given, version overwrites ~keep
+            ("subject", "subject"),
+            ("title", "title"),
+            ("version", "version"),
+        ]:
+            if core_property := getattr(presentation.core_properties, core_property_key, None):
+                metadata[metadata_key] = core_property  # type: ignore[literal-required]
+
+        if presentation.core_properties.language:
+            metadata["languages"] = [presentation.core_properties.language]
+
+        if presentation.core_properties.category:
+            metadata["categories"] = [presentation.core_properties.category]
+
+        fonts = set()
+        for slide in presentation.slides:
+            for shape in slide.shapes:
+                if not hasattr(shape, "text_frame"):
+                    continue
+
+                for paragraph in shape.text_frame.paragraphs:
+                    for run in paragraph.runs:
+                        if hasattr(run, "font") and run.font.name:
+                            fonts.add(run.font.name)
+
+        if fonts:
+            metadata["fonts"] = list(fonts)
+
+        return metadata

kreuzberg/_extractors/_spread_sheet.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import csv
+import sys
+from datetime import date, datetime, time, timedelta
+from io import StringIO
+from typing import TYPE_CHECKING, Any, Union
+
+import anyio
+from anyio import Path as AsyncPath
+from python_calamine import CalamineWorkbook
+
+from kreuzberg._extractors._base import Extractor
+from kreuzberg._mime_types import MARKDOWN_MIME_TYPE, SPREADSHEET_MIME_TYPES
+from kreuzberg._types import ExtractionResult
+from kreuzberg._utils._string import normalize_spaces
+from kreuzberg._utils._sync import run_sync, run_taskgroup
+from kreuzberg._utils._tmp import create_temp_file
+from kreuzberg.exceptions import ParsingError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from pathlib import Path
+
+if sys.version_info < (3, 11):  # pragma: no cover
+    from exceptiongroup import ExceptionGroup  # type: ignore[import-not-found]
+
+
+CellValue = Union[int, float, str, bool, time, date, datetime, timedelta]
+
+
+class SpreadSheetExtractor(Extractor):
+    SUPPORTED_MIME_TYPES = SPREADSHEET_MIME_TYPES
+
+    async def extract_bytes_async(self, content: bytes) -> ExtractionResult:
+        xlsx_path, unlink = await create_temp_file(".xlsx")
+        await AsyncPath(xlsx_path).write_bytes(content)
+        try:
+            return await self.extract_path_async(xlsx_path)
+        finally:
+            await unlink()
+
+    async def extract_path_async(self, path: Path) -> ExtractionResult:
+        try:
+            workbook: CalamineWorkbook = await run_sync(CalamineWorkbook.from_path, str(path))
+            tasks = [self._convert_sheet_to_text(workbook, sheet_name) for sheet_name in workbook.sheet_names]
+
+            try:
+                results: list[str] = await run_taskgroup(*tasks)
+
+                return ExtractionResult(
+                    content="\n\n".join(results), mime_type=MARKDOWN_MIME_TYPE, metadata={}, chunks=[]
+                )
+            except ExceptionGroup as eg:
+                raise ParsingError(
+                    "Failed to extract file data",
+                    context={"file": str(path), "errors": eg.exceptions},
+                ) from eg
+        except Exception as e:
+            if isinstance(e, ParsingError):
+                raise
+            raise ParsingError(
+                "Failed to extract file data",
+                context={"file": str(path), "error": str(e)},
+            ) from e
+
+    def extract_bytes_sync(self, content: bytes) -> ExtractionResult:
+        return anyio.run(self.extract_bytes_async, content)
+
+    def extract_path_sync(self, path: Path) -> ExtractionResult:
+        return anyio.run(self.extract_path_async, path)
+
+    @staticmethod
+    def _convert_cell_to_str(value: Any) -> str:
+        """Convert a cell value to string representation.
+
+        Args:
+            value: The cell value to convert.
+
+        Returns:
+            String representation of the cell value.
+        """
+        if value is None:
+            return ""
+        if isinstance(value, bool):
+            return str(value).lower()
+        if isinstance(value, (datetime, date, time)):
+            return value.isoformat()
+        if isinstance(value, timedelta):
+            return f"{value.total_seconds()} seconds"
+        return str(value)
+
+    async def _convert_sheet_to_text(self, workbook: CalamineWorkbook, sheet_name: str) -> str:
+        values = workbook.get_sheet_by_name(sheet_name).to_python()
+
+        csv_buffer = StringIO()
+        writer = csv.writer(csv_buffer)
+
+        for row in values:
+            writer.writerow([self._convert_cell_to_str(cell) for cell in row])
+
+        csv_data = csv_buffer.getvalue()
+        csv_buffer.close()
+
+        csv_path, unlink = await create_temp_file(".csv")
+        await AsyncPath(csv_path).write_text(csv_data)
+
+        csv_reader = csv.reader(StringIO(csv_data))
+        rows = list(csv_reader)
+        result = ""
+        if rows:
+            header = rows[0]
+            markdown_lines: list[str] = [
+                "| " + " | ".join(header) + " |",
+                "| " + " | ".join(["---" for _ in header]) + " |",
+            ]
+
+            for row in rows[1:]:  # type: ignore[assignment]
+                while len(row) < len(header):
+                    row.append("")
+                markdown_lines.append("| " + " | ".join(row) + " |")  # type: ignore[arg-type]
+
+            result = "\n".join(markdown_lines)
+
+        await unlink()
+        return f"## {sheet_name}\n\n{normalize_spaces(result)}"

kreuzberg/_mime_types.py

@@ -16,7 +16,7 @@ PDF_MIME_TYPE: Final = "application/pdf"
 PLAIN_TEXT_MIME_TYPE: Final = "text/plain"
 POWER_POINT_MIME_TYPE: Final = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
 DOCX_MIME_TYPE: Final = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
-# Excel formats
+
 EXCEL_MIME_TYPE: Final = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 EXCEL_BINARY_MIME_TYPE: Final = "application/vnd.ms-excel"
 EXCEL_MACRO_MIME_TYPE: Final = "application/vnd.ms-excel.sheet.macroEnabled.12"
@@ -24,8 +24,8 @@ EXCEL_BINARY_2007_MIME_TYPE: Final = "application/vnd.ms-excel.sheet.binary.macr
 EXCEL_ADDON_MIME_TYPE: Final = "application/vnd.ms-excel.addin.macroEnabled.12"
 EXCEL_TEMPLATE_MIME_TYPE: Final = "application/vnd.ms-excel.template.macroEnabled.12"
 
-# OpenDocument spreadsheet format
-OPENDOC_SPREADSHEET_MIME_TYPE: Final = "application/vnd.oasis.opendocument.spreadsheet"  # ods
+
+OPENDOC_SPREADSHEET_MIME_TYPE: Final = "application/vnd.oasis.opendocument.spreadsheet"
 PLAIN_TEXT_MIME_TYPES: Final[set[str]] = {PLAIN_TEXT_MIME_TYPE, MARKDOWN_MIME_TYPE}
 
 IMAGE_MIME_TYPES: Final[set[str]] = {
@@ -48,26 +48,7 @@ IMAGE_MIME_TYPES: Final[set[str]] = {
     "image/x-portable-pixmap",
     "image/x-tiff",
 }
-IMAGE_MIME_TYPE_EXT_MAP: Final[Mapping[str, str]] = {
-    "image/bmp": "bmp",
-    "image/x-bmp": "bmp",
-    "image/x-ms-bmp": "bmp",
-    "image/gif": "gif",
-    "image/jpeg": "jpg",
-    "image/pjpeg": "jpg",
-    "image/png": "png",
-    "image/tiff": "tiff",
-    "image/x-tiff": "tiff",
-    "image/jp2": "jp2",
-    "image/jpx": "jpx",
-    "image/jpm": "jpm",
-    "image/mj2": "mj2",
-    "image/webp": "webp",
-    "image/x-portable-anymap": "pnm",
-    "image/x-portable-bitmap": "pbm",
-    "image/x-portable-graymap": "pgm",
-    "image/x-portable-pixmap": "ppm",
-}
+
 PANDOC_SUPPORTED_MIME_TYPES: Final[set[str]] = {
     "application/csl+json",
     "application/docbook+xml",
@@ -162,13 +143,17 @@ SUPPORTED_MIME_TYPES: Final[set[str]] = (
 )
 
 
-def validate_mime_type(file_path: PathLike[str] | str, mime_type: str | None = None) -> str:
+def validate_mime_type(
+    *, file_path: PathLike[str] | str | None = None, mime_type: str | None = None, check_file_exists: bool = True
+) -> str:
     """Validate and detect the MIME type for a given file.
 
     Args:
         file_path: The path to the file.
         mime_type: Optional explicit MIME type. If provided, this will be validated.
             If not provided, the function will attempt to detect the MIME type.
+        check_file_exists: Whether to check if the file exists. Default is True.
+            Set to False in tests where you want to validate a mime type without an actual file.
 
     Raises:
         ValidationError: If the MIME type is not supported or cannot be determined.
@@ -176,10 +161,18 @@ def validate_mime_type(file_path: PathLike[str] | str, mime_type: str | None = N
     Returns:
         The validated MIME type.
     """
-    path = Path(file_path)
+    if file_path and check_file_exists:
+        path = Path(file_path)
+        if not path.exists():
+            raise ValidationError("The file does not exist", context={"file_path": str(path)})
 
     if not mime_type:
-        # Try to determine MIME type from file extension first
+        if not file_path:
+            raise ValidationError(
+                "Could not determine mime type.",
+            )
+        path = Path(file_path)
+
         ext = path.suffix.lower()
         mime_type = EXT_TO_MIME_TYPE.get(ext) or guess_type(path.name)[0]
 

kreuzberg/_ocr/__init__.py

@@ -0,0 +1,17 @@
+from functools import lru_cache
+from typing import Any
+
+from kreuzberg._ocr._base import OCRBackend
+from kreuzberg._ocr._easyocr import EasyOCRBackend
+from kreuzberg._ocr._paddleocr import PaddleBackend
+from kreuzberg._ocr._tesseract import TesseractBackend
+from kreuzberg._types import OcrBackendType
+
+
+@lru_cache
+def get_ocr_backend(backend: OcrBackendType) -> OCRBackend[Any]:
+    if backend == "easyocr":
+        return EasyOCRBackend()
+    if backend == "paddleocr":
+        return PaddleBackend()
+    return TesseractBackend()

kreuzberg/_ocr/_base.py

@@ -0,0 +1,54 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Generic, TypeVar
+
+from PIL.Image import Image
+
+from kreuzberg._types import ExtractionResult
+
+try:  # pragma: no cover
+    from typing import Unpack  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover
+    from typing_extensions import Unpack
+
+
+T = TypeVar("T")
+
+
+class OCRBackend(ABC, Generic[T]):
+    """Abstract base class for Optical Character Recognition (OCR) backend implementations.
+
+    This class provides the blueprint for OCR backend implementations,
+    offering both synchronous and asynchronous methods to process images
+    and files for text extraction.
+    """
+
+    @abstractmethod
+    async def process_image(self, image: Image, **kwargs: Unpack[T]) -> ExtractionResult:
+        """Asynchronously process an image and extract its text and metadata.
+
+        Args:
+            image: An instance of PIL.Image representing the input image.
+            **kwargs: Any kwargs related to the given backend
+
+        Returns:
+            The extraction result object
+        """
+        ...
+
+    @abstractmethod
+    async def process_file(self, path: Path, **kwargs: Unpack[T]) -> ExtractionResult:
+        """Asynchronously process a file and extract its text and metadata.
+
+        Args:
+            path: A Path object representing the file to be processed.
+            **kwargs: Any kwargs related to the given backend
+
+        Returns:
+            The extraction result object
+        """
+        ...
+
+    def __hash__(self) -> int:
+        """Hash function for allowing caching."""
+        return hash(type(self).__name__)