kreuzberg 3.2.0__py3-none-any.whl → 3.4.0__py3-none-any.whl

kreuzberg/extraction.py

@@ -13,7 +13,8 @@ from kreuzberg._mime_types import (
 from kreuzberg._registry import ExtractorRegistry
 from kreuzberg._types import ExtractionConfig
 from kreuzberg._utils._string import safe_decode
-from kreuzberg._utils._sync import run_maybe_async, run_maybe_sync
+from kreuzberg._utils._sync import run_maybe_sync, run_sync_only
+from kreuzberg.exceptions import ValidationError
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -42,7 +43,7 @@ async def _validate_and_post_process_async(result: ExtractionResult, config: Ext
 
 def _validate_and_post_process_sync(result: ExtractionResult, config: ExtractionConfig) -> ExtractionResult:
     for validator in config.validators or []:
-        run_maybe_async(validator, result)
+        run_sync_only(validator, result)
 
     if config.chunk_content:
         result.chunks = _handle_chunk_content(
@@ -52,7 +53,7 @@ def _validate_and_post_process_sync(result: ExtractionResult, config: Extraction
         )
 
     for post_processor in config.post_processing_hooks or []:
-        result = run_maybe_async(post_processor, result)
+        result = run_sync_only(post_processor, result)
 
     return result
 
@@ -104,22 +105,57 @@ async def extract_file(
 
     Returns:
         The extracted content and the mime type of the content.
+
+    Raises:
+        ValidationError: If the file path or configuration is invalid.
     """
-    mime_type = validate_mime_type(file_path=file_path, mime_type=mime_type)
-    if extractor := ExtractorRegistry.get_extractor(mime_type=mime_type, config=config):
-        result = await extractor.extract_path_async(Path(file_path))
-    else:
-        result = ExtractionResult(
-            content=safe_decode(await anyio.Path(file_path).read_bytes()), chunks=[], mime_type=mime_type, metadata={}
-        )
+    from kreuzberg._utils._document_cache import get_document_cache
 
-    return await _validate_and_post_process_async(result=result, config=config)
+    cache = get_document_cache()
+    path = Path(file_path)
+    cached_result = cache.get(path, config)
+    if cached_result is not None:
+        return cached_result
+
+    if cache.is_processing(path, config):
+        event = cache.mark_processing(path, config)
+        await anyio.to_thread.run_sync(event.wait)  # pragma: no cover
+
+        # Try cache again after waiting for other process to complete  # ~keep
+        cached_result = cache.get(path, config)  # pragma: no cover
+        if cached_result is not None:  # pragma: no cover
+            return cached_result
+
+    cache.mark_processing(path, config)
+
+    try:
+        if not path.exists():
+            raise ValidationError("The file does not exist", context={"file_path": str(path)})
+
+        mime_type = validate_mime_type(file_path=file_path, mime_type=mime_type)
+        if extractor := ExtractorRegistry.get_extractor(mime_type=mime_type, config=config):
+            result = await extractor.extract_path_async(Path(file_path))
+        else:
+            result = ExtractionResult(
+                content=safe_decode(await anyio.Path(file_path).read_bytes()),
+                chunks=[],
+                mime_type=mime_type,
+                metadata={},
+            )
+
+        result = await _validate_and_post_process_async(result=result, config=config)
+
+        cache.set(path, config, result)
+
+        return result
+    finally:
+        cache.mark_complete(path, config)
 
 
 async def batch_extract_file(
     file_paths: Sequence[PathLike[str] | str], config: ExtractionConfig = DEFAULT_CONFIG
 ) -> list[ExtractionResult]:
-    """Extract text from multiple files concurrently.
+    """Extract text from multiple files concurrently with optimizations.
 
     Args:
         file_paths: A sequence of paths to files to extract text from.
@@ -128,15 +164,43 @@ async def batch_extract_file(
     Returns:
         A list of extraction results in the same order as the input paths.
     """
+    if not file_paths:
+        return []
+
+    import multiprocessing as mp
+
+    max_concurrency = min(len(file_paths), mp.cpu_count() * 2)
+    semaphore = anyio.Semaphore(max_concurrency)
+
     results = cast("list[ExtractionResult]", ([None] * len(file_paths)))
 
     async def _extract_file(path: PathLike[str] | str, index: int) -> None:
-        result = await extract_file(
-            path,
-            None,
-            config,
-        )
-        results[index] = result
+        async with semaphore:
+            try:
+                result = await extract_file(
+                    path,
+                    None,
+                    config,
+                )
+                results[index] = result
+            except Exception as e:  # noqa: BLE001
+                from kreuzberg._utils._errors import create_error_context
+
+                error_result = ExtractionResult(
+                    content=f"Error: {type(e).__name__}: {e!s}",
+                    mime_type="text/plain",
+                    metadata={  # type: ignore[typeddict-unknown-key]
+                        "error": True,
+                        "error_context": create_error_context(
+                            operation="batch_extract_file",
+                            file_path=path,
+                            error=e,
+                            index=index,
+                        ),
+                    },
+                    chunks=[],
+                )
+                results[index] = error_result
 
     async with anyio.create_task_group() as tg:
         for i, path in enumerate(file_paths):
@@ -148,7 +212,7 @@ async def batch_extract_file(
 async def batch_extract_bytes(
     contents: Sequence[tuple[bytes, str]], config: ExtractionConfig = DEFAULT_CONFIG
 ) -> list[ExtractionResult]:
-    """Extract text from multiple byte contents concurrently.
+    """Extract text from multiple byte contents concurrently with optimizations.
 
     Args:
         contents: A sequence of tuples containing (content, mime_type) pairs.
@@ -157,11 +221,40 @@ async def batch_extract_bytes(
     Returns:
         A list of extraction results in the same order as the input contents.
     """
+    if not contents:
+        return []
+
+    import multiprocessing as mp
+
+    max_concurrency = min(len(contents), mp.cpu_count() * 2)
+    semaphore = anyio.Semaphore(max_concurrency)
+
     results = cast("list[ExtractionResult]", [None] * len(contents))
 
     async def _extract_bytes(content: bytes, mime_type: str, index: int) -> None:
-        result = await extract_bytes(content, mime_type, config)
-        results[index] = result
+        async with semaphore:
+            try:
+                result = await extract_bytes(content, mime_type, config)
+                results[index] = result
+            except Exception as e:  # noqa: BLE001
+                from kreuzberg._utils._errors import create_error_context
+
+                error_result = ExtractionResult(
+                    content=f"Error: {type(e).__name__}: {e!s}",
+                    mime_type="text/plain",
+                    metadata={  # type: ignore[typeddict-unknown-key]
+                        "error": True,
+                        "error_context": create_error_context(
+                            operation="batch_extract_bytes",
+                            error=e,
+                            index=index,
+                            mime_type=mime_type,
+                            content_size=len(content),
+                        ),
+                    },
+                    chunks=[],
+                )
+                results[index] = error_result
 
     async with anyio.create_task_group() as tg:
         for i, (content, mime_type) in enumerate(contents):
@@ -207,24 +300,57 @@ def extract_file_sync(
 
     Returns:
         The extracted content and the mime type of the content.
+
+    Raises:
+        ValidationError: If the file path or configuration is invalid.
     """
-    mime_type = validate_mime_type(file_path=file_path, mime_type=mime_type)
-    if extractor := ExtractorRegistry.get_extractor(mime_type=mime_type, config=config):
-        result = extractor.extract_path_sync(Path(file_path))
-    else:
-        result = ExtractionResult(
-            content=Path(file_path).read_text(),
-            chunks=[],
-            mime_type=mime_type,
-            metadata={},
-        )
-    return _validate_and_post_process_sync(result=result, config=config)
+    from kreuzberg._utils._document_cache import get_document_cache
+
+    cache = get_document_cache()
+    path = Path(file_path)
+    cached_result = cache.get(path, config)
+    if cached_result is not None:
+        return cached_result
+
+    if cache.is_processing(path, config):
+        event = cache.mark_processing(path, config)
+        event.wait()  # pragma: no cover
+
+        # Try cache again after waiting for other process to complete  # ~keep
+        cached_result = cache.get(path, config)  # pragma: no cover
+        if cached_result is not None:  # pragma: no cover
+            return cached_result
+
+    cache.mark_processing(path, config)
+
+    try:
+        if not path.exists():
+            raise ValidationError("The file does not exist", context={"file_path": str(path)})
+
+        mime_type = validate_mime_type(file_path=file_path, mime_type=mime_type)
+        if extractor := ExtractorRegistry.get_extractor(mime_type=mime_type, config=config):
+            result = extractor.extract_path_sync(Path(file_path))
+        else:
+            result = ExtractionResult(
+                content=Path(file_path).read_text(),
+                chunks=[],
+                mime_type=mime_type,
+                metadata={},
+            )
+
+        result = _validate_and_post_process_sync(result=result, config=config)
+
+        cache.set(path, config, result)
+
+        return result
+    finally:
+        cache.mark_complete(path, config)
 
 
 def batch_extract_file_sync(
     file_paths: Sequence[PathLike[str] | str], config: ExtractionConfig = DEFAULT_CONFIG
 ) -> list[ExtractionResult]:
-    """Synchronous version of batch_extract_file.
+    """Synchronous version of batch_extract_file with parallel processing.
 
     Args:
         file_paths: A sequence of paths to files to extract text from.
@@ -233,13 +359,54 @@ def batch_extract_file_sync(
     Returns:
         A list of extraction results in the same order as the input paths.
     """
-    return [extract_file_sync(file_path=Path(file_path), mime_type=None, config=config) for file_path in file_paths]
+    if len(file_paths) <= 1:
+        return [extract_file_sync(file_path=Path(file_path), mime_type=None, config=config) for file_path in file_paths]
+
+    import multiprocessing as mp
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+
+    max_workers = min(len(file_paths), mp.cpu_count())
+
+    def extract_single(file_path: PathLike[str] | str) -> tuple[int, ExtractionResult]:
+        """Extract single file with index for ordering."""
+        try:
+            return (
+                file_paths.index(file_path),
+                extract_file_sync(file_path=Path(file_path), mime_type=None, config=config),
+            )
+        except Exception as e:  # noqa: BLE001
+            from kreuzberg._utils._errors import create_error_context
+
+            error_result = ExtractionResult(
+                content=f"Error: {type(e).__name__}: {e!s}",
+                mime_type="text/plain",
+                metadata={  # type: ignore[typeddict-unknown-key]
+                    "error": True,
+                    "error_context": create_error_context(
+                        operation="batch_extract_file_sync",
+                        file_path=file_path,
+                        error=e,
+                    ),
+                },
+                chunks=[],
+            )
+            return (file_paths.index(file_path), error_result)
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        future_to_index = {executor.submit(extract_single, fp): i for i, fp in enumerate(file_paths)}
+
+        results: list[ExtractionResult] = [None] * len(file_paths)  # type: ignore[list-item]
+        for future in as_completed(future_to_index):
+            index, result = future.result()
+            results[index] = result
+
+    return results
 
 
 def batch_extract_bytes_sync(
     contents: Sequence[tuple[bytes, str]], config: ExtractionConfig = DEFAULT_CONFIG
 ) -> list[ExtractionResult]:
-    """Synchronous version of batch_extract_bytes.
+    """Synchronous version of batch_extract_bytes with parallel processing.
 
     Args:
         contents: A sequence of tuples containing (content, mime_type) pairs.
@@ -248,4 +415,48 @@ def batch_extract_bytes_sync(
     Returns:
         A list of extraction results in the same order as the input contents.
     """
-    return [extract_bytes_sync(content=content, mime_type=mime_type, config=config) for content, mime_type in contents]
+    if len(contents) <= 1:
+        return [
+            extract_bytes_sync(content=content, mime_type=mime_type, config=config) for content, mime_type in contents
+        ]
+
+    import multiprocessing as mp
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+
+    max_workers = min(len(contents), mp.cpu_count())
+
+    def extract_single(index_and_content: tuple[int, tuple[bytes, str]]) -> tuple[int, ExtractionResult]:
+        """Extract single content with index for ordering."""
+        index, (content, mime_type) = index_and_content
+        try:
+            return (index, extract_bytes_sync(content=content, mime_type=mime_type, config=config))
+        except Exception as e:  # noqa: BLE001
+            from kreuzberg._utils._errors import create_error_context
+
+            error_result = ExtractionResult(
+                content=f"Error: {type(e).__name__}: {e!s}",
+                mime_type="text/plain",
+                metadata={  # type: ignore[typeddict-unknown-key]
+                    "error": True,
+                    "error_context": create_error_context(
+                        operation="batch_extract_bytes_sync",
+                        error=e,
+                        index=index,
+                        mime_type=mime_type,
+                        content_size=len(content),
+                    ),
+                },
+                chunks=[],
+            )
+            return (index, error_result)
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        indexed_contents = list(enumerate(contents))
+        future_to_index = {executor.submit(extract_single, ic): i for i, ic in enumerate(indexed_contents)}
+
+        results: list[ExtractionResult] = [None] * len(contents)  # type: ignore[list-item]
+        for future in as_completed(future_to_index):
+            index, result = future.result()
+            results[index] = result
+
+    return results

kreuzberg-3.4.0.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: kreuzberg
+Version: 3.4.0
+Summary: A text extraction library supporting PDFs, images, office documents and more
+Project-URL: homepage, https://github.com/Goldziher/kreuzberg
+Author-email: Na'aman Hirschfeld <nhirschfed@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: document-processing,image-to-text,ocr,pandoc,pdf-extraction,rag,table-extraction,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.13
+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.13
+Requires-Dist: anyio>=4.9.0
+Requires-Dist: charset-normalizer>=3.4.2
+Requires-Dist: exceptiongroup>=1.2.2; python_version < '3.11'
+Requires-Dist: html-to-markdown>=1.4.0
+Requires-Dist: msgspec>=0.18.0
+Requires-Dist: playa-pdf>=0.6.1
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pypdfium2==4.30.0
+Requires-Dist: python-calamine>=0.3.2
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: typing-extensions>=4.14.0; python_version < '3.12'
+Provides-Extra: all
+Requires-Dist: click>=8.2.1; extra == 'all'
+Requires-Dist: easyocr>=1.7.2; extra == 'all'
+Requires-Dist: gmft>=0.4.2; extra == 'all'
+Requires-Dist: litestar[opentelemetry,standard,structlog]>=2.1.6; extra == 'all'
+Requires-Dist: paddleocr>=3.1.0; extra == 'all'
+Requires-Dist: paddlepaddle>=3.1.0; extra == 'all'
+Requires-Dist: rich>=14.0.0; extra == 'all'
+Requires-Dist: semantic-text-splitter>=0.27.0; extra == 'all'
+Requires-Dist: setuptools>=80.9.0; extra == 'all'
+Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'all'
+Provides-Extra: api
+Requires-Dist: litestar[opentelemetry,standard,structlog]>=2.1.6; extra == 'api'
+Provides-Extra: chunking
+Requires-Dist: semantic-text-splitter>=0.27.0; extra == 'chunking'
+Provides-Extra: cli
+Requires-Dist: click>=8.2.1; extra == 'cli'
+Requires-Dist: rich>=14.0.0; extra == 'cli'
+Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'cli'
+Provides-Extra: easyocr
+Requires-Dist: easyocr>=1.7.2; extra == 'easyocr'
+Provides-Extra: gmft
+Requires-Dist: gmft>=0.4.2; extra == 'gmft'
+Provides-Extra: paddleocr
+Requires-Dist: paddleocr>=3.1.0; extra == 'paddleocr'
+Requires-Dist: paddlepaddle>=3.1.0; extra == 'paddleocr'
+Requires-Dist: setuptools>=80.9.0; extra == 'paddleocr'
+Description-Content-Type: text/markdown
+
+# Kreuzberg
+
+[![Discord](https://img.shields.io/badge/Discord-Join%20our%20community-7289da)](https://discord.gg/pXxagNK2zN)
+[![PyPI version](https://badge.fury.io/py/kreuzberg.svg)](https://badge.fury.io/py/kreuzberg)
+[![Documentation](https://img.shields.io/badge/docs-GitHub_Pages-blue)](https://goldziher.github.io/kreuzberg/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Kreuzberg is a **high-performance** Python library for text extraction from documents. **Benchmarked as one of the fastest text extraction libraries available**, it provides a unified interface for extracting text from PDFs, images, office documents, and more, with both async and sync APIs optimized for speed and efficiency.
+
+## Why Kreuzberg?
+
+- **🚀 Substantially Faster**: Extraction speeds that significantly outperform other text extraction libraries
+- **⚡ Unique Dual API**: The only framework supporting both sync and async APIs for maximum flexibility
+- **💾 Memory Efficient**: Lower memory footprint compared to competing libraries
+- **📊 Proven Performance**: [Comprehensive benchmarks](https://github.com/Goldziher/python-text-extraction-libs-benchmarks) demonstrate superior performance across formats
+- **Simple and Hassle-Free**: Clean API that just works, without complex configuration
+- **Local Processing**: No external API calls or cloud dependencies required
+- **Resource Efficient**: Lightweight processing without GPU requirements
+- **Format Support**: Comprehensive support for documents, images, and text formats
+- **Multiple OCR Engines**: Support for Tesseract, EasyOCR, and PaddleOCR
+- **Command Line Interface**: Powerful CLI for batch processing and automation
+- **Metadata Extraction**: Get document metadata alongside text content
+- **Table Extraction**: Extract tables from documents using the excellent GMFT library
+- **Modern Python**: Built with async/await, type hints, and a functional-first approach
+- **Permissive OSS**: MIT licensed with permissively licensed dependencies
+
+## Quick Start
+
+```bash
+pip install kreuzberg
+
+# Or install with CLI support
+pip install "kreuzberg[cli]"
+
+# Or install with API server
+pip install "kreuzberg[api]"
+```
+
+Install pandoc:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install tesseract-ocr pandoc
+
+# macOS
+brew install tesseract pandoc
+
+# Windows
+choco install -y tesseract pandoc
+```
+
+The tesseract OCR engine is the default OCR engine. You can decide not to use it - and then either use one of the two alternative OCR engines, or have no OCR at all.
+
+### Alternative OCR engines
+
+```bash
+# Install with EasyOCR support
+pip install "kreuzberg[easyocr]"
+
+# Install with PaddleOCR support
+pip install "kreuzberg[paddleocr]"
+```
+
+## Quick Example
+
+```python
+import asyncio
+from kreuzberg import extract_file
+
+async def main():
+    # Extract text from a PDF
+    result = await extract_file("document.pdf")
+    print(result.content)
+
+    # Extract text from an image
+    result = await extract_file("scan.jpg")
+    print(result.content)
+
+    # Extract text from a Word document
+    result = await extract_file("report.docx")
+    print(result.content)
+
+asyncio.run(main())
+```
+
+## Docker
+
+Docker images are available for easy deployment:
+
+```bash
+# Run the API server
+docker run -p 8000:8000 goldziher/kreuzberg:latest
+
+# Extract files via API
+curl -X POST http://localhost:8000/extract -F "data=@document.pdf"
+```
+
+See the [Docker documentation](https://goldziher.github.io/kreuzberg/user-guide/docker/) for more options.
+
+## REST API
+
+Run Kreuzberg as a REST API server:
+
+```bash
+pip install "kreuzberg[api]"
+litestar --app kreuzberg._api.main:app run
+```
+
+See the [API documentation](https://goldziher.github.io/kreuzberg/user-guide/api-server/) for endpoints and usage.
+
+## Command Line Interface
+
+Kreuzberg includes a powerful CLI for processing documents from the command line:
+
+```bash
+# Extract text from a file
+kreuzberg extract document.pdf
+
+# Extract with JSON output and metadata
+kreuzberg extract document.pdf --output-format json --show-metadata
+
+# Extract from stdin
+cat document.html | kreuzberg extract
+
+# Use specific OCR backend
+kreuzberg extract image.png --ocr-backend easyocr --easyocr-languages en,de
+
+# Extract with configuration file
+kreuzberg extract document.pdf --config config.toml
+```
+
+### CLI Configuration
+
+Configure via `pyproject.toml`:
+
+```toml
+[tool.kreuzberg]
+force_ocr = true
+chunk_content = false
+extract_tables = true
+max_chars = 4000
+ocr_backend = "tesseract"
+
+[tool.kreuzberg.tesseract]
+language = "eng+deu"
+psm = 3
+```
+
+For full CLI documentation, see the [CLI Guide](https://goldziher.github.io/kreuzberg/cli/).
+
+## Documentation
+
+For comprehensive documentation, visit our [GitHub Pages](https://goldziher.github.io/kreuzberg/):
+
+- [Getting Started](https://goldziher.github.io/kreuzberg/getting-started/) - Installation and basic usage
+- [User Guide](https://goldziher.github.io/kreuzberg/user-guide/) - In-depth usage information
+- [CLI Guide](https://goldziher.github.io/kreuzberg/cli/) - Command-line interface documentation
+- [API Reference](https://goldziher.github.io/kreuzberg/api-reference/) - Detailed API documentation
+- [Examples](https://goldziher.github.io/kreuzberg/examples/) - Code examples for common use cases
+- [OCR Configuration](https://goldziher.github.io/kreuzberg/user-guide/ocr-configuration/) - Configure OCR engines
+- [OCR Backends](https://goldziher.github.io/kreuzberg/user-guide/ocr-backends/) - Choose the right OCR engine
+
+## Supported Formats
+
+Kreuzberg supports a wide range of document formats:
+
+- **Documents**: PDF, DOCX, RTF, TXT, EPUB, etc.
+- **Images**: JPG, PNG, TIFF, BMP, GIF, etc.
+- **Spreadsheets**: XLSX, XLS, CSV, etc.
+- **Presentations**: PPTX, PPT, etc.
+- **Web Content**: HTML, XML, etc.
+
+## OCR Engines
+
+Kreuzberg supports multiple OCR engines:
+
+- **Tesseract** (Default): Lightweight, fast startup, requires system installation
+- **EasyOCR**: Good for many languages, pure Python, but downloads models on first use
+- **PaddleOCR**: Excellent for Asian languages, pure Python, but downloads models on first use
+
+For comparison and selection guidance, see the [OCR Backends](https://goldziher.github.io/kreuzberg/user-guide/ocr-backends/) documentation.
+
+## Performance
+
+Kreuzberg delivers **exceptional performance** compared to other text extraction libraries:
+
+### 🏆 Competitive Benchmarks
+
+[Comprehensive benchmarks](https://github.com/Goldziher/python-text-extraction-libs-benchmarks) comparing Kreuzberg against other popular Python text extraction libraries show:
+
+- **Fastest Extraction**: Consistently fastest processing times across file formats
+- **Lowest Memory Usage**: Most memory-efficient text extraction solution
+- **100% Success Rate**: Reliable extraction across all tested document types
+- **Optimal for High-Throughput**: Designed for real-time, production applications
+
+### 💾 Installation Size Efficiency
+
+Kreuzberg delivers maximum performance with minimal overhead:
+
+1. **Kreuzberg**: 71.0 MB (20 deps) - Most lightweight
+1. **Unstructured**: 145.8 MB (54 deps) - Moderate footprint
+1. **MarkItDown**: 250.7 MB (25 deps) - ML inference overhead
+1. **Docling**: 1,031.9 MB (88 deps) - Full ML stack included
+
+**Kreuzberg is up to 14x smaller** than competing solutions while delivering superior performance.
+
+### ⚡ Sync vs Async Performance
+
+Kreuzberg is the only library offering both sync and async APIs. Choose based on your use case:
+
+| Operation              | Sync Time | Async Time | Async Advantage    |
+| ---------------------- | --------- | ---------- | ------------------ |
+| Simple text (Markdown) | 0.4ms     | 17.5ms     | **❌ 41x slower**  |
+| HTML documents         | 1.6ms     | 1.1ms      | **✅ 1.5x faster** |
+| Complex PDFs           | 39.0s     | 8.5s       | **✅ 4.6x faster** |
+| OCR processing         | 0.4s      | 0.7s       | **✅ 1.7x faster** |
+| Batch operations       | 38.6s     | 8.5s       | **✅ 4.5x faster** |
+
+**Rule of thumb:** Use async for complex documents, OCR, batch processing, and backend APIs.
+
+For detailed benchmarks and methodology, see our [Performance Documentation](https://goldziher.github.io/kreuzberg/advanced/performance/).
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details on setting up your development environment and submitting pull requests.
+
+## License
+
+This library is released under the MIT license.