ebook2text 2.2.0__tar.gz → 2.3.2__tar.gz

{ebook2text-2.2.0 → ebook2text-2.3.2}/PKG-INFO

@@ -1,54 +1,58 @@
 Metadata-Version: 2.4
 Name: ebook2text
-Version: 2.2.0
+Version: 2.3.2
 Summary: Convert common book file types to text for machine learning
 Author: Ashlynn Antrobus
 Author-email: Ashlynn Antrobus <ashlynn@prosepal.io>
-License: MIT
-Project-URL: Repository, https://github.com/ashrobertsdragon/Ebook-conversion-to-Text-for-Machine-Learning
-Classifier: License :: OSI Approved :: MIT License
+Project-URL: Repository, https://github.com/ashrobertsdragon/ebook2text
 Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Text Processing
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: beautifulsoup4>=4.12.3
-Requires-Dist: ebooklib-autoupdate>=0.18.3
+Requires-Dist: ebooklib>=0.20
 Requires-Dist: openai>=1.54.3
 Requires-Dist: pdfminer-six>=20240706
-Requires-Dist: pillow>=10.4.0
+Requires-Dist: pillow>=12.3.0
 Requires-Dist: python-docx>=1.1.2
 Requires-Dist: python-dotenv>=1.0.1
+Provides-Extra: all
+Requires-Dist: ebook2text[anthropic,gemini]; extra == "all"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == "gemini"
 Dynamic: author
 
-
 # Ebook2Text
 
 ## Overview
 
-This Python script provides functionality for converting various ebook file formats (EPUB, DOCX, PDF, TXT) into a standardized text format. The script processes each file, identifying chapters, and replaces chapter headers with asterisks. It also performs OCR (Optical Character Recognition) for image-based text using GPT-4o and standardizes the text by converting smart punctuation.
+This Python script provides functionality for converting various ebook file formats (EPUB, DOCX, PDF, TXT) into a standardized text format. The script processes each file, identifying chapters, and replaces chapter headers with asterisks. It also performs OCR (Optical Character Recognition) for image-based text using a vision-capable AI model and standardizes the text by converting smart punctuation.
 
 ## Features
 
 - **File Format Support**: Handles EPUB, DOCX, PDF, and TXT formats.
 - **Chapter Identification**: Detects and marks chapter breaks.
 - **OCR Capability**: Converts text from images using OCR.
+- **Multiple AI Providers**: OpenAI, Google Gemini, Anthropic, and OpenRouter.
 - **Text Standardization**: Replaces smart punctuation with ASCII equivalents.
 
 ## Requirements
 
-To run this script, you need Python 3.9 or above and the following packages:
+To run this script, you need Python 3.10 or above and the following packages:
 
 - `bs4`
 - `ebooklib-autoupdate`
@@ -58,11 +62,45 @@ To run this script, you need Python 3.9 or above and the following packages:
 - `python-dotenv`
 - `openai`
 
+The OpenAI SDK is a core dependency and also serves OpenRouter. Gemini and Anthropic need optional extras:
+
+```bash
+pip install ebook2text[gemini]     # Google Gemini
+pip install ebook2text[anthropic]  # Anthropic Claude
+pip install ebook2text[all]        # both
+```
+
+## AI provider configuration
+
+OCR runs through one of four providers, selected by environment variable. See `.env.sample` for a complete template.
+
+| Variable                                                                         | Purpose                                          | Default                      |
+| -------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------- |
+| `OCR_PROVIDER`                                                                   | `openai`, `gemini`, `anthropic`, or `openrouter` | `openai`                     |
+| `OCR_MODEL`                                                                      | Model name for the chosen provider               | falls back to `OPENAI_MODEL` |
+| `OCR_MAX_TOKENS`                                                                 | Maximum tokens in the OCR response               | `1000`                       |
+| `OPENAI_API_KEY` / `GEMINI_API_KEY` / `ANTHROPIC_API_KEY` / `OPENROUTER_API_KEY` | API key for the selected provider                | —                            |
+
+API keys and models are read the first time an image is actually processed, so importing the library and converting text-only books requires no configuration at all.
+
+To choose a provider programmatically instead, pass one to `convert_file`:
+
+```python
+from ebook2text import convert_file, get_ocr_provider
+
+provider = get_ocr_provider(provider="anthropic", model="claude-haiku-4-5")
+text = convert_file(
+    file_path, metadata, save_file=False, ocr_provider=provider
+)
+```
+
+Any object with a `perform_ocr(base64_images: list[str]) -> str` method satisfies the `OCRProvider` protocol, so you can supply your own implementation.
+
 ## Usage
 
 1. Ensure all dependencies are installed.
-2. Set your environment variable for the OpenAI API key.
-3. Run `convert_file` from the `convert_file` module with the path to the ebook file and a metadata dictionary with keys of 'title' and 'author' as arguments.
+1. Set your environment variables for the AI provider (see above).
+1. Run `convert_file` from the `convert_file` module with the path to the ebook file and a metadata dictionary with keys of 'title' and 'author' as arguments.
 
 - set `save_file` to False, if you want a string returned.
 - set `save_file` to True or leave blank, and provide a Path object to `save_path` to use a custom output filename.
@@ -95,7 +133,7 @@ Converts an ebook file to a standardized text format.
 `ebook2text.convert_file.py`
 
 **Signature**:
-`convert_file(file_path: Path, metadata: dict, *, save_file: bool = True, save_path: Optional[Path] = None) -> Union[str, None]`
+`convert_file(file_path: Path, metadata: dict, *, save_file: bool = True, save_path: Path | None = None, ocr_provider: OCRProvider | None = None) -> str | None`
 
 **Arguments**:
 
@@ -103,7 +141,10 @@ Converts an ebook file to a standardized text format.
 - `metadata`: Dictionary containing the book's `title` and `author`.
 - `save_file`: Boolean flag. If `True`, saves the converted text to a file; otherwise, returns it as a string. Defaults to `True`.
 - `save_path`: Optional path to save the output file. Defaults to a generated name in the input file's directory.
+- `ocr_provider`: Optional OCR provider for image text extraction. Defaults to the provider configured by environment variables.
+
 **Returns**:
+
 - If `save_file` is `True`: Returns `None`.
 - If `save_file` is `False`: Returns the converted text as a string.
 
@@ -119,12 +160,13 @@ Initializes a PDFConverter instance for handling PDF files.
 `ebook2_text.pdf_converter`
 
 **Signature**:
-`initialize_pdf_converter(file_path: Path, metadata: dict) -> PDFConverter`
+`initialize_pdf_converter(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> PDFConverter`
 
 **Arguments**:
 
 - `file_path`: Path to the PDF file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Returns**:
 
@@ -139,12 +181,13 @@ Convenience function for reading and processing a PDF file, splitting its conten
 
 **Signature**:
 
-convert_pdf(file_path: Path, metadata: dict) -> Generator[str, None, None]
+convert_pdf(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> Generator[str, None, None]
 
 **Arguments**:
 
 - `file_path`: Path to the PDF file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Yields**:
 
@@ -176,12 +219,13 @@ Initializes a EpubConverter instance for handling Epub files.
 `ebook2_text.epub_converter`
 
 **Signature**:
-`initialize_epub_converter(file_path: Path, metadata: dict) -> EpubConverter`
+`initialize_epub_converter(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> EpubConverter`
 
 **Arguments**:
 
 - `file_path`: Path to the Epub file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Returns**:
 
@@ -196,12 +240,13 @@ Convenience function for reading and processing a Epub file, splitting its conte
 
 **Signature**:
 
-convert_epub(file_path: Path, metadata: dict) -> Generator[str, None, None]
+convert_epub(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> Generator[str, None, None]
 
 **Arguments**:
 
 - `file_path`: Path to the Epub file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Yields**:
 
@@ -233,12 +278,13 @@ Initializes a DocxConverter instance for handling Docx files.
 `ebook2_text.docx_converter`
 
 **Signature**:
-`initialize_docx_converter(file_path: Path, metadata: dict) -> DocxConverter`
+`initialize_docx_converter(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> DocxConverter`
 
 **Arguments**:
 
 - `file_path`: Path to the Docx file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Returns**:
 
@@ -253,12 +299,13 @@ Convenience function for reading and processing a Docx file, splitting its conte
 
 **Signature**:
 
-convert_docx(file_path: Path, metadata: dict) -> Generator[str, None, None]
+convert_docx(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> Generator[str, None, None]
 
 **Arguments**:
 
 - `file_path`: Path to the Docx file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Yields**:
 
@@ -292,7 +339,6 @@ Contributions to this project are welcome. Please use Ruff for formatting to ens
   - Tests for text converter
   - More edge cases and failure states
 - Better handling of ebooklib dependency
-- Add additional AI models for OCR as plugins
 - Explore additional filetypes
 - Other options for determining filetype
 

{ebook2text-2.2.0 → ebook2text-2.3.2}/README.md

@@ -1,20 +1,20 @@
-
 # Ebook2Text
 
 ## Overview
 
-This Python script provides functionality for converting various ebook file formats (EPUB, DOCX, PDF, TXT) into a standardized text format. The script processes each file, identifying chapters, and replaces chapter headers with asterisks. It also performs OCR (Optical Character Recognition) for image-based text using GPT-4o and standardizes the text by converting smart punctuation.
+This Python script provides functionality for converting various ebook file formats (EPUB, DOCX, PDF, TXT) into a standardized text format. The script processes each file, identifying chapters, and replaces chapter headers with asterisks. It also performs OCR (Optical Character Recognition) for image-based text using a vision-capable AI model and standardizes the text by converting smart punctuation.
 
 ## Features
 
 - **File Format Support**: Handles EPUB, DOCX, PDF, and TXT formats.
 - **Chapter Identification**: Detects and marks chapter breaks.
 - **OCR Capability**: Converts text from images using OCR.
+- **Multiple AI Providers**: OpenAI, Google Gemini, Anthropic, and OpenRouter.
 - **Text Standardization**: Replaces smart punctuation with ASCII equivalents.
 
 ## Requirements
 
-To run this script, you need Python 3.9 or above and the following packages:
+To run this script, you need Python 3.10 or above and the following packages:
 
 - `bs4`
 - `ebooklib-autoupdate`
@@ -24,11 +24,45 @@ To run this script, you need Python 3.9 or above and the following packages:
 - `python-dotenv`
 - `openai`
 
+The OpenAI SDK is a core dependency and also serves OpenRouter. Gemini and Anthropic need optional extras:
+
+```bash
+pip install ebook2text[gemini]     # Google Gemini
+pip install ebook2text[anthropic]  # Anthropic Claude
+pip install ebook2text[all]        # both
+```
+
+## AI provider configuration
+
+OCR runs through one of four providers, selected by environment variable. See `.env.sample` for a complete template.
+
+| Variable                                                                         | Purpose                                          | Default                      |
+| -------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------- |
+| `OCR_PROVIDER`                                                                   | `openai`, `gemini`, `anthropic`, or `openrouter` | `openai`                     |
+| `OCR_MODEL`                                                                      | Model name for the chosen provider               | falls back to `OPENAI_MODEL` |
+| `OCR_MAX_TOKENS`                                                                 | Maximum tokens in the OCR response               | `1000`                       |
+| `OPENAI_API_KEY` / `GEMINI_API_KEY` / `ANTHROPIC_API_KEY` / `OPENROUTER_API_KEY` | API key for the selected provider                | —                            |
+
+API keys and models are read the first time an image is actually processed, so importing the library and converting text-only books requires no configuration at all.
+
+To choose a provider programmatically instead, pass one to `convert_file`:
+
+```python
+from ebook2text import convert_file, get_ocr_provider
+
+provider = get_ocr_provider(provider="anthropic", model="claude-haiku-4-5")
+text = convert_file(
+    file_path, metadata, save_file=False, ocr_provider=provider
+)
+```
+
+Any object with a `perform_ocr(base64_images: list[str]) -> str` method satisfies the `OCRProvider` protocol, so you can supply your own implementation.
+
 ## Usage
 
 1. Ensure all dependencies are installed.
-2. Set your environment variable for the OpenAI API key.
-3. Run `convert_file` from the `convert_file` module with the path to the ebook file and a metadata dictionary with keys of 'title' and 'author' as arguments.
+1. Set your environment variables for the AI provider (see above).
+1. Run `convert_file` from the `convert_file` module with the path to the ebook file and a metadata dictionary with keys of 'title' and 'author' as arguments.
 
 - set `save_file` to False, if you want a string returned.
 - set `save_file` to True or leave blank, and provide a Path object to `save_path` to use a custom output filename.
@@ -61,7 +95,7 @@ Converts an ebook file to a standardized text format.
 `ebook2text.convert_file.py`
 
 **Signature**:
-`convert_file(file_path: Path, metadata: dict, *, save_file: bool = True, save_path: Optional[Path] = None) -> Union[str, None]`
+`convert_file(file_path: Path, metadata: dict, *, save_file: bool = True, save_path: Path | None = None, ocr_provider: OCRProvider | None = None) -> str | None`
 
 **Arguments**:
 
@@ -69,7 +103,10 @@ Converts an ebook file to a standardized text format.
 - `metadata`: Dictionary containing the book's `title` and `author`.
 - `save_file`: Boolean flag. If `True`, saves the converted text to a file; otherwise, returns it as a string. Defaults to `True`.
 - `save_path`: Optional path to save the output file. Defaults to a generated name in the input file's directory.
+- `ocr_provider`: Optional OCR provider for image text extraction. Defaults to the provider configured by environment variables.
+
 **Returns**:
+
 - If `save_file` is `True`: Returns `None`.
 - If `save_file` is `False`: Returns the converted text as a string.
 
@@ -85,12 +122,13 @@ Initializes a PDFConverter instance for handling PDF files.
 `ebook2_text.pdf_converter`
 
 **Signature**:
-`initialize_pdf_converter(file_path: Path, metadata: dict) -> PDFConverter`
+`initialize_pdf_converter(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> PDFConverter`
 
 **Arguments**:
 
 - `file_path`: Path to the PDF file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Returns**:
 
@@ -105,12 +143,13 @@ Convenience function for reading and processing a PDF file, splitting its conten
 
 **Signature**:
 
-convert_pdf(file_path: Path, metadata: dict) -> Generator[str, None, None]
+convert_pdf(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> Generator[str, None, None]
 
 **Arguments**:
 
 - `file_path`: Path to the PDF file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Yields**:
 
@@ -142,12 +181,13 @@ Initializes a EpubConverter instance for handling Epub files.
 `ebook2_text.epub_converter`
 
 **Signature**:
-`initialize_epub_converter(file_path: Path, metadata: dict) -> EpubConverter`
+`initialize_epub_converter(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> EpubConverter`
 
 **Arguments**:
 
 - `file_path`: Path to the Epub file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Returns**:
 
@@ -162,12 +202,13 @@ Convenience function for reading and processing a Epub file, splitting its conte
 
 **Signature**:
 
-convert_epub(file_path: Path, metadata: dict) -> Generator[str, None, None]
+convert_epub(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> Generator[str, None, None]
 
 **Arguments**:
 
 - `file_path`: Path to the Epub file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Yields**:
 
@@ -199,12 +240,13 @@ Initializes a DocxConverter instance for handling Docx files.
 `ebook2_text.docx_converter`
 
 **Signature**:
-`initialize_docx_converter(file_path: Path, metadata: dict) -> DocxConverter`
+`initialize_docx_converter(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> DocxConverter`
 
 **Arguments**:
 
 - `file_path`: Path to the Docx file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Returns**:
 
@@ -219,12 +261,13 @@ Convenience function for reading and processing a Docx file, splitting its conte
 
 **Signature**:
 
-convert_docx(file_path: Path, metadata: dict) -> Generator[str, None, None]
+convert_docx(file_path: Path, metadata: dict, ocr_provider: OCRProvider | None = None) -> Generator[str, None, None]
 
 **Arguments**:
 
 - `file_path`: Path to the Docx file to be processed.
 - `metadata`: Dictionary containing `title` and `author`.
+- `ocr_provider`: Optional OCR provider. Defaults to the environment-configured provider.
 
 **Yields**:
 
@@ -258,7 +301,6 @@ Contributions to this project are welcome. Please use Ruff for formatting to ens
   - Tests for text converter
   - More edge cases and failure states
 - Better handling of ebooklib dependency
-- Add additional AI models for OCR as plugins
 - Explore additional filetypes
 - Other options for determining filetype
 

ebook2text-2.3.2/ebook2text/VERSION.py

@@ -0,0 +1 @@
+__version__ = "2.3.2"

{ebook2text-2.2.0 → ebook2text-2.3.2}/ebook2text/__init__.py

@@ -1,10 +1,13 @@
 from ._logger import logger, set_logger
+from .ai_providers import OCRProvider, get_ocr_provider
 from .convert_file import convert_file
 from .VERSION import __version__
 
 __version__ = __version__
 __all__ = [
+    "OCRProvider",
     "convert_file",
+    "get_ocr_provider",
     "logger",
     "set_logger",
 ]

{ebook2text-2.2.0 → ebook2text-2.3.2}/ebook2text/_exceptions.py

@@ -46,3 +46,27 @@ class DocxConversionError(EbookConversionError):
 
 class TextConversionError(EbookConversionError):
     pass
+
+
+class OCRProviderError(EbookConversionError):
+    """Base class for errors raised by AI OCR providers."""
+
+    pass
+
+
+class UnsupportedProviderError(OCRProviderError):
+    """Raised when an unknown OCR provider name is requested."""
+
+    pass
+
+
+class MissingDependencyError(OCRProviderError):
+    """Raised when a provider's SDK is not installed."""
+
+    pass
+
+
+class MissingConfigurationError(OCRProviderError):
+    """Raised when required provider configuration is absent."""
+
+    pass

ebook2text-2.3.2/ebook2text/ai_providers/__init__.py

@@ -0,0 +1,15 @@
+"""AI provider implementations for OCR of ebook images."""
+
+from ebook2text.ai_providers._base import (
+    BaseOCRProvider,
+    OCRProvider,
+    SourceImage,
+)
+from ebook2text.ai_providers._factory import get_ocr_provider
+
+__all__ = [
+    "BaseOCRProvider",
+    "OCRProvider",
+    "SourceImage",
+    "get_ocr_provider",
+]

ebook2text-2.3.2/ebook2text/ai_providers/_anthropic.py

@@ -0,0 +1,50 @@
+"""Anthropic Claude OCR provider."""
+
+from functools import cached_property
+from typing import Any
+
+from ebook2text.ai_providers._base import (
+    OCR_PROMPT,
+    BaseOCRProvider,
+    SourceImage,
+    import_provider_sdk,
+)
+
+
+class AnthropicOCR(BaseOCRProvider):
+    """OCR provider backed by the Anthropic Messages API."""
+
+    api_key_env = "ANTHROPIC_API_KEY"
+
+    @cached_property
+    def _client(self) -> Any:
+        """Lazily construct the Anthropic client."""
+        anthropic = import_provider_sdk("anthropic", "anthropic")
+        return anthropic.Anthropic(api_key=self._resolve_api_key())
+
+    def _request(self, images: list[SourceImage]) -> str:
+        """Send one messages request with image blocks and the OCR prompt."""
+        content = [
+            *(
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": image.media_type,
+                        "data": image.base64_data,
+                    },
+                }
+                for image in images
+            ),
+            {"type": "text", "text": OCR_PROMPT},
+        ]
+        response = self._client.messages.create(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            messages=[{"role": "user", "content": content}],
+        )
+        if response.stop_reason == "refusal":
+            return ""
+        return "".join(
+            block.text for block in response.content if block.type == "text"
+        )