ocr-llm 1.0.0__py3-none-any.whl

llm_ocr/__init__.py

@@ -0,0 +1,18 @@
+"""llm-ocr: Convert PDFs to markdown using LLMs."""
+
+from .config.settings import OCRConfig
+from .core.base import LLMProvider
+from .core.processor import LLMOCR
+
+# Import providers
+from .providers.gemini import Gemini
+from .providers.openai import OpenAI
+
+__version__ = "1.0.0"
+__all__ = [
+    "LLMOCR",
+    "OCRConfig",
+    "LLMProvider",
+    "Gemini",
+    "OpenAI",
+]

llm_ocr/config/settings.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class OCRConfig:
+    """Configuration for OCR processing."""
+
+    dpi: int = 200
+    max_pages: Optional[int] = None
+    batch_size: int = 5  # PDF to image conversion batch size
+    llm_batch_size: int = 1  # Number of pages to send to LLM at once
+    thread_count: int = 4
+    convert_to_grayscale: bool = False
+    optimize_png: bool = True
+    use_cropbox: bool = True
+    max_retries: int = 3
+    retry_delay: float = 1.0
+    output_format: str = "markdown"
+    include_page_markers: bool = False
+
+    def validate(self):
+        """Validate configuration."""
+        if self.dpi < 72 or self.dpi > 600:
+            raise ValueError("DPI must be between 72 and 600")
+        if self.batch_size < 1:
+            raise ValueError("Batch size must be at least 1")
+        if self.llm_batch_size < 1:
+            raise ValueError("LLM batch size must be at least 1")

llm_ocr/core/base.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class LLMProvider(ABC):
+    """Abstract base class for LLM providers."""
+
+    def __init__(self, api_key: str, model: str, **kwargs):
+        """
+        Initialize the LLM provider.
+
+        Args:
+            api_key: API key for the provider
+            model: Model identifier/name
+            **kwargs: Additional provider-specific parameters
+        """
+        self.api_key = api_key
+        self.model = model
+        self.kwargs = kwargs
+
+    @abstractmethod
+    async def generate_content(
+        self,
+        prompt: str,
+        image_bytes_list: List[bytes],
+    ) -> str:
+        """
+        Generate content from images and prompt.
+
+        Args:
+            prompt: The instruction prompt
+            image_bytes_list: List of PNG image bytes (one or more pages)
+
+        Returns:
+            Generated text content
+        """
+        pass
+
+    @abstractmethod
+    async def aclose(self):
+        """Close and cleanup resources."""
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the provider name."""
+        pass

llm_ocr/core/processor.py

@@ -0,0 +1,224 @@
+import asyncio
+import io
+import tempfile
+from pathlib import Path
+from typing import AsyncIterable, List, Optional, Tuple, Union
+
+from pdf2image import convert_from_path, pdfinfo_from_path
+from PIL import Image
+
+from ..config.settings import OCRConfig
+from ..core.base import LLMProvider
+from ..prompts.markdown import MARKDOWN_SYSTEM_PROMPT
+
+
+class LLMOCR:
+    """Main processor for converting PDFs to markdown using LLMs."""
+
+    def __init__(self, provider: LLMProvider, config: Optional[OCRConfig] = None):
+        """
+        Initialize LLM OCR converter.
+
+        Args:
+            provider: An instance of an LLM provider (Gemini, OpenAI, etc.)
+            config: OCRConfig object for processing settings
+        """
+        if not isinstance(provider, LLMProvider):
+            raise TypeError(
+                f"provider must be an instance of LLMProvider, got {type(provider)}"
+            )
+
+        self.provider = provider
+        self.config = config or OCRConfig()
+        self.config.validate()
+
+    def _process_image_to_bytes(self, img_path: str) -> bytes:
+        """Convert image file to PNG bytes."""
+        with Image.open(img_path) as im:
+            if self.config.convert_to_grayscale:
+                im = im.convert("L")
+            buff = io.BytesIO()
+            im.save(buff, format="PNG", optimize=self.config.optimize_png)
+            return buff.getvalue()
+
+    async def _iter_pdf_pages_as_png_bytes(
+        self, pdf_path: Path
+    ) -> AsyncIterable[Tuple[int, bytes]]:
+        """Yield (page_number, png_bytes) for each page."""
+        info = pdfinfo_from_path(pdf_path)
+        total_pages = info["Pages"]
+        if self.config.max_pages:
+            total_pages = min(total_pages, self.config.max_pages)
+
+        page = 1
+        with tempfile.TemporaryDirectory() as tmpdir:
+            while page <= total_pages:
+                first = page
+                last = min(page + self.config.batch_size - 1, total_pages)
+
+                img_paths = convert_from_path(
+                    pdf_path,
+                    dpi=self.config.dpi,
+                    first_page=first,
+                    last_page=last,
+                    output_folder=tmpdir,
+                    fmt="png",
+                    paths_only=True,
+                    thread_count=self.config.thread_count,
+                    use_cropbox=self.config.use_cropbox,
+                )
+
+                for p, img_path in enumerate(img_paths, start=first):
+                    png_bytes = await asyncio.to_thread(
+                        self._process_image_to_bytes, img_path
+                    )
+                    yield p, png_bytes
+
+                page = last + 1
+
+    async def _process_batch_with_llm(
+        self, png_bytes_list: List[bytes], page_nums: List[int], total_pages: int
+    ) -> str:
+        """Process a batch of pages with the LLM provider."""
+        # Format page range for prompt
+        if len(page_nums) == 1:
+            page_range = f"{page_nums[0]}"
+        else:
+            page_range = f"{page_nums[0]}-{page_nums[-1]}"
+
+        prompt = MARKDOWN_SYSTEM_PROMPT.format(
+            page_range=page_range, total_pages=total_pages
+        )
+
+        try:
+            content = await self.provider.generate_content(prompt, png_bytes_list)
+            return content.strip()
+        except Exception as err:
+            print(f"[ERROR] Pages {page_range}: Failed to process: {err}")
+            raise  # Fail-fast: re-raise to stop processing
+
+    def _combine_markdown_chunks(self, chunks: List[str]) -> str:
+        """Combine markdown chunks from multiple pages."""
+        combined = []
+
+        for i, chunk in enumerate(chunks):
+            if not chunk.strip():
+                continue
+
+            # Add page separator comment for debugging (optional)
+            if i > 0 and self.config.include_page_markers:
+                combined.append(f"\n<!-- Page {i + 1} -->\n")
+
+            combined.append(chunk)
+
+        return "\n\n".join(combined)
+
+    async def aclose(self):
+        """Close and cleanup resources."""
+        await self.provider.aclose()
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.aclose()
+
+    async def convert(
+        self, pdf_path: Union[str, Path], output_path: Optional[Union[str, Path]] = None
+    ) -> str:
+        """
+        Convert PDF to markdown.
+
+        Args:
+            pdf_path: Path to the PDF file
+            output_path: Optional path to save the markdown file
+
+        Returns:
+            Markdown content as string
+        """
+        pdf_path = Path(pdf_path)
+
+        if not pdf_path.exists():
+            raise FileNotFoundError(f"PDF file not found: {pdf_path}")
+
+        # Get total pages
+        info = pdfinfo_from_path(pdf_path)
+        total_pages = info["Pages"]
+        if self.config.max_pages:
+            total_pages = min(total_pages, self.config.max_pages)
+
+        print(f"[INFO] Converting PDF: {pdf_path.name} ({total_pages} pages)")
+        print(f"[INFO] Using provider: {self.provider.name} ({self.provider.model})")
+        print(f"[INFO] LLM batch size: {self.config.llm_batch_size}")
+
+        markdown_chunks = []
+
+        # Collect pages into batches according to llm_batch_size
+        page_batch = []
+        page_num_batch = []
+
+        async for page_num, png_bytes in self._iter_pdf_pages_as_png_bytes(pdf_path):
+            page_batch.append(png_bytes)
+            page_num_batch.append(page_num)
+
+            # Process batch when it reaches llm_batch_size or this is the last page
+            if len(page_batch) >= self.config.llm_batch_size or page_num == total_pages:
+                # Retry logic for transient errors
+                markdown_content = ""
+                for attempt in range(self.config.max_retries):
+                    try:
+                        markdown_content = await self._process_batch_with_llm(
+                            page_batch, page_num_batch, total_pages
+                        )
+                        break
+                    except Exception as e:
+                        if attempt == self.config.max_retries - 1:
+                            page_range = (
+                                f"{page_num_batch[0]}-{page_num_batch[-1]}"
+                                if len(page_num_batch) > 1
+                                else str(page_num_batch[0])
+                            )
+                            print(
+                                f"[ERROR] Pages {page_range}: Failed after "
+                                f"{self.config.max_retries} attempts: {e}"
+                            )
+                            raise  # Fail-fast: stop processing on failure
+                        await asyncio.sleep(self.config.retry_delay * (attempt + 1))
+
+                if markdown_content.strip():
+                    page_range = (
+                        f"{page_num_batch[0]}-{page_num_batch[-1]}"
+                        if len(page_num_batch) > 1
+                        else str(page_num_batch[0])
+                    )
+                    print(
+                        f"[OK] Pages {page_range}/{total_pages} processed "
+                        f"({len(markdown_content)} chars)"
+                    )
+                    markdown_chunks.append(markdown_content)
+                else:
+                    page_range = (
+                        f"{page_num_batch[0]}-{page_num_batch[-1]}"
+                        if len(page_num_batch) > 1
+                        else str(page_num_batch[0])
+                    )
+                    print(f"[OK] Pages {page_range}/{total_pages} - No content")
+
+                # Clear the batch
+                page_batch = []
+                page_num_batch = []
+
+        # Combine all chunks
+        final_markdown = self._combine_markdown_chunks(markdown_chunks)
+
+        # Save to file if output path provided
+        if output_path:
+            output_path = Path(output_path)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(final_markdown, encoding="utf-8")
+            print(f"[DONE] Saved to: {output_path}")
+
+        print(f"[DONE] Generated {len(final_markdown)} characters of markdown")
+        return final_markdown

llm_ocr/prompts/markdown.py

@@ -0,0 +1,33 @@
+from textwrap import dedent
+
+MARKDOWN_SYSTEM_PROMPT = dedent(
+    """
+    You are an expert at converting document images to markdown format.
+    
+    Your task is to accurately transcribe all text content from the image(s) and format it as clean, readable markdown.
+    
+    FORMATTING RULES:
+    - Use proper markdown headers (# ## ###) for document structure
+    - Preserve lists (ordered and unordered)
+    - Format tables using markdown table syntax
+    - Use **bold** and *italic* for emphasized text
+    - Preserve code blocks with ```language syntax
+    - Use > for blockquotes
+    - Keep links and images in markdown format
+    - Maintain paragraph breaks and spacing
+    
+    CRITICAL RULES:
+    - DO NOT add any commentary, explanations, or meta-text
+    - DO NOT include markdown code fences (```) around your output
+    - Output ONLY the markdown content itself
+    - If a page is blank or contains no meaningful content, skip it
+    - Preserve the original document's structure and hierarchy
+    - For multi-column layouts, process left to right, top to bottom
+    - When processing multiple pages, combine them into a single coherent output
+    - Maintain continuity across pages (e.g., tables, paragraphs spanning pages)
+    
+    PAGES: {page_range} of {total_pages}
+    
+    Output only the markdown content:
+    """
+)

llm_ocr/providers/__init__.py

@@ -0,0 +1,4 @@
+from .gemini import Gemini
+from .openai import OpenAI
+
+__all__ = ["Gemini", "OpenAI"]

llm_ocr/providers/gemini.py

@@ -0,0 +1,87 @@
+import os
+from typing import List, Optional
+
+from google.genai import Client, types
+
+from ..core.base import LLMProvider
+
+
+class Gemini(LLMProvider):
+    """
+    Google Gemini provider for OCR.
+
+    Supported models:
+    - gemini-2.5-pro (recommended, best quality)
+    - gemini-2.5-flash (fast)
+    - gemini-2.0-pro
+    - gemini-2.0-flash
+    """
+
+    # Available models with their identifiers
+    FLASH_2_5 = "gemini-2.5-flash"
+    PRO_2_5 = "gemini-2.5-pro"
+    FLASH_2_0 = "gemini-2.0-flash"
+    PRO_2_0 = "gemini-2.0-pro"
+
+    def __init__(self, api_key: Optional[str] = None, model: str = FLASH_2_5, **kwargs):
+        """
+        Initialize Gemini provider.
+
+        Args:
+            api_key: Gemini API key. If None, reads from GEMINI_API_KEY env var
+            model: Model to use. Use Gemini.FLASH_2_5, Gemini.PRO_2_5, etc.
+            **kwargs: Additional parameters for the Gemini API
+        """
+        api_key = api_key or os.getenv("GEMINI_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "Gemini API key is required. "
+                "Pass it directly or set GEMINI_API_KEY environment variable."
+            )
+
+        super().__init__(api_key, model, **kwargs)
+
+        # Initialize the async client
+        client = Client(api_key=self.api_key)
+        self.aclient = client.aio
+
+    @property
+    def name(self) -> str:
+        """Return provider name."""
+        return "gemini"
+
+    async def generate_content(
+        self,
+        prompt: str,
+        image_bytes_list: List[bytes],
+    ) -> str:
+        """Generate content using Gemini with one or more images."""
+        # Create image parts for all images in the batch
+        image_parts = [
+            types.Part(inline_data=types.Blob(mime_type="image/png", data=image_bytes))
+            for image_bytes in image_bytes_list
+        ]
+
+        # Combine prompt and all images
+        contents = [prompt] + image_parts
+
+        try:
+            resp = await self.aclient.models.generate_content(
+                model=self.model, contents=contents, **self.kwargs
+            )
+
+            try:
+                return resp.text or ""
+            except (ValueError, AttributeError):
+                print("[WARNING] Gemini returned no content")
+                return ""
+
+        except Exception as err:
+            print(f"[ERROR] Gemini generation failed: {err}")
+            raise
+
+    async def aclose(self):
+        """Close the Gemini client."""
+        # The Google GenAI AsyncClient doesn't require explicit closing
+        # Resources are cleaned up automatically
+        pass

llm_ocr/providers/openai.py

@@ -0,0 +1,123 @@
+import base64
+import os
+from typing import List, Optional
+
+from openai import AsyncOpenAI
+
+from ..core.base import LLMProvider
+
+
+class OpenAI(LLMProvider):
+    """
+    OpenAI provider for OCR.
+
+    Supported models:
+    - gpt-5
+    - gpt-5-mini
+    - gpt-5-nano
+    - gpt-5-chat-latest
+    - gpt-4.1
+    - gpt-4.1-mini
+    - gpt-4.1-nano
+    - o4-mini
+    - o1
+    - o3
+    - gpt-4o
+    - gpt-4o-mini
+    """
+
+    # Available models with their identifiers
+    GPT_5 = "gpt-5"
+    GPT_5_MINI = "gpt-5-mini"
+    GPT_5_NANO = "gpt-5-nano"
+    GPT_5_CHAT_LATEST = "gpt-5-chat-latest"
+
+    GPT_4_1 = "gpt-4.1"
+    GPT_4_1_MINI = "gpt-4.1-mini"
+    GPT_4_1_NANO = "gpt-4.1-nano"
+
+    O4_MINI = "o4-mini"
+    O1 = "o1"
+    O3 = "o3"
+
+    GPT_4O = "gpt-4o"
+    GPT_4O_MINI = "gpt-4o-mini"
+
+    def __init__(
+        self, api_key: Optional[str] = None, model: str = GPT_4O_MINI, **kwargs
+    ):
+        """
+        Initialize OpenAI provider.
+
+        Args:
+            api_key: OpenAI API key. If None, reads from OPENAI_API_KEY env var
+            model: Model to use. Use OpenAI.GPT_4O, OpenAI.GPT_4O_MINI, etc.
+            **kwargs: Additional parameters for the OpenAI API (e.g., max_tokens, temperature)
+        """
+        api_key = api_key or os.getenv("OPENAI_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "OpenAI API key is required. "
+                "Pass it directly or set OPENAI_API_KEY environment variable."
+            )
+
+        super().__init__(api_key, model, **kwargs)
+
+        # Initialize the async client
+        self.aclient = AsyncOpenAI(api_key=self.api_key)
+
+    @property
+    def name(self) -> str:
+        """Return provider name."""
+        return "openai"
+
+    async def generate_content(
+        self,
+        prompt: str,
+        image_bytes_list: List[bytes],
+    ) -> str:
+        """Generate content using OpenAI with one or more images."""
+        # Create content array with text prompt
+        content = [{"type": "text", "text": prompt}]
+
+        # Add all images as base64-encoded data URLs
+        for image_bytes in image_bytes_list:
+            b64_image = base64.b64encode(image_bytes).decode("utf-8")
+            content.append(
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": f"data:image/png;base64,{b64_image}",
+                    },
+                }
+            )
+
+        try:
+            # Use the Chat Completions API with vision
+            response = await self.aclient.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": content,
+                    }
+                ],
+                **self.kwargs,
+            )
+
+            # Extract the text content from the response
+            if response.choices and len(response.choices) > 0:
+                message_content = response.choices[0].message.content
+                return message_content or ""
+            else:
+                print("[WARNING] OpenAI returned no content")
+                return ""
+
+        except Exception as err:
+            print(f"[ERROR] OpenAI generation failed: {err}")
+            raise
+
+    async def aclose(self):
+        """Close the OpenAI client."""
+        # Close the async client
+        await self.aclient.close()

ocr_llm-1.0.0.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: ocr-llm
+Version: 1.0.0
+Summary: Convert PDFs to markdown using Large Language Models (LLMs) with vision capabilities
+Author-email: Shehryar Sohail <hafizshehryar88@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Shehryar718/llm-ocr
+Project-URL: Repository, https://github.com/Shehryar718/llm-ocr
+Project-URL: Issues, https://github.com/Shehryar718/llm-ocr/issues
+Keywords: ocr,pdf,markdown,llm,vision,gemini,openai,ai
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdf2image>=1.16.0
+Requires-Dist: Pillow>=11.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: openai>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.5.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: isort>=6.0.0; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.10.0; extra == "dev"
+Dynamic: license-file
+
+# LLM OCR
+
+[![PyPI](https://img.shields.io/pypi/v/ocr-llm)](https://pypi.org/project/ocr-llm/)
+[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)](https://pypi.org/project/ocr-llm/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Shehryar718/llm-ocr/blob/main/LICENSE)
+
+Convert PDFs to markdown using Large Language Models (LLMs) with vision capabilities.
+
+## Features
+
+- 🔍 High-quality OCR using vision-capable LLMs
+- 📄 Batch processing of multiple PDF pages
+- 🔌 Multiple provider support (Gemini, OpenAI)
+- ⚙️ Configurable processing settings
+- 🔄 Automatic retry logic for transient errors
+- 📝 Clean markdown output
+
+## Installation
+
+```bash
+pip install ocr-llm
+```
+
+### System Dependencies
+
+You also need to install poppler (required for PDF processing):
+
+```bash
+# macOS
+brew install poppler
+
+# Ubuntu/Debian
+sudo apt-get install poppler-utils
+
+# Fedora/RHEL
+sudo yum install poppler-utils
+```
+
+### Dependencies
+
+The library requires:
+
+- **System**: `poppler-utils` for PDF processing
+- **Python**:
+  - `google-genai` for Gemini provider
+  - `openai` for OpenAI provider
+  - `pdf2image` and `Pillow` for PDF processing
+
+## Quick Start
+
+### Using OpenAI
+
+```python
+import asyncio
+from llm_ocr import LLMOCR, OpenAI
+
+async def main():
+    # Initialize OpenAI provider
+    provider = OpenAI(
+        api_key="your-api-key",  # Or set OPENAI_API_KEY env var
+        model=OpenAI.GPT_4O_MINI
+    )
+
+    # Create OCR processor
+    async with LLMOCR(provider) as ocr:
+        # Convert PDF to markdown
+        markdown = await ocr.convert(
+            "document.pdf",
+            output_path="output.md"
+        )
+        print(markdown)
+
+asyncio.run(main())
+```
+
+### Using Gemini
+
+```python
+import asyncio
+from llm_ocr import LLMOCR, Gemini
+
+async def main():
+    # Initialize Gemini provider
+    provider = Gemini(
+        api_key="your-api-key",  # Or set GEMINI_API_KEY env var
+        model=Gemini.FLASH_2_5  # Or Gemini.PRO_2_5 for best quality
+    )
+
+    # Create OCR processor
+    async with LLMOCR(provider) as ocr:
+        # Convert PDF to markdown
+        markdown = await ocr.convert(
+            "document.pdf",
+            output_path="output.md"
+        )
+        print(markdown)
+
+asyncio.run(main())
+```
+
+## Available Models
+
+### OpenAI
+
+- `OpenAI.GPT_4O`
+- `OpenAI.GPT_4O_MINI` (default)
+
+Additional models: `O1`, `O3`, `O4_MINI`, `GPT_5`, `GPT_5_MINI`, `GPT_4_1`, and more.
+
+> See `llm_ocr/providers/openai.py` for the complete list.
+
+### Gemini
+
+- `Gemini.PRO_2_5`
+- `Gemini.FLASH_2_5` (default)
+
+Additional models: `PRO_2_0`, `FLASH_2_0`.
+
+> See `llm_ocr/providers/gemini.py` for the complete list.
+
+## Configuration
+
+Customize the OCR processing with `OCRConfig`:
+
+```python
+from llm_ocr import LLMOCR, OpenAI, OCRConfig
+
+config = OCRConfig(
+    dpi=300,                    # Higher DPI for better quality
+    max_pages=10,               # Limit number of pages to process
+    llm_batch_size=2,           # Send 2 pages to LLM at once
+    convert_to_grayscale=True,  # Convert images to grayscale
+    max_retries=3,              # Retry failed requests
+    retry_delay=1.0,            # Wait 1 second between retries
+    include_page_markers=True,  # Add page markers in output
+)
+
+provider = OpenAI()
+ocr = LLMOCR(provider, config=config)
+```
+
+### Configuration Options
+
+| Option                 | Default | Description                                |
+| ---------------------- | ------- | ------------------------------------------ |
+| `dpi`                  | 200     | DPI for PDF to image conversion (72-600)   |
+| `max_pages`            | None    | Maximum number of pages to process         |
+| `batch_size`           | 5       | PDF to image conversion batch size         |
+| `llm_batch_size`       | 1       | Number of pages to send to LLM at once     |
+| `thread_count`         | 4       | Number of threads for PDF conversion       |
+| `convert_to_grayscale` | False   | Convert images to grayscale                |
+| `optimize_png`         | True    | Optimize PNG compression                   |
+| `use_cropbox`          | True    | Use PDF cropbox for conversion             |
+| `max_retries`          | 3       | Maximum retry attempts for failed requests |
+| `retry_delay`          | 1.0     | Delay between retries in seconds           |
+| `include_page_markers` | False   | Add page markers in markdown output        |
+
+## Advanced Usage
+
+### Custom Provider Parameters
+
+Pass additional parameters to the LLM provider:
+
+```python
+# OpenAI with custom parameters
+provider = OpenAI(
+    model=OpenAI.GPT_4O,
+    max_tokens=4000,
+    temperature=0.0,
+)
+
+# Gemini with custom parameters
+provider = Gemini(
+    model=Gemini.PRO_2_5,
+    temperature=0.0,
+)
+```
+
+### Processing Multiple Documents
+
+```python
+import asyncio
+from pathlib import Path
+from llm_ocr import LLMOCR, OpenAI
+
+async def process_documents():
+    provider = OpenAI()
+
+    async with LLMOCR(provider) as ocr:
+        pdf_files = Path("pdfs").glob("*.pdf")
+
+        for pdf_file in pdf_files:
+            output_file = pdf_file.with_suffix(".md")
+            await ocr.convert(pdf_file, output_path=output_file)
+            print(f"Converted {pdf_file.name} -> {output_file.name}")
+
+asyncio.run(process_documents())
+```
+
+### Without Context Manager
+
+If you prefer not to use the context manager:
+
+```python
+import asyncio
+from llm_ocr import LLMOCR, OpenAI
+
+async def main():
+    provider = OpenAI()
+    ocr = LLMOCR(provider)
+
+    try:
+        markdown = await ocr.convert("document.pdf")
+        print(markdown)
+    finally:
+        await ocr.aclose()  # Don't forget to close!
+
+asyncio.run(main())
+```
+
+## Environment Variables
+
+Set API keys via environment variables:
+
+```bash
+# For OpenAI
+export OPENAI_API_KEY="your-openai-api-key"
+
+# For Gemini
+export GEMINI_API_KEY="your-gemini-api-key"
+```
+
+Then use providers without passing API keys:
+
+```python
+# API key read from environment variable
+provider = OpenAI()  # Uses OPENAI_API_KEY
+# or
+provider = Gemini()  # Uses GEMINI_API_KEY
+```
+
+## Error Handling
+
+The library uses a fail-fast approach with automatic retries:
+
+```python
+import asyncio
+from llm_ocr import LLMOCR, OpenAI, OCRConfig
+
+async def main():
+    provider = OpenAI()
+    config = OCRConfig(
+        max_retries=5,      # Retry up to 5 times
+        retry_delay=2.0,    # Wait 2 seconds between retries
+    )
+
+    async with LLMOCR(provider, config) as ocr:
+        try:
+            markdown = await ocr.convert("document.pdf")
+            print(markdown)
+        except Exception as e:
+            print(f"Failed to process document: {e}")
+
+asyncio.run(main())
+```
+
+## License
+
+See LICENSE file for details.

ocr_llm-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+llm_ocr/__init__.py,sha256=85oykW2FSKOFMZKUccUW5wEs8Wlk5-8Q8KBPyL0GF4c,371
+llm_ocr/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llm_ocr/config/settings.py,sha256=WzZfNKTj1VZ4yS0bCEmVX9R5IxwGtMeje9x6hiHzE9U,943
+llm_ocr/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llm_ocr/core/base.py,sha256=guS3dTsGBFzAKXTjIni3w2oeHNM6EAOQYqaKLoOkJqw,1140
+llm_ocr/core/processor.py,sha256=kbCnmXNaRoyVyA2m170FARKf_Z2nbZDgcRLZPMj2Xr0,8380
+llm_ocr/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llm_ocr/prompts/markdown.py,sha256=ik6QhFLVsnxDVTN-z1S7tjHaZGcZJ8wcdnCPhfv5ZHY,1336
+llm_ocr/providers/__init__.py,sha256=Sf8t5ZxwOZ7XlwxX0OSXlgYMPhAaEc6JhUdO58zgk6k,86
+llm_ocr/providers/gemini.py,sha256=_Fo-AKF5XStQ-7stti2GfBbs9DQsf88hUo0vcJxfhKw,2603
+llm_ocr/providers/openai.py,sha256=RFuwsaYae3WDQd6V1plN4q88owg9B4Q2W0h1GwdfHvw,3402
+ocr_llm-1.0.0.dist-info/licenses/LICENSE,sha256=YNyaca-Sr7AUZJKoh_1wWi9GN6PRNZErWfIASRtCBAM,1072
+ocr_llm-1.0.0.dist-info/METADATA,sha256=5j_lVKX0Ef_KaGoR5dD5sF9uzbWaKV3001ADLUy67Sc,8411
+ocr_llm-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ocr_llm-1.0.0.dist-info/top_level.txt,sha256=kUf9ARPXFNWvv-LRnhJPYz7BbBgPNDi9uesrPduvD0k,8
+ocr_llm-1.0.0.dist-info/RECORD,,

ocr_llm-1.0.0.dist-info/WHEEL

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

ocr_llm-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shehryar Sohail
+
+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.

ocr_llm-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llm_ocr