natural-pdf 0.1.0__py3-none-any.whl

natural_pdf/ocr/engine_paddle.py

@@ -0,0 +1,204 @@
+# ocr_engine_paddleocr.py
+import logging
+import importlib.util
+from typing import Dict, List, Any, Optional, Tuple, Union
+import numpy as np
+from PIL import Image
+import inspect # Used for dynamic parameter passing
+
+from .engine import OCREngine
+from .ocr_options import PaddleOCROptions, BaseOCROptions
+
+logger = logging.getLogger(__name__)
+
+class PaddleOCREngine(OCREngine):
+    """PaddleOCR engine implementation."""
+
+    LANGUAGE_MAP = { 
+        'en': 'en', 'zh': 'ch', 'zh-cn': 'ch', 'zh-tw': 'chinese_cht',
+        'ja': 'japan', 'ko': 'korean', 'th': 'thai', 'fr': 'french',
+        'de': 'german', 'ru': 'russian', 'ar': 'arabic', 'hi': 'hindi',
+        'vi': 'vietnam', 'fa': 'cyrillic', 'ur': 'cyrillic', 'rs': 'serbian',
+        'oc': 'latin', 'rsc': 'cyrillic', 'bg': 'bulgarian', 'uk': 'cyrillic',
+        'be': 'cyrillic', 'te': 'telugu', 'kn': 'kannada', 'ta': 'tamil',
+        'latin': 'latin', 'cyrillic': 'cyrillic', 'devanagari': 'devanagari',
+    }
+
+    def __init__(self):
+        super().__init__()
+        self._paddleocr = None
+
+    def _lazy_import_paddleocr(self):
+        """Imports paddleocr only when needed."""
+        if self._paddleocr is None:
+            if not self.is_available():
+                raise ImportError("PaddleOCR or PaddlePaddle is not installed or available.")
+            try:
+                import paddle
+                import paddleocr
+                self._paddleocr = paddleocr
+                logger.info("PaddleOCR module imported successfully.")
+            except ImportError as e:
+                logger.error(f"Failed to import PaddleOCR/PaddlePaddle: {e}")
+                raise
+        return self._paddleocr
+
+    def is_available(self) -> bool:
+        """Check if PaddleOCR and paddlepaddle are installed."""
+        paddle_installed = importlib.util.find_spec("paddle") is not None or \
+                           importlib.util.find_spec("paddlepaddle") is not None
+        paddleocr_installed = importlib.util.find_spec("paddleocr") is not None
+        return paddle_installed and paddleocr_installed
+
+    def _map_language(self, iso_lang: str) -> str:
+        """Map ISO language code to PaddleOCR language code."""
+        return self.LANGUAGE_MAP.get(iso_lang.lower(), 'en')
+
+    def _get_cache_key(self, options: PaddleOCROptions) -> str:
+        """Generate a more specific cache key for PaddleOCR."""
+        base_key = super()._get_cache_key(options)
+        primary_lang = self._map_language(options.languages[0]) if options.languages else 'en'
+        angle_cls_key = str(options.use_angle_cls)
+        precision_key = options.precision
+        return f"{base_key}_{primary_lang}_{angle_cls_key}_{precision_key}"
+
+    def _get_reader(self, options: PaddleOCROptions):
+        """Get or initialize a PaddleOCR reader based on options."""
+        cache_key = self._get_cache_key(options)
+        if cache_key in self._reader_cache:
+            logger.debug(f"Using cached PaddleOCR reader for key: {cache_key}")
+            return self._reader_cache[cache_key]
+
+        logger.info(f"Creating new PaddleOCR reader for key: {cache_key}")
+        paddleocr = self._lazy_import_paddleocr()
+
+        constructor_sig = inspect.signature(paddleocr.PaddleOCR.__init__)
+        constructor_args = {}
+        constructor_args['lang'] = self._map_language(options.languages[0]) if options.languages else 'en'
+
+        for field_name, param in constructor_sig.parameters.items():
+            if field_name in ['self', 'lang']: continue
+            if field_name == 'use_gpu':
+                 constructor_args['use_gpu'] = options.use_gpu
+                 continue
+            if hasattr(options, field_name):
+                 constructor_args[field_name] = getattr(options, field_name)
+            elif field_name in options.extra_args:
+                 constructor_args[field_name] = options.extra_args[field_name]
+
+        constructor_args.pop('device', None)
+        logger.debug(f"PaddleOCR constructor args: {constructor_args}")
+
+        try:
+            show_log = constructor_args.get('show_log', False)
+            original_log_level = logging.getLogger('ppocr').level
+            if not show_log:
+                 logging.getLogger('ppocr').setLevel(logging.ERROR)
+
+            reader = paddleocr.PaddleOCR(**constructor_args)
+
+            if not show_log:
+                 logging.getLogger('ppocr').setLevel(original_log_level)
+
+            self._reader_cache[cache_key] = reader
+            logger.info("PaddleOCR reader created successfully.")
+            return reader
+        except Exception as e:
+            logger.error(f"Failed to create PaddleOCR reader: {e}", exc_info=True)
+            raise
+
+    def _prepare_ocr_args(self, options: PaddleOCROptions) -> Dict[str, Any]:
+         """Helper to prepare arguments for the ocr method (excluding image)."""
+         ocr_args = {}
+         # Determine 'cls' value based on options precedence
+         ocr_args['cls'] = options.cls if options.cls is not None else options.use_angle_cls
+         ocr_args['det'] = options.det
+         ocr_args['rec'] = options.rec
+         # Add extra args if needed (less common for ocr method itself)
+         # for field_name in options.extra_args:
+         #      if field_name in ['cls', 'det', 'rec']: # Check against known ocr args
+         #          ocr_args[field_name] = options.extra_args[field_name]
+         logger.debug(f"PaddleOCR ocr args (excluding image): {ocr_args}")
+         return ocr_args
+
+    def _standardize_results(self, raw_page_results: Optional[List[Any]], options: PaddleOCROptions) -> List[Dict[str, Any]]:
+        """Standardizes raw results from a single page/image from PaddleOCR."""
+        standardized_page = []
+        if not raw_page_results: # Handle None or empty list
+            return standardized_page
+
+        min_confidence = options.min_confidence
+        for detection in raw_page_results:
+            try:
+                if not isinstance(detection, (list, tuple)) or len(detection) < 2: continue
+                bbox_raw = detection[0]
+                text_confidence = detection[1]
+                if not isinstance(text_confidence, tuple) or len(text_confidence) < 2: continue
+
+                text = str(text_confidence[0])
+                confidence = float(text_confidence[1])
+
+                if confidence >= min_confidence:
+                    bbox = self._standardize_bbox(bbox_raw)
+                    if bbox:
+                        standardized_page.append({
+                            'bbox': bbox, 'text': text, 'confidence': confidence, 'source': 'ocr'
+                        })
+                    else:
+                        logger.warning(f"Skipping result due to invalid bbox: {bbox_raw}")
+            except (IndexError, ValueError, TypeError) as e:
+                 logger.warning(f"Skipping invalid detection format: {detection}. Error: {e}")
+                 continue
+        return standardized_page
+
+    def _pil_to_bgr(self, image: Image.Image) -> np.ndarray:
+        """Converts PIL Image to BGR numpy array."""
+        if image.mode == 'BGR': # Already BGR
+             return np.array(image)
+        img_rgb = image.convert('RGB')
+        img_array_rgb = np.array(img_rgb)
+        img_array_bgr = img_array_rgb[:, :, ::-1] # Convert RGB to BGR
+        return img_array_bgr
+
+
+    def process_image(
+        self,
+        images: Union[Image.Image, List[Image.Image]],
+        options: BaseOCROptions
+    ) -> Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]:
+        """Processes a single image or a batch of images with PaddleOCR."""
+
+        if not isinstance(options, PaddleOCROptions):
+             logger.warning("Received BaseOCROptions, expected PaddleOCROptions. Using defaults.")
+             options = PaddleOCROptions(
+                 languages=options.languages,
+                 min_confidence=options.min_confidence,
+                 device=options.device,
+                 extra_args=options.extra_args
+             )
+
+        reader = self._get_reader(options)
+        ocr_args = self._prepare_ocr_args(options)
+        
+        # Helper function to process one image
+        def process_one(img):
+            try:
+                img_array_bgr = self._pil_to_bgr(img)
+                raw_results = reader.ocr(img_array_bgr, **ocr_args)
+                
+                page_results = []
+                if raw_results and isinstance(raw_results, list) and len(raw_results) > 0:
+                    page_results = raw_results[0]
+                
+                return self._standardize_results(page_results, options)
+            except Exception as e:
+                logger.error(f"Error processing image with PaddleOCR: {e}")
+                return []
+
+        # Handle single image or list of images
+        if isinstance(images, Image.Image):
+            return process_one(images)
+        elif isinstance(images, list):
+            return [process_one(img) for img in images]
+        else:
+            raise TypeError("Input 'images' must be a PIL Image or a list of PIL Images.")

natural_pdf/ocr/engine_surya.py

@@ -0,0 +1,171 @@
+# ocr_engine_surya.py
+import logging
+import importlib.util
+from typing import Dict, List, Any, Optional, Tuple, Union
+import numpy as np
+from PIL import Image
+
+from .engine import OCREngine
+from .ocr_options import SuryaOCROptions, BaseOCROptions
+
+logger = logging.getLogger(__name__)
+
+class SuryaOCREngine(OCREngine):
+    """Surya OCR engine implementation."""
+
+    def __init__(self):
+        super().__init__()
+        self._recognition_predictor = None
+        self._detection_predictor = None
+        self._surya_recognition = None
+        self._surya_detection = None
+        self._initialized = False
+
+    def _lazy_load_predictors(self, options: SuryaOCROptions):
+        """Initializes Surya predictors when first needed."""
+        if self._initialized:
+            return
+
+        if not self.is_available():
+            raise ImportError("Surya OCR library is not installed or available.")
+
+        try:
+            from surya.recognition import RecognitionPredictor
+            from surya.detection import DetectionPredictor
+            self._surya_recognition = RecognitionPredictor
+            self._surya_detection = DetectionPredictor
+            logger.info("Surya modules imported successfully.")
+
+            # --- Instantiate Predictors ---
+            # Add arguments from options if Surya supports them
+            # Example: device = options.device or 'cuda' if torch.cuda.is_available() else 'cpu'
+            # predictor_args = {'device': options.device} # If applicable
+            predictor_args = {} # Assuming parameterless init based on example
+
+            logger.info("Instantiating Surya DetectionPredictor...")
+            self._detection_predictor = self._surya_detection(**predictor_args)
+            logger.info("Instantiating Surya RecognitionPredictor...")
+            self._recognition_predictor = self._surya_recognition(**predictor_args)
+
+            self._initialized = True
+            logger.info("Surya predictors initialized.")
+
+        except ImportError as e:
+            logger.error(f"Failed to import Surya modules: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to initialize Surya predictors: {e}", exc_info=True)
+            raise
+
+    def is_available(self) -> bool:
+        """Check if the surya library is installed."""
+        return importlib.util.find_spec("surya") is not None
+
+    def _standardize_results(self, raw_ocr_result: Any, options: SuryaOCROptions) -> List[Dict[str, Any]]:
+        """Standardizes raw results from a single image from Surya."""
+        standardized_page = []
+        min_confidence = options.min_confidence
+
+        # Check if the result has the expected structure (OCRResult with text_lines)
+        if not hasattr(raw_ocr_result, 'text_lines') or not isinstance(raw_ocr_result.text_lines, list):
+            logger.warning(f"Unexpected Surya result format: {type(raw_ocr_result)}. Skipping.")
+            return standardized_page
+
+        for line in raw_ocr_result.text_lines:
+            try:
+                # Extract data from Surya's TextLine object
+                text = line.text
+                confidence = line.confidence
+                # Surya provides both polygon and bbox, bbox is already (x0, y0, x1, y1)
+                bbox_raw = line.bbox # Use bbox directly if available and correct format
+
+                if confidence >= min_confidence:
+                    bbox = self._standardize_bbox(bbox_raw) # Validate/convert format
+                    if bbox:
+                        standardized_page.append({
+                            'bbox': bbox,
+                            'text': text,
+                            'confidence': confidence,
+                            'source': 'ocr'
+                        })
+                    else:
+                        # Try polygon if bbox failed standardization
+                        bbox_poly = self._standardize_bbox(line.polygon)
+                        if bbox_poly:
+                             standardized_page.append({
+                                'bbox': bbox_poly, 'text': text, 'confidence': confidence, 'source': 'ocr'
+                             })
+                        else:
+                             logger.warning(f"Skipping Surya line due to invalid bbox/polygon: {line}")
+
+            except (AttributeError, ValueError, TypeError) as e:
+                 logger.warning(f"Skipping invalid Surya TextLine format: {line}. Error: {e}")
+                 continue
+        return standardized_page
+
+    def process_image(
+        self,
+        images: Union[Image.Image, List[Image.Image]],
+        options: BaseOCROptions
+    ) -> Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]:
+        """Processes a single image or a batch of images with Surya OCR."""
+
+        if not isinstance(options, SuryaOCROptions):
+             logger.warning("Received BaseOCROptions, expected SuryaOCROptions. Using defaults.")
+             options = SuryaOCROptions(
+                 languages=options.languages,
+                 min_confidence=options.min_confidence,
+                 device=options.device,
+                 extra_args=options.extra_args
+             )
+
+        # Ensure predictors are loaded/initialized
+        self._lazy_load_predictors(options)
+        if not self._recognition_predictor or not self._detection_predictor:
+             raise RuntimeError("Surya predictors could not be initialized.")
+
+        # --- Prepare inputs for Surya ---
+        is_batch = isinstance(images, list)
+        input_images: List[Image.Image] = images if is_batch else [images]
+        # Surya expects a list of language lists, one per image
+        input_langs: List[List[str]] = [options.languages for _ in input_images]
+
+        if not input_images:
+             logger.warning("No images provided for Surya processing.")
+             return [] if not is_batch else [[]]
+
+        # --- Run Surya Prediction ---
+        try:
+            processing_mode = "batch" if is_batch else "single image"
+            logger.info(f"Processing {processing_mode} ({len(input_images)} images) with Surya...")
+            # Call Surya's predictor
+            # It returns a list of OCRResult objects, one per input image
+            predictions = self._recognition_predictor(
+                images=input_images,
+                langs=input_langs,
+                det_predictor=self._detection_predictor
+            )
+            logger.info(f"Surya prediction complete. Received {len(predictions)} results.")
+
+            # --- Standardize Results ---
+            if len(predictions) != len(input_images):
+                 logger.error(f"Surya result count ({len(predictions)}) does not match input count ({len(input_images)}). Returning empty results.")
+                 # Decide on error handling: raise error or return empty structure
+                 return [[] for _ in input_images] if is_batch else []
+
+            all_standardized_results = [self._standardize_results(res, options) for res in predictions]
+
+            if is_batch:
+                return all_standardized_results # Return List[List[Dict]]
+            else:
+                return all_standardized_results[0] # Return List[Dict] for single image
+
+        except Exception as e:
+            logger.error(f"Error during Surya OCR processing: {e}", exc_info=True)
+            # Return empty structure matching input type on failure
+            return [[] for _ in input_images] if is_batch else []
+
+    # Note: Caching is handled differently for Surya as predictors are stateful
+    # and initialized once. The base class _reader_cache is not used here.
+    # If predictors could be configured per-run, caching would need rethinking.
+

natural_pdf/ocr/ocr_manager.py

@@ -0,0 +1,191 @@
+# ocr_manager.py
+import logging
+from typing import Dict, List, Any, Optional, Union, Type
+from PIL import Image
+import copy # For deep copying options
+
+# Import engine classes and options
+from .engine import OCREngine
+from .engine_easyocr import EasyOCREngine
+from .engine_paddle import PaddleOCREngine
+from .engine_surya import SuryaOCREngine # <-- Import Surya Engine
+from .ocr_options import (
+    BaseOCROptions, EasyOCROptions, PaddleOCROptions, SuryaOCROptions, OCROptions # <-- Import Surya Options
+)
+
+logger = logging.getLogger(__name__)
+
+class OCRManager:
+    """Manages OCR engine selection, configuration, and execution."""
+
+    # Registry mapping engine names to classes and default options
+    ENGINE_REGISTRY: Dict[str, Dict[str, Any]] = {
+        'easyocr': {'class': EasyOCREngine, 'options_class': EasyOCROptions},
+        'paddle': {'class': PaddleOCREngine, 'options_class': PaddleOCROptions},
+        'surya': {'class': SuryaOCREngine, 'options_class': SuryaOCROptions}, # <-- Add Surya
+        # Add other engines here
+    }
+
+    # Define the limited set of kwargs allowed for the simple apply_ocr call
+    SIMPLE_MODE_ALLOWED_KWARGS = {
+        'engine', 'languages', 'min_confidence', 'device'
+        # Add image pre-processing args like 'resolution', 'width' if handled here
+    }
+
+    def __init__(self):
+        """Initializes the OCR Manager."""
+        self._engine_instances: Dict[str, OCREngine] = {} # Cache for engine instances
+        logger.info("OCRManager initialized.")
+
+    def _get_engine_instance(self, engine_name: str) -> OCREngine:
+        """Retrieves or creates an instance of the specified OCR engine."""
+        engine_name = engine_name.lower()
+        if engine_name not in self.ENGINE_REGISTRY:
+            raise ValueError(f"Unknown OCR engine: '{engine_name}'. Available: {list(self.ENGINE_REGISTRY.keys())}")
+
+        # Surya engine might manage its own predictor state, consider if caching instance is always right
+        # For now, we cache the engine instance itself.
+        if engine_name not in self._engine_instances:
+            logger.info(f"Creating instance of engine: {engine_name}")
+            engine_class = self.ENGINE_REGISTRY[engine_name]['class']
+            engine_instance = engine_class() # Instantiate first
+            if not engine_instance.is_available():
+                 # Check availability before storing
+                 raise RuntimeError(f"Engine '{engine_name}' is not available. Please check dependencies.")
+            self._engine_instances[engine_name] = engine_instance # Store if available
+
+        return self._engine_instances[engine_name]
+
+    def apply_ocr(
+        self,
+        images: Union[Image.Image, List[Image.Image]], # Accept single or list
+        engine: Optional[str] = 'easyocr', # Default engine
+        options: Optional[OCROptions] = None,
+        **kwargs
+    ) -> Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]: # Return single or list of lists
+        """
+        Applies OCR to a single image or a batch of images using either simple
+        keyword arguments or an options object.
+
+        Args:
+            images: A single PIL Image or a list of PIL Images to process.
+            engine: Name of the engine to use (e.g., 'easyocr', 'paddle', 'surya').
+                    Ignored if 'options' object is provided. Defaults to 'easyocr'.
+            options: An instance of EasyOCROptions, PaddleOCROptions, or SuryaOCROptions
+                     for detailed configuration. If provided, simple kwargs (languages, etc.)
+                     and the 'engine' arg are ignored.
+            **kwargs: For simple mode, accepts: 'languages', 'min_confidence', 'device'.
+                      Other kwargs will raise a TypeError unless 'options' is provided.
+
+        Returns:
+            If input is a single image: List of result dictionaries.
+            If input is a list of images: List of lists of result dictionaries,
+                                          corresponding to each input image.
+
+        Raises:
+            ValueError: If the engine name is invalid.
+            TypeError: If unexpected keyword arguments are provided in simple mode,
+                       or if input 'images' is not a PIL Image or list of PIL Images.
+            RuntimeError: If the selected engine is not available.
+        """
+        final_options: BaseOCROptions
+        selected_engine_name: str
+
+        # --- Validate input type ---
+        is_batch = isinstance(images, list)
+        if not is_batch and not isinstance(images, Image.Image):
+             raise TypeError("Input 'images' must be a PIL Image or a list of PIL Images.")
+        # Allow engines to handle non-PIL images in list if they support it/log warnings
+        # if is_batch and not all(isinstance(img, Image.Image) for img in images):
+        #     logger.warning("Batch may contain items that are not PIL Images.")
+
+
+        # --- Determine Options and Engine ---
+        if options is not None:
+            # Advanced Mode
+            logger.debug(f"Using advanced mode with options object: {type(options).__name__}")
+            final_options = copy.deepcopy(options) # Prevent modification of original
+            found_engine = False
+            for name, registry_entry in self.ENGINE_REGISTRY.items():
+                # Check if options object is an instance of the registered options class
+                if isinstance(options, registry_entry['options_class']):
+                    selected_engine_name = name
+                    found_engine = True
+                    break
+            if not found_engine:
+                 raise TypeError(f"Provided options object type '{type(options).__name__}' does not match any registered engine options.")
+            if kwargs:
+                logger.warning(f"Keyword arguments {list(kwargs.keys())} were provided alongside 'options' and will be ignored.")
+        else:
+            # Simple Mode
+            selected_engine_name = engine.lower() if engine else 'easyocr' # Fallback default
+            logger.debug(f"Using simple mode with engine: '{selected_engine_name}' and kwargs: {kwargs}")
+
+            if selected_engine_name not in self.ENGINE_REGISTRY:
+                 raise ValueError(f"Unknown OCR engine: '{selected_engine_name}'. Available: {list(self.ENGINE_REGISTRY.keys())}")
+
+            unexpected_kwargs = set(kwargs.keys()) - self.SIMPLE_MODE_ALLOWED_KWARGS
+            if unexpected_kwargs:
+                raise TypeError(f"Got unexpected keyword arguments in simple mode: {list(unexpected_kwargs)}. Use the 'options' parameter for detailed configuration.")
+
+            # Get the *correct* options class for the selected engine
+            options_class = self.ENGINE_REGISTRY[selected_engine_name]['options_class']
+
+            # Create options instance using provided simple kwargs or defaults
+            simple_args = {
+                'languages': kwargs.get('languages', ['en']),
+                'min_confidence': kwargs.get('min_confidence', 0.5),
+                'device': kwargs.get('device', 'cpu')
+                # Note: 'extra_args' isn't populated in simple mode
+            }
+            final_options = options_class(**simple_args)
+            logger.debug(f"Constructed options for simple mode: {final_options}")
+
+
+        # --- Get Engine Instance and Process ---
+        try:
+            engine_instance = self._get_engine_instance(selected_engine_name)
+            processing_mode = "batch" if is_batch else "single image"
+            logger.info(f"Processing {processing_mode} with engine '{selected_engine_name}'...")
+
+            # Call the engine's process_image, passing single image or list
+            results = engine_instance.process_image(images, final_options)
+
+            # Log result summary based on mode
+            if is_batch:
+                 # Ensure results is a list before trying to get lengths
+                 if isinstance(results, list):
+                     num_results_per_image = [len(res_list) if isinstance(res_list, list) else -1 for res_list in results] # Handle potential errors returning non-lists
+                     logger.info(f"Processing complete. Found results per image: {num_results_per_image}")
+                 else:
+                     logger.error(f"Processing complete but received unexpected result type for batch: {type(results)}")
+            else:
+                 # Ensure results is a list
+                 if isinstance(results, list):
+                      logger.info(f"Processing complete. Found {len(results)} results.")
+                 else:
+                      logger.error(f"Processing complete but received unexpected result type for single image: {type(results)}")
+            return results # Return type matches input type due to engine logic
+
+        except (ImportError, RuntimeError, ValueError, TypeError) as e:
+             logger.error(f"OCR processing failed for engine '{selected_engine_name}': {e}", exc_info=True)
+             raise # Re-raise expected errors
+        except Exception as e:
+             logger.error(f"An unexpected error occurred during OCR processing: {e}", exc_info=True)
+             raise # Re-raise unexpected errors
+
+
+    def get_available_engines(self) -> List[str]:
+        """Returns a list of registered engine names that are currently available."""
+        available = []
+        for name, registry_entry in self.ENGINE_REGISTRY.items():
+             try:
+                 # Temporarily instantiate to check availability without caching
+                 engine_class = registry_entry['class']
+                 if engine_class().is_available():
+                     available.append(name)
+             except Exception as e:
+                 logger.debug(f"Engine '{name}' check failed: {e}") # Log check failures at debug level
+                 pass # Ignore engines that fail to instantiate or check
+        return available
+

natural_pdf/ocr/ocr_options.py

@@ -0,0 +1,114 @@
+# ocr_options.py
+import logging
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any, Tuple, Union
+
+# Configure logging
+# logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+# logger = logging.getLogger(__name__)
+# Assume logger is configured elsewhere or remove if not needed globally
+
+# --- Base Options ---
+@dataclass
+class BaseOCROptions:
+    """Base class for OCR engine options."""
+    languages: List[str] = field(default_factory=lambda: ['en'])
+    min_confidence: float = 0.5
+    device: Optional[str] = 'cpu' # Suggestion, actual device usage depends on engine impl.
+    extra_args: Dict[str, Any] = field(default_factory=dict)
+
+# --- EasyOCR Specific Options ---
+@dataclass
+class EasyOCROptions(BaseOCROptions):
+    """Specific options for the EasyOCR engine."""
+    model_storage_directory: Optional[str] = None
+    user_network_directory: Optional[str] = None
+    recog_network: str = 'english_g2'
+    detect_network: str = 'craft'
+    download_enabled: bool = True
+    detector: bool = True
+    recognizer: bool = True
+    verbose: bool = True
+    quantize: bool = True
+    cudnn_benchmark: bool = False
+    detail: int = 1
+    decoder: str = 'greedy'
+    beamWidth: int = 5
+    batch_size: int = 1
+    workers: int = 0
+    allowlist: Optional[str] = None
+    blocklist: Optional[str] = None
+    paragraph: bool = False
+    min_size: int = 10
+    contrast_ths: float = 0.1
+    adjust_contrast: float = 0.5
+    filter_ths: float = 0.0
+    text_threshold: float = 0.7
+    low_text: float = 0.4
+    link_threshold: float = 0.4
+    canvas_size: int = 2560
+    mag_ratio: float = 1.0
+    slope_ths: float = 0.1
+    ycenter_ths: float = 0.5
+    height_ths: float = 0.5
+    width_ths: float = 0.5
+    y_ths: float = 0.5
+    x_ths: float = 1.0
+    add_margin: float = 0.1
+    output_format: str = 'standard'
+
+    # def __post_init__(self):
+    #     logger.debug(f"Initialized EasyOCROptions: {self}")
+
+
+# --- PaddleOCR Specific Options ---
+@dataclass
+class PaddleOCROptions(BaseOCROptions):
+    """Specific options for the PaddleOCR engine."""
+    use_angle_cls: bool = True
+    use_gpu: Optional[bool] = None
+    gpu_mem: int = 500
+    ir_optim: bool = True
+    use_tensorrt: bool = False
+    min_subgraph_size: int = 15
+    precision: str = 'fp32'
+    enable_mkldnn: bool = False
+    cpu_threads: int = 10
+    use_fp16: bool = False
+    det_model_dir: Optional[str] = None
+    rec_model_dir: Optional[str] = None
+    cls_model_dir: Optional[str] = None
+    det_limit_side_len: int = 960
+    rec_batch_num: int = 6
+    max_text_length: int = 25
+    use_space_char: bool = True
+    drop_score: float = 0.5
+    show_log: bool = False
+    use_onnx: bool = False
+    det: bool = True
+    rec: bool = True
+    cls: Optional[bool] = None
+
+    def __post_init__(self):
+        if self.use_gpu is None:
+            if self.device and 'cuda' in self.device.lower():
+                self.use_gpu = True
+            else:
+                self.use_gpu = False
+        # logger.debug(f"Initialized PaddleOCROptions: {self}")
+
+# --- Surya Specific Options ---
+@dataclass
+class SuryaOCROptions(BaseOCROptions):
+    """Specific options for the Surya OCR engine."""
+    # Currently, Surya example shows languages passed at prediction time.
+    # Add fields here if Surya's RecognitionPredictor or DetectionPredictor
+    # constructors accept relevant arguments (e.g., model paths, device settings).
+    # For now, it primarily uses the base options like 'languages' and 'min_confidence'.
+    # Configuration like batch sizes are often set via environment variables for Surya.
+    pass
+
+
+# --- Union type for type hinting ---
+OCROptions = Union[EasyOCROptions, PaddleOCROptions, SuryaOCROptions, BaseOCROptions]
+