kreuzberg 1.0.0__py3-none-any.whl

kreuzberg/__init__.py

@@ -0,0 +1,11 @@
+from .exceptions import KreuzbergError, ParsingError, ValidationError
+from .extraction import ExtractionResult, extract_bytes, extract_file
+
+__all__ = [
+    "ExtractionResult",
+    "KreuzbergError",
+    "ParsingError",
+    "ValidationError",
+    "extract_bytes",
+    "extract_file",
+]

kreuzberg/_extractors.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from charset_normalizer import detect
+from pypandoc import convert_file, convert_text
+from pypdfium2 import PdfDocument, PdfiumError
+from pytesseract import TesseractError, image_to_string
+
+from kreuzberg._mime_types import PANDOC_MIME_TYPE_EXT_MAP
+from kreuzberg._sync import run_sync
+from kreuzberg.exceptions import ParsingError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _extract_pdf_with_tesseract(file_path: Path) -> str:
+    """Extract text from a scanned PDF file using pytesseract.
+
+    Args:
+        file_path: The path to the PDF file.
+
+    Raises:
+        ParsingError: If the text could not be extracted from the PDF file.
+
+    Returns:
+        The extracted text.
+    """
+    try:
+        # make it into an image here:
+        pdf = PdfDocument(str(file_path))
+        images = [page.render(scale=2.0).to_pil() for page in pdf]
+
+        text = "\n".join(image_to_string(img) for img in images)
+        return text.strip()
+    except (PdfiumError, TesseractError) as e:
+        raise ParsingError(
+            "Could not extract text from PDF file", context={"file_path": str(file_path), "error": str(e)}
+        ) from e
+
+
+def _extract_pdf_with_pdfium2(file_path: Path) -> str:
+    """Extract text from a searchable PDF file using pypdfium2.
+
+    Args:
+        file_path: The path to the PDF file.
+
+    Raises:
+        ParsingError: If the text could not be extracted from the PDF file.
+
+    Returns:
+        The extracted text.
+    """
+    try:
+        document = PdfDocument(file_path)
+        text = "\n".join(page.get_textpage().get_text_range() for page in document)
+        return text.strip()
+    except PdfiumError as e:
+        raise ParsingError(
+            "Could not extract text from PDF file", context={"file_path": str(file_path), "error": str(e)}
+        ) from e
+
+
+async def _extract_pdf_file(file_path: Path) -> str:
+    """Extract text from a PDF file.
+
+    Args:
+        file_path: The path to the PDF file.
+
+    Returns:
+        The extracted text.
+    """
+    if content := await run_sync(_extract_pdf_with_pdfium2, file_path):
+        return content
+
+    return await run_sync(_extract_pdf_with_tesseract, file_path)
+
+
+async def _extract_content_with_pandoc(file_data: bytes, mime_type: str, encoding: str | None = None) -> str:
+    """Extract text using pandoc.
+
+    Args:
+        file_data: The content of the file.
+        mime_type: The mime type of the file.
+        encoding: An optional encoding to use when decoding the string.
+
+    Raises:
+        ParsingError: If the text could not be extracted from the file using pandoc.
+
+    Returns:
+        The extracted text.
+    """
+    ext = PANDOC_MIME_TYPE_EXT_MAP[mime_type]
+    encoding = encoding or detect(file_data)["encoding"] or "utf-8"
+    try:
+        return cast(str, await run_sync(convert_text, file_data, to="md", format=ext, encoding=encoding))
+    except RuntimeError as e:
+        raise ParsingError(
+            f"Could not extract text from {PANDOC_MIME_TYPE_EXT_MAP[mime_type]} file contents",
+            context={"error": str(e)},
+        ) from e
+
+
+async def _extract_file_with_pandoc(file_path: Path | str, mime_type: str) -> str:
+    """Extract text using pandoc.
+
+    Args:
+        file_path: The path to the file.
+        mime_type: The mime type of the file.
+
+    Raises:
+        ParsingError: If the text could not be extracted from the file using pandoc.
+
+    Returns:
+        The extracted text.
+    """
+    ext = PANDOC_MIME_TYPE_EXT_MAP[mime_type]
+    try:
+        return cast(str, await run_sync(convert_file, file_path, to="md", format=ext))
+    except RuntimeError as e:
+        raise ParsingError(
+            f"Could not extract text from {PANDOC_MIME_TYPE_EXT_MAP[mime_type]} file",
+            context={"file_path": str(file_path), "error": str(e)},
+        ) from e
+
+
+async def _extract_image_with_tesseract(file_path: Path | str) -> str:
+    """Extract text from an image file.
+
+    Args:
+        file_path: The path to the image file.
+
+    Raises:
+        ParsingError: If the text could not be extracted from the image file.
+
+    Returns:
+        The extracted content.
+    """
+    try:
+        return cast(str, image_to_string(str(file_path)).strip())
+    except TesseractError as e:
+        raise ParsingError(
+            "Could not extract text from image file", context={"file_path": str(file_path), "error": str(e)}
+        ) from e

kreuzberg/_mime_types.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+MARKDOWN_MIME_TYPE: Final[str] = "text/markdown"
+PLAIN_TEXT_MIME_TYPE: Final[str] = "text/plain"
+PDF_MIME_TYPE: Final[str] = "application/pdf"
+
+PLAIN_TEXT_MIME_TYPES: Final[set[str]] = {PLAIN_TEXT_MIME_TYPE, MARKDOWN_MIME_TYPE}
+
+IMAGE_MIME_TYPES: Final[set[str]] = {
+    "image/bmp",
+    "image/gif",
+    "image/jp2",
+    "image/jpeg",
+    "image/jpm",
+    "image/jpx",
+    "image/mj2",
+    "image/pjpeg",
+    "image/png",
+    "image/tiff",
+    "image/webp",
+    "image/x-bmp",
+    "image/x-ms-bmp",
+    "image/x-portable-anymap",
+    "image/x-portable-bitmap",
+    "image/x-portable-graymap",
+    "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/csv",
+    "application/latex",
+    "application/rtf",
+    "application/vnd.oasis.opendocument.text",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/x-csv",
+    "application/x-latex",
+    "application/x-rtf",
+    "application/x-vnd.oasis.opendocument.text",
+    "text/csv",
+    "text/latex",
+    "text/rst",
+    "text/rtf",
+    "text/tab-separated-values",
+    "text/x-csv",
+    "text/x-latex",
+    "text/x-rst",
+    "text/x-tsv",
+}
+PANDOC_MIME_TYPE_EXT_MAP: Final[Mapping[str, str]] = {
+    "application/csv": "csv",
+    "application/latex": "latex",
+    "application/rtf": "rtf",
+    "application/vnd.oasis.opendocument.text": "odt",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/x-csv": "csv",
+    "application/x-latex": "latex",
+    "application/x-rtf": "rtf",
+    "application/x-vnd.oasis.opendocument.text": "odt",
+    "text/csv": "csv",
+    "text/latex": "latex",
+    "text/rst": "rst",
+    "text/rtf": "rtf",
+    "text/tab-separated-values": "tsv",
+    "text/x-csv": "csv",
+    "text/x-latex": "latex",
+    "text/x-rst": "rst",
+    "text/x-tsv": "tsv",
+}
+
+SUPPORTED_MIME_TYPES: Final[set[str]] = (
+    PLAIN_TEXT_MIME_TYPES | IMAGE_MIME_TYPES | PANDOC_SUPPORTED_MIME_TYPES | {PDF_MIME_TYPE}
+)

kreuzberg/_string.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from charset_normalizer import detect
+
+
+def safe_decode(byte_data: bytes, encoding: str | None = None) -> str:
+    """Decode a byte string safely, removing invalid sequences.
+
+    Args:
+        byte_data: The byte string to decode.
+        encoding: The encoding to use when decoding the byte string.
+
+    Returns:
+        The decoded string.
+    """
+    if not byte_data:
+        return ""
+
+    if encoding:
+        try:
+            return byte_data.decode(encoding, errors="ignore")
+        except UnicodeDecodeError:  # pragma: no cover
+            pass
+
+    encodings = ["utf-8", "latin-1"]
+    if encoding := detect(byte_data).get("encoding"):
+        encodings.append(encoding)
+
+    for encoding in encodings:
+        try:
+            return byte_data.decode(encoding, errors="ignore")
+        except UnicodeDecodeError:  # pragma: no cover  # noqa: PERF203
+            pass
+
+    return byte_data.decode("latin-1", errors="replace")

kreuzberg/_sync.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from anyio.to_thread import run_sync as any_io_run_sync
+from typing_extensions import ParamSpec
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+async def run_sync(sync_fn: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
+    """Run a synchronous function in an asynchronous context.
+
+    Args:
+        sync_fn: The synchronous function to run.
+        *args: The positional arguments to pass to the function.
+        **kwargs: The keyword arguments to pass to the function.
+
+    Returns:
+        The result of the synchronous function.
+    """
+    handler = partial(sync_fn, **kwargs)
+    return cast(T, await any_io_run_sync(handler, *args))  # pyright: ignore [reportCallIssue]

kreuzberg/exceptions.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from json import dumps
+from typing import Any
+
+
+class KreuzbergError(Exception):
+    """Base exception for all Kreuzberg errors."""
+
+    context: Any
+    """The context of the error."""
+
+    def __init__(self, message: str, context: Any = None) -> None:
+        self.context = context
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Return a string representation of the exception."""
+        ctx = f"\n\nContext: {dumps(self.context)}" if self.context else ""
+
+        return f"{self.__class__.__name__}: {super().__str__()}{ctx}"
+
+
+class ParsingError(KreuzbergError):
+    """Raised when a parsing error occurs."""
+
+
+class ValidationError(KreuzbergError):
+    """Raised when a validation error occurs."""

kreuzberg/extraction.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from mimetypes import guess_type
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import NamedTuple
+
+from anyio import Path as AsyncPath
+
+from kreuzberg._extractors import (
+    _extract_content_with_pandoc,
+    _extract_file_with_pandoc,
+    _extract_image_with_tesseract,
+    _extract_pdf_file,
+)
+from kreuzberg._mime_types import (
+    IMAGE_MIME_TYPE_EXT_MAP,
+    IMAGE_MIME_TYPES,
+    MARKDOWN_MIME_TYPE,
+    PANDOC_SUPPORTED_MIME_TYPES,
+    PDF_MIME_TYPE,
+    PLAIN_TEXT_MIME_TYPE,
+    SUPPORTED_MIME_TYPES,
+)
+from kreuzberg._string import safe_decode
+from kreuzberg.exceptions import ValidationError
+
+
+class ExtractionResult(NamedTuple):
+    """The result of a file extraction."""
+
+    content: str
+    """The extracted content."""
+    mime_type: str
+    """The mime type of the content."""
+
+
+async def extract_bytes(content: bytes, mime_type: str) -> ExtractionResult:
+    """Extract the textual content from a given byte string representing a file's contents.
+
+    Args:
+        content: The content to extract.
+        mime_type: The mime type of the content.
+
+    Raises:
+        ValidationError: If the mime type is not supported.
+
+    Returns:
+        The extracted content and the mime type of the content.
+    """
+    if mime_type not in SUPPORTED_MIME_TYPES or not any(mime_type.startswith(value) for value in SUPPORTED_MIME_TYPES):
+        raise ValidationError(
+            f"Unsupported mime type: {mime_type}",
+            context={"mime_type": mime_type, "supported_mimetypes": ",".join(sorted(SUPPORTED_MIME_TYPES))},
+        )
+
+    if mime_type == PDF_MIME_TYPE or mime_type.startswith(PDF_MIME_TYPE):
+        with NamedTemporaryFile(suffix=".pdf") as temp_file:
+            temp_file.write(content)
+            return ExtractionResult(
+                content=await _extract_pdf_file(Path(temp_file.name)), mime_type=PLAIN_TEXT_MIME_TYPE
+            )
+
+    if mime_type in IMAGE_MIME_TYPES or any(mime_type.startswith(value) for value in IMAGE_MIME_TYPES):
+        with NamedTemporaryFile(suffix=IMAGE_MIME_TYPE_EXT_MAP[mime_type]) as temp_file:
+            temp_file.write(content)
+            return ExtractionResult(
+                content=await _extract_image_with_tesseract(temp_file.name), mime_type=PLAIN_TEXT_MIME_TYPE
+            )
+
+    if mime_type in PANDOC_SUPPORTED_MIME_TYPES or any(
+        mime_type.startswith(value) for value in PANDOC_SUPPORTED_MIME_TYPES
+    ):
+        return ExtractionResult(
+            content=await _extract_content_with_pandoc(content, mime_type), mime_type=MARKDOWN_MIME_TYPE
+        )
+
+    return ExtractionResult(
+        content=safe_decode(content),
+        mime_type=mime_type,
+    )
+
+
+async def extract_file(file_path: Path | str, mime_type: str | None = None) -> ExtractionResult:
+    """Extract the textual content from a given file.
+
+    Args:
+        file_path: The path to the file.
+        mime_type: The mime type of the file.
+
+    Raises:
+        ValidationError: If the mime type is not supported.
+
+    Returns:
+        The extracted content and the mime type of the content.
+    """
+    file_path = Path(file_path)
+    mime_type = mime_type or guess_type(file_path.name)[0]
+    if not mime_type:  # pragma: no cover
+        raise ValidationError("Could not determine the mime type of the file.", context={"file_path": str(file_path)})
+
+    if mime_type not in SUPPORTED_MIME_TYPES or not any(mime_type.startswith(value) for value in SUPPORTED_MIME_TYPES):
+        raise ValidationError(
+            f"Unsupported mime type: {mime_type}",
+            context={"mime_type": mime_type, "supported_mimetypes": ",".join(sorted(SUPPORTED_MIME_TYPES))},
+        )
+
+    if not await AsyncPath(file_path).exists():
+        raise ValidationError("The file does not exist.", context={"file_path": str(file_path)})
+
+    if mime_type == PDF_MIME_TYPE or mime_type.startswith(PDF_MIME_TYPE):
+        return ExtractionResult(content=await _extract_pdf_file(file_path), mime_type=PLAIN_TEXT_MIME_TYPE)
+
+    if mime_type in IMAGE_MIME_TYPES or any(mime_type.startswith(value) for value in IMAGE_MIME_TYPES):
+        return ExtractionResult(content=await _extract_image_with_tesseract(file_path), mime_type=PLAIN_TEXT_MIME_TYPE)
+
+    if mime_type in PANDOC_SUPPORTED_MIME_TYPES or any(
+        mime_type.startswith(value) for value in PANDOC_SUPPORTED_MIME_TYPES
+    ):
+        return ExtractionResult(
+            content=await _extract_file_with_pandoc(file_path, mime_type), mime_type=MARKDOWN_MIME_TYPE
+        )
+
+    return ExtractionResult(content=await AsyncPath(file_path).read_text(), mime_type=mime_type)

kreuzberg-1.0.0.dist-info/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Na'aman Hirschfeld
+
+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.

kreuzberg-1.0.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.2
+Name: kreuzberg
+Version: 1.0.0
+Summary: A text extraction library supporting PDFs, images, office documents and more
+Author-email: Na'aman Hirschfeld <nhirschfed@gmail.com>
+License: MIT
+Project-URL: homepage, https://github.com/Goldziher/kreuzberg
+Keywords: async,document-processing,docx,image-to-text,latex,markdown,ocr,odt,office-documents,pandoc,pdf,pdf-extraction,rag,tesseract,text-extraction,text-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anyio>=4.8.0
+Requires-Dist: charset-normalizer>=3.4.1
+Requires-Dist: pypandoc>=1.15
+Requires-Dist: pypdfium2>=4.30.1
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: typing-extensions>=4.12.2
+
+# Kreuzberg
+
+Kreuzberg is a library for simplified text extraction from PDF files. It's meant to offer simple, hassle free text
+extraction.
+
+Why?
+
+I am building, like many do now, a RAG focused service. I have text extraction needs.
+There are quite a lot of commercial options out there, and several open-source + paid options.
+But I wanted something simple, which does not require expansive round-trips to an external API.
+Furthermore, I wanted something that is easy to run locally and isn't very heavy / requires a GPU.
+
+Hence, this library.
+
+## Features
+
+- Extract text from PDFs, images, and office documents
+- Use modern Python with async (via `anyio`) and proper type hints
+- Extensive error handling for easy debugging
+
+## Installation
+
+1. Begin by installing the python package:
+
+   ```shell
+
+   pip install kreuzberg
+
+   ```
+
+2. Install the system dependencies:
+
+- [pandoc](https://pandoc.org/installing.html) (non-pdf text extraction, GPL v2.0 licensed but used via CLI only)
+- [tesseract-ocr](https://tesseract-ocr.github.io/) (for image/PDF OCR, Apache License)
+
+## Supported File Types
+
+Kreuzberg supports a wide range of file formats:
+
+### Document Formats
+
+- PDF (`.pdf`) - both searchable and scanned documents
+- Word Documents (`.docx`)
+- OpenDocument Text (`.odt`)
+- Rich Text Format (`.rtf`)
+
+### Image Formats
+
+- JPEG, JPG (`.jpg`, `.jpeg`, `.pjpeg`)
+- PNG (`.png`)
+- TIFF (`.tiff`, `.tif`)
+- BMP (`.bmp`)
+- GIF (`.gif`)
+- WebP (`.webp`)
+- JPEG 2000 (`.jp2`, `.jpx`, `.jpm`, `.mj2`)
+- Portable Anymap (`.pnm`)
+- Portable Bitmap (`.pbm`)
+- Portable Graymap (`.pgm`)
+- Portable Pixmap (`.ppm`)
+
+#### Text and Markup Formats
+
+- Plain Text (`.txt`)
+- Markdown (`.md`)
+- reStructuredText (`.rst`)
+- LaTeX (`.tex`)
+
+#### Data Formats
+
+- Comma-Separated Values (`.csv`)
+- Tab-Separated Values (`.tsv`)
+
+All formats support text extraction, with different processing methods:
+
+- PDFs are processed using pdfium2 for searchable PDFs and Tesseract OCR for scanned documents
+- Images are processed using Tesseract OCR
+- Office documents and other formats are processed using Pandoc
+- Plain text files are read directly with appropriate encoding detection
+
+## Usage
+
+Kreuzberg exports two async functions:
+
+- Extract text from a file (string path or `pathlib.Path`) using `extract_file()`
+- Extract text from a byte-string using `extract_bytes()`
+
+Note - both of these functions are async and therefore should be used in an async context.
+
+### Extract from File
+
+```python
+from pathlib import Path
+from kreuzberg import extract_file
+
+
+# Extract text from a PDF file
+async def extract_pdf():
+    result = await extract_file("document.pdf")
+    print(f"Extracted text: {result.content}")
+    print(f"Output mime type: {result.mime_type}")
+
+
+# Extract text from an image
+async def extract_image():
+    result = await extract_file("scan.png")
+    print(f"Extracted text: {result.content}")
+
+
+# or use Path
+
+async def extract_pdf():
+    result = await extract_file(Path("document.pdf"))
+    print(f"Extracted text: {result.content}")
+    print(f"Output mime type: {result.mime_type}")
+```
+
+### Extract from Bytes
+
+```python
+from kreuzberg import extract_bytes
+
+
+# Extract text from PDF bytes
+async def process_uploaded_pdf(pdf_content: bytes):
+    result = await extract_bytes(pdf_content, mime_type="application/pdf")
+    return result.content
+
+
+# Extract text from image bytes
+async def process_uploaded_image(image_content: bytes):
+    result = await extract_bytes(image_content, mime_type="image/jpeg")
+    return result.content
+```
+
+### Error Handling
+
+Kreuzberg raises two exception types:
+
+#### ValidationError
+
+Raised when there are issues with input validation:
+
+- Unsupported mime types
+- Non-existent files
+- Undetectable mime types
+
+#### ParsingError
+
+Raised when there are issues during the text extraction process:
+
+- PDF parsing failures
+- OCR errors
+- Pandoc conversion errors
+
+```python
+from kreuzberg import extract_file
+from kreuzberg.exceptions import ValidationError, ParsingError
+
+
+async def safe_extract():
+    try:
+        result = await extract_file("document.doc")
+        return result.content
+    except ValidationError as e:
+        print(f"Validation error: {e.message}")
+        print(f"Context: {e.context}")
+    except ParsingError as e:
+        print(f"Parsing error: {e.message}")
+        print(f"Context: {e.context}")  # Contains detailed error information
+```
+
+Both error types include helpful context information for debugging:
+
+```python
+try:
+    result = await extract_file("scanned.pdf")
+except ParsingError as e:
+# e.context might contain:
+# {
+#    "file_path": "scanned.pdf",
+#    "error": "Tesseract OCR failed: Unable to process image"
+# }
+```
+
+### ExtractionResult
+
+All extraction functions return an ExtractionResult named tuple containing:
+
+- content: The extracted text as a string
+- mime_type: The mime type of the output (either "text/plain" or, if pandoc is used- "text/markdown")
+
+```python
+from kreuzberg import ExtractionResult
+
+
+async def process_document(path: str) -> str:
+    result: ExtractionResult = await extract_file(path)
+    return result.content
+
+
+# or access the result as tuple
+
+async def process_document(path: str) -> str:
+    content, mime_type = await extract_file(path)
+    # do something with mime_type
+    return content
+```
+
+## Contribution
+
+This library is open to contribution. Feel free to open issues or submit PRs. Its better to discuss issues before
+submitting PRs to avoid disappointment.
+
+### Local Development
+
+1. Clone the repo
+2. Install the system dependencies
+3. Install the full dependencies with `uv sync`
+4. Install the pre-commit hooks with:
+   ```shell
+   pre-commit install && pre-commit install --hook-type commit-msg
+   ```
+5. Make your changes and submit a PR
+
+## License
+
+This library uses the MIT license.

kreuzberg-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kreuzberg/__init__.py,sha256=5IBPjPsZ7faK15gFB9ZEROHhkEX7KKQmrHPCZuGnhb0,285
+kreuzberg/_extractors.py,sha256=tmOgzhKw8J21R-NKWSgu7yf5epGleoxC9nKQacUDdms,4461
+kreuzberg/_mime_types.py,sha256=VI3bWm7NBF0Vs2PXpxnJxTlt0pRSE59raVO_KTDJCVQ,2719
+kreuzberg/_string.py,sha256=8YezUPhTGEMk08yGrBxVu4CwhUdCQwOvyC6EGB7wxLk,975
+kreuzberg/_sync.py,sha256=OQZTSKUOaSMkxAb4ynq-BDrx1JLAYP9uc_zFZaAN_fk,854
+kreuzberg/exceptions.py,sha256=jrXyvcuSU-694OEtXPZfHYcUbpoRZzNKw9Lo3wIZwL0,770
+kreuzberg/extraction.py,sha256=utxr9HM8K2aDU0LXHVKCNPXqTu7fGDeNCNpamGr6hAQ,4646
+kreuzberg/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kreuzberg-1.0.0.dist-info/LICENSE,sha256=-8caMvpCK8SgZ5LlRKhGCMtYDEXqTKH9X8pFEhl91_4,1066
+kreuzberg-1.0.0.dist-info/METADATA,sha256=fQszunogmstxhdJMMD5ieXLRqjBojXpb0pXJAZZO8fQ,7238
+kreuzberg-1.0.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+kreuzberg-1.0.0.dist-info/top_level.txt,sha256=rbGkygffkZiyKhL8UN41ZOjLfem0jJPA1Whtndne0rE,10
+kreuzberg-1.0.0.dist-info/RECORD,,

kreuzberg-1.0.0.dist-info/WHEEL

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

kreuzberg-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kreuzberg