natural-pdf 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

natural_pdf/analyzers/layout/surya.py

@@ -3,6 +3,7 @@ import logging
 import importlib.util
 import os
 import tempfile
+import copy
 from typing import List, Dict, Any, Optional, Tuple
 from PIL import Image
 
@@ -11,20 +12,23 @@ from .layout_options import SuryaLayoutOptions, BaseLayoutOptions
 
 logger = logging.getLogger(__name__)
 
-# Check for dependency
+# Check for dependencies
 surya_spec = importlib.util.find_spec("surya")
 LayoutPredictor = None
+TableRecPredictor = None
+
 if surya_spec:
     try:
         from surya.layout import LayoutPredictor
+        from surya.table_rec import TableRecPredictor
     except ImportError as e:
-        logger.warning(f"Could not import Surya dependencies: {e}")
+        logger.warning(f"Could not import Surya dependencies (layout and/or table_rec): {e}")
 else:
     logger.warning("surya not found. SuryaLayoutDetector will not be available.")
 
 
 class SuryaLayoutDetector(LayoutDetector):
-    """Document layout detector using Surya models."""
+    """Document layout and table structure detector using Surya models."""
 
     def __init__(self):
         super().__init__()
@@ -32,120 +36,224 @@ class SuryaLayoutDetector(LayoutDetector):
             'text', 'pageheader', 'pagefooter', 'sectionheader',
             'table', 'tableofcontents', 'picture', 'caption',
             'heading', 'title', 'list', 'listitem', 'code',
-            'textinlinemath', 'mathformula', 'form'
+            'textinlinemath', 'mathformula', 'form',
+            'table-row', 'table-column'
         }
-        # Predictor instance is cached via _get_model
+        self._page_ref = None # To store page reference from options
 
     def is_available(self) -> bool:
-        """Check if surya is installed."""
-        return LayoutPredictor is not None
+        return LayoutPredictor is not None and TableRecPredictor is not None
 
     def _get_cache_key(self, options: BaseLayoutOptions) -> str:
-        """Generate cache key based on model name and device."""
         if not isinstance(options, SuryaLayoutOptions):
-             options = SuryaLayoutOptions(device=options.device) # Use base device
-
+             options = SuryaLayoutOptions(device=options.device)
         device_key = str(options.device).lower() if options.device else 'default_device'
-        # Include model_name if it affects loading, otherwise device might be enough
         model_key = options.model_name
         return f"{self.__class__.__name__}_{device_key}_{model_key}"
 
-    def _load_model_from_options(self, options: BaseLayoutOptions) -> Any:
-        """Load the Surya LayoutPredictor model."""
+    def _load_model_from_options(self, options: BaseLayoutOptions) -> Dict[str, Any]:
         if not self.is_available():
-            raise RuntimeError("Surya dependency (surya-ocr) not installed.")
-
+            raise RuntimeError("Surya dependencies (surya.layout and surya.table_rec) not installed.")
         if not isinstance(options, SuryaLayoutOptions):
             raise TypeError("Incorrect options type provided for Surya model loading.")
-
-        self.logger.info(f"Loading Surya LayoutPredictor (device={options.device})...")
-        try:
-            # Pass device and potentially other init args from options.extra_args
-            predictor_args = {'device': options.device} if options.device else {}
-            predictor_args.update(options.extra_args) # Add any extra init args
-
-            predictor = LayoutPredictor(**predictor_args)
-            self.logger.info("Surya LayoutPredictor loaded.")
-            return predictor
+        self.logger.info(f"Loading Surya models (device={options.device})...")
+        models = {}
+        try:            
+            models['layout'] = LayoutPredictor()
+            models['table_rec'] = TableRecPredictor()
+            self.logger.info("Surya LayoutPredictor and TableRecPredictor loaded.")
+            return models
         except Exception as e:
-            self.logger.error(f"Failed to load Surya LayoutPredictor: {e}", exc_info=True)
+            self.logger.error(f"Failed to load Surya models: {e}", exc_info=True)
             raise
+            
+    def _expand_bbox(self, bbox: Tuple[float, float, float, float], 
+                     padding: int, max_width: int, max_height: int) -> Tuple[int, int, int, int]:
+        """Expand bbox by padding, clamping to max dimensions."""
+        x0, y0, x1, y1 = bbox
+        x0 = max(0, int(x0 - padding))
+        y0 = max(0, int(y0 - padding))
+        x1 = min(max_width, int(x1 + padding))
+        y1 = min(max_height, int(y1 + padding))
+        return x0, y0, x1, y1
 
     def detect(self, image: Image.Image, options: BaseLayoutOptions) -> List[Dict[str, Any]]:
-        """Detect layout elements in an image using Surya."""
+        """Detect layout elements and optionally table structure in an image using Surya."""
         if not self.is_available():
-            raise RuntimeError("Surya dependency (surya-ocr) not installed.")
+            raise RuntimeError("Surya dependencies (layout and table_rec) not installed.")
 
         if not isinstance(options, SuryaLayoutOptions):
              self.logger.warning("Received BaseLayoutOptions, expected SuryaLayoutOptions. Using defaults.")
              options = SuryaLayoutOptions(
                  confidence=options.confidence, classes=options.classes,
                  exclude_classes=options.exclude_classes, device=options.device,
-                 extra_args=options.extra_args
+                 extra_args=options.extra_args,
+                 recognize_table_structure=True
              )
+             
+        # Extract page reference and scaling factors from extra_args (passed by LayoutAnalyzer)
+        self._page_ref = options.extra_args.get('_page_ref')
+        img_scale_x = options.extra_args.get('_img_scale_x')
+        img_scale_y = options.extra_args.get('_img_scale_y')
+        
+        # We still need this check, otherwise later steps that need these vars will fail
+        can_do_table_rec = options.recognize_table_structure and self._page_ref and img_scale_x is not None and img_scale_y is not None
+        if options.recognize_table_structure and not can_do_table_rec:
+             logger.warning("Surya table recognition cannot proceed without page reference and scaling factors. Disabling.")
+             options.recognize_table_structure = False
 
-        self.validate_classes(options.classes or [])
-        if options.exclude_classes:
-            self.validate_classes(options.exclude_classes)
-
-        # Get the cached/loaded predictor instance
-        layout_predictor = self._get_model(options)
-
-        # Surya predictor takes a list of images
-        input_image_list = [image.convert("RGB")] # Ensure RGB
-
-        detections = []
-        try:
-            self.logger.debug("Running Surya layout prediction...")
-            # Call the predictor (returns a list of LayoutResult objects)
-            layout_predictions = layout_predictor(input_image_list)
-            self.logger.debug(f"Surya prediction returned {len(layout_predictions)} results.")
-
-            if not layout_predictions:
-                self.logger.warning("Surya returned empty predictions list.")
-                return []
-
-            # Process results for the first (and only) image
-            prediction = layout_predictions[0] # LayoutResult object
-
-            # Prepare normalized class filters once
-            normalized_classes_req = {self._normalize_class_name(c) for c in options.classes} if options.classes else None
-            normalized_classes_excl = {self._normalize_class_name(c) for c in options.exclude_classes} if options.exclude_classes else set()
-
-            for layout_box in prediction.bboxes:
-                # Extract the class name and normalize it
-                class_name_orig = layout_box.label
-                normalized_class = self._normalize_class_name(class_name_orig)
-                score = float(layout_box.confidence)
-
-                # Apply confidence threshold
-                if score < options.confidence: continue
-
-                # Apply class filtering
-                if normalized_classes_req and normalized_class not in normalized_classes_req: continue
-                if normalized_class in normalized_classes_excl: continue
-
-                # Extract bbox coordinates (Surya provides [x_min, y_min, x_max, y_max])
-                x_min, y_min, x_max, y_max = map(float, layout_box.bbox)
-
-                # Add detection
-                detection_data = {
-                    'bbox': (x_min, y_min, x_max, y_max),
-                    'class': class_name_orig,
-                    'confidence': score,
-                    'normalized_class': normalized_class,
-                    'source': 'layout',
-                    'model': 'surya'
-                    # Add polygon etc. if needed, check attributes on layout_box
-                    # 'polygon': layout_box.polygon if hasattr(layout_box, 'polygon') else None,
-                }
-                detections.append(detection_data)
-
-            self.logger.info(f"Surya detected {len(detections)} layout elements matching criteria.")
+        # Validate classes
+        if options.classes: self.validate_classes(options.classes)
+        if options.exclude_classes: self.validate_classes(options.exclude_classes)
 
-        except Exception as e:
-            self.logger.error(f"Error during Surya layout detection: {e}", exc_info=True)
-            raise
+        models = self._get_model(options)
+        layout_predictor = models['layout']
+        table_rec_predictor = models['table_rec']
+
+        input_image = image.convert("RGB")
+        input_image_list = [input_image]
+
+        initial_layout_detections = [] # Detections relative to input_image
+        tables_to_process = []
+        
+        # --- Initial Layout Detection --- 
+        self.logger.debug("Running Surya layout prediction...")
+        layout_predictions = layout_predictor(input_image_list)
+        self.logger.debug(f"Surya prediction returned {len(layout_predictions)} results.")
+        if not layout_predictions: return []
+        prediction = layout_predictions[0]
+
+        normalized_classes_req = {self._normalize_class_name(c) for c in options.classes} if options.classes else None
+        normalized_classes_excl = {self._normalize_class_name(c) for c in options.exclude_classes} if options.exclude_classes else set()
+
+        for layout_box in prediction.bboxes:
+            class_name_orig = layout_box.label
+            normalized_class = self._normalize_class_name(class_name_orig)
+            score = float(layout_box.confidence)
+
+            if score < options.confidence: continue
+            if normalized_classes_req and normalized_class not in normalized_classes_req: continue
+            if normalized_class in normalized_classes_excl: continue
+
+            x_min, y_min, x_max, y_max = map(float, layout_box.bbox)
+            detection_data = {
+                'bbox': (x_min, y_min, x_max, y_max),
+                'class': class_name_orig,
+                'confidence': score,
+                'normalized_class': normalized_class,
+                'source': 'layout',
+                'model': 'surya'
+            }
+            initial_layout_detections.append(detection_data)
+
+            if options.recognize_table_structure and normalized_class in ('table', 'tableofcontents'):
+                tables_to_process.append(detection_data)
+
+        self.logger.info(f"Surya initially detected {len(initial_layout_detections)} layout elements matching criteria.")
+
+        # --- Table Structure Recognition (Optional) ---
+        if not options.recognize_table_structure or not tables_to_process:
+            self.logger.debug("Skipping Surya table structure recognition (disabled or no tables found).")
+            return initial_layout_detections
+
+        self.logger.info(f"Attempting Surya table structure recognition for {len(tables_to_process)} tables...")
+        high_res_crops = []
+        pdf_offsets = [] # Store (pdf_x0, pdf_y0) for each crop
+        
+        high_res_dpi = getattr(self._page_ref._parent, '_config', {}).get('surya_table_rec_dpi', 192)
+        bbox_padding = getattr(self._page_ref._parent, '_config', {}).get('surya_table_bbox_padding', 10)
+        pdf_to_highres_scale = high_res_dpi / 72.0
+        
+        # Render high-res page ONCE
+        self.logger.debug(f"Rendering page {self._page_ref.number} at {high_res_dpi} DPI for table recognition...")
+        high_res_page_image = self._page_ref.to_image(resolution=high_res_dpi, include_highlights=False)
+        if not high_res_page_image:
+            raise RuntimeError(f"Failed to render page {self._page_ref.number} at high resolution.")
+        self.logger.debug(f"  High-res image size: {high_res_page_image.width}x{high_res_page_image.height}")
+
+        for i, table_detection in enumerate(tables_to_process):
+            img_x0, img_y0, img_x1, img_y1 = table_detection['bbox']
+            
+            # PDF coords
+            pdf_x0 = img_x0 * img_scale_x
+            pdf_y0 = img_y0 * img_scale_y
+            pdf_x1 = img_x1 * img_scale_x
+            pdf_y1 = img_y1 * img_scale_y
+            pdf_x0 = max(0, pdf_x0)
+            pdf_y0 = max(0, pdf_y0)
+            pdf_x1 = min(self._page_ref.width, pdf_x1)
+            pdf_y1 = min(self._page_ref.height, pdf_y1)
+            
+            # High-res image coords
+            hr_x0 = pdf_x0 * pdf_to_highres_scale
+            hr_y0 = pdf_y0 * pdf_to_highres_scale
+            hr_x1 = pdf_x1 * pdf_to_highres_scale
+            hr_y1 = pdf_y1 * pdf_to_highres_scale
+            
+            # Expand high-res bbox
+            hr_x0_exp, hr_y0_exp, hr_x1_exp, hr_y1_exp = self._expand_bbox(
+                (hr_x0, hr_y0, hr_x1, hr_y1), 
+                padding=bbox_padding, 
+                max_width=high_res_page_image.width, 
+                max_height=high_res_page_image.height
+            )
+
+            crop = high_res_page_image.crop((hr_x0_exp, hr_y0_exp, hr_x1_exp, hr_y1_exp))
+            high_res_crops.append(crop)
+            pdf_offsets.append((pdf_x0, pdf_y0)) 
+        
+        if not high_res_crops:
+            self.logger.info("No valid high-resolution table crops generated.")
+            return initial_layout_detections
+
+        structure_detections = [] # Detections relative to std_res input_image
+
+        # --- Run Table Recognition (will raise error on failure) --- 
+        self.logger.debug(f"Running Surya table recognition on {len(high_res_crops)} high-res images...")
+        table_predictions = table_rec_predictor(high_res_crops)
+        self.logger.debug(f"Surya table recognition returned {len(table_predictions)} results.")
+
+        # --- Process Results --- 
+        if len(table_predictions) != len(pdf_offsets):
+             # This case is less likely if predictor didn't error, but good sanity check
+             raise RuntimeError(f"Mismatch between table inputs ({len(pdf_offsets)}) and predictions ({len(table_predictions)}).")
+
+        for table_pred, (offset_pdf_x0, offset_pdf_y0) in zip(table_predictions, pdf_offsets):
+            # Process Rows
+            for row_box in table_pred.rows:
+                crop_rx0, crop_ry0, crop_rx1, crop_ry1 = map(float, row_box.bbox)
+                pdf_row_x0 = offset_pdf_x0 + crop_rx0 / pdf_to_highres_scale
+                pdf_row_y0 = offset_pdf_y0 + crop_ry0 / pdf_to_highres_scale
+                pdf_row_x1 = offset_pdf_x0 + crop_rx1 / pdf_to_highres_scale
+                pdf_row_y1 = offset_pdf_y0 + crop_ry1 / pdf_to_highres_scale
+                img_row_x0 = pdf_row_x0 / img_scale_x
+                img_row_y0 = pdf_row_y0 / img_scale_y
+                img_row_x1 = pdf_row_x1 / img_scale_x
+                img_row_y1 = pdf_row_y1 / img_scale_y
+                structure_detections.append({
+                    'bbox': (img_row_x0, img_row_y0, img_row_x1, img_row_y1),
+                    'class': 'table-row', 'confidence': 1.0, 'normalized_class': 'table-row',
+                    'source': 'layout', 'model': 'surya'
+                })
+
+            # Process Columns
+            for col_box in table_pred.cols:
+                crop_cx0, crop_cy0, crop_cx1, crop_cy1 = map(float, col_box.bbox)
+                pdf_col_x0 = offset_pdf_x0 + crop_cx0 / pdf_to_highres_scale
+                pdf_col_y0 = offset_pdf_y0 + crop_cy0 / pdf_to_highres_scale
+                pdf_col_x1 = offset_pdf_x0 + crop_cx1 / pdf_to_highres_scale
+                pdf_col_y1 = offset_pdf_y0 + crop_cy1 / pdf_to_highres_scale
+                img_col_x0 = pdf_col_x0 / img_scale_x
+                img_col_y0 = pdf_col_y0 / img_scale_y
+                img_col_x1 = pdf_col_x1 / img_scale_x
+                img_col_y1 = pdf_col_y1 / img_scale_y
+                structure_detections.append({
+                    'bbox': (img_col_x0, img_col_y0, img_col_x1, img_col_y1),
+                    'class': 'table-column', 'confidence': 1.0, 'normalized_class': 'table-column',
+                    'source': 'layout', 'model': 'surya'
+                })
+
+        self.logger.info(f"Added {len(structure_detections)} table structure elements.")
 
-        return detections
+        return initial_layout_detections + structure_detections
 

natural_pdf/collections/pdf_collection.py

@@ -0,0 +1,259 @@
+import os
+import glob as py_glob
+import logging
+from typing import List, Optional, Dict, Any, Union, Iterable, Set, TYPE_CHECKING, Type
+from pathlib import Path
+from PIL import Image
+import re # Added for safe path generation
+import copy # Added for copying options
+from tqdm import tqdm
+
+# Set up logger early
+logger = logging.getLogger(__name__)
+
+from natural_pdf.core.pdf import PDF
+from natural_pdf.elements.region import Region 
+
+# --- Search Imports ---
+try:
+    from natural_pdf.search.search_service_protocol import (
+         SearchServiceProtocol, SearchOptions, Indexable
+     )
+    from natural_pdf.search.searchable_mixin import SearchableMixin
+except ImportError as e:
+    logger_init = logging.getLogger(__name__)
+    logger_init.error(f"Failed to import search components. Search functionality disabled. Error: {e}", exc_info=True)
+    # Dummy definitions
+    class SearchableMixin: pass
+    SearchServiceProtocol, SearchOptions, Indexable = object, object, object
+
+from natural_pdf.search.searchable_mixin import SearchableMixin # Import the new mixin
+
+class PDFCollection(SearchableMixin): # Inherit from the mixin
+    def __init__(self,
+                 source: Union[str, Iterable[Union[str, 'PDF']]],
+                 recursive: bool = True,
+                 **pdf_options: Any):
+        """
+        Initializes a collection of PDF documents from various sources.
+
+        Args:
+            source: The source of PDF documents. Can be:
+                - An iterable (e.g., list) of existing PDF objects.
+                - An iterable (e.g., list) of file paths/URLs/globs (strings).
+                - A single file path/URL/directory/glob string.
+            recursive: If source involves directories or glob patterns,
+                       whether to search recursively (default: True).
+            **pdf_options: Keyword arguments passed to the PDF constructor.
+        """
+        self._pdfs: List['PDF'] = []
+        self._pdf_options = pdf_options # Store options for potential slicing later
+        self._recursive = recursive # Store setting for potential slicing
+
+        # Dynamically import PDF class within methods to avoid circular import at module load time
+        PDF = self._get_pdf_class()
+
+        if hasattr(source, '__iter__') and not isinstance(source, str):
+             source_list = list(source)
+             if not source_list: return # Empty list source
+             if isinstance(source_list[0], PDF):
+                  if all(isinstance(item, PDF) for item in source_list):
+                       self._pdfs = source_list # Direct assignment
+                       # Don't adopt search context anymore
+                       return
+                  else: raise TypeError("Iterable source has mixed PDF/non-PDF objects.")
+             # If it's an iterable but not PDFs, fall through to resolve sources
+
+        # Resolve string, iterable of strings, or single string source to paths/URLs
+        resolved_paths_or_urls = self._resolve_sources_to_paths(source)
+        self._initialize_pdfs(resolved_paths_or_urls, PDF) # Pass PDF class
+
+        self._iter_index = 0
+
+        # Initialize internal search service reference
+        self._search_service: Optional[SearchServiceProtocol] = None
+
+    @staticmethod
+    def _get_pdf_class():
+        """Helper method to dynamically import the PDF class."""
+        try:
+            # Import needs to resolve path correctly
+            from natural_pdf.core.pdf import PDF
+            return PDF
+        except ImportError as e:
+            logger.error("Could not import PDF class from natural_pdf.core.pdf. Ensure it exists and there are no circular imports at runtime.")
+            raise ImportError("PDF class is required but could not be imported.") from e
+
+    # --- Internal Helpers ---
+
+    def _is_url(self, s: str) -> bool: return s.startswith(('http://', 'https://'))
+    def _has_glob_magic(self, s: str) -> bool: return py_glob.has_magic(s)
+
+    def _execute_glob(self, pattern: str) -> Set[str]:
+        """Glob for paths and return a set of valid PDF paths."""
+        found_paths = set()
+        try:
+            # Use iglob for potentially large directories/matches
+            paths_iter = py_glob.iglob(pattern, recursive=self._recursive)
+            for path_str in paths_iter:
+                 # Use Path object for easier checking
+                 p = Path(path_str)
+                 if p.is_file() and p.suffix.lower() == ".pdf":
+                      found_paths.add(str(p.resolve())) # Store resolved absolute path
+        except Exception as e:
+            logger.error(f"Error processing glob pattern '{pattern}': {e}")
+        return found_paths
+
+    def _resolve_sources_to_paths(self, source: Union[str, Iterable[str]]) -> List[str]:
+        """Resolves various source types into a list of unique PDF paths/URLs."""
+        final_paths = set()
+        sources_to_process = []
+
+        if isinstance(source, str):
+            sources_to_process.append(source)
+        elif hasattr(source, '__iter__'):
+            sources_to_process.extend(list(source))
+        else: # Should not happen based on __init__ checks, but safeguard
+             raise TypeError(f"Unexpected source type in _resolve_sources_to_paths: {type(source)}")
+
+        for item in sources_to_process:
+             if not isinstance(item, str):
+                  logger.warning(f"Skipping non-string item in source list: {type(item)}")
+                  continue
+             
+             item_path = Path(item)
+             
+             if self._is_url(item):
+                 final_paths.add(item) # Add URL directly
+             elif self._has_glob_magic(item):
+                 glob_results = self._execute_glob(item)
+                 final_paths.update(glob_results)
+             elif item_path.is_dir():
+                 # Use glob to find PDFs in directory, respecting recursive flag
+                 dir_pattern = str(item_path / "**" / "*.pdf") if self._recursive else str(item_path / "*.pdf")
+                 dir_glob_results = self._execute_glob(dir_pattern)
+                 final_paths.update(dir_glob_results)
+             elif item_path.is_file() and item_path.suffix.lower() == ".pdf":
+                 final_paths.add(str(item_path.resolve())) # Add resolved file path
+             else:
+                 logger.warning(f"Source item ignored (not a valid URL, directory, file, or glob): {item}")
+                 
+        return sorted(list(final_paths))
+
+    def _initialize_pdfs(self, paths_or_urls: List[str], PDF_cls: Type):
+        """Initializes PDF objects from a list of paths/URLs."""
+        logger.info(f"Initializing {len(paths_or_urls)} PDF objects...")
+        failed_count = 0
+        for path_or_url in tqdm(paths_or_urls, desc="Loading PDFs"):
+            try:
+                pdf_instance = PDF_cls(path_or_url, **self._pdf_options)
+                self._pdfs.append(pdf_instance)
+            except Exception as e:
+                 logger.error(f"Failed to load PDF: {path_or_url}. Error: {e}", exc_info=False) # Keep log concise
+                 failed_count += 1
+        logger.info(f"Successfully initialized {len(self._pdfs)} PDFs. Failed: {failed_count}")
+
+    # --- Public Factory Class Methods (Simplified) ---
+
+    @classmethod
+    def from_paths(cls, paths_or_urls: List[str], **pdf_options: Any) -> 'PDFCollection':
+        """Creates a PDFCollection explicitly from a list of file paths or URLs."""
+        # __init__ can handle List[str] directly now
+        return cls(paths_or_urls, **pdf_options)
+
+    @classmethod
+    def from_glob(cls, pattern: str, recursive: bool = True, **pdf_options: Any) -> 'PDFCollection':
+        """Creates a PDFCollection explicitly from a single glob pattern."""
+        # __init__ can handle single glob string directly
+        return cls(pattern, recursive=recursive, **pdf_options)
+
+    @classmethod
+    def from_globs(cls, patterns: List[str], recursive: bool = True, **pdf_options: Any) -> 'PDFCollection':
+        """Creates a PDFCollection explicitly from a list of glob patterns."""
+         # __init__ can handle List[str] containing globs directly
+        return cls(patterns, recursive=recursive, **pdf_options)
+
+    @classmethod
+    def from_directory(cls, directory_path: str, recursive: bool = True, **pdf_options: Any) -> 'PDFCollection':
+        """Creates a PDFCollection explicitly from PDF files within a directory."""
+        # __init__ can handle single directory string directly
+        return cls(directory_path, recursive=recursive, **pdf_options)
+
+    # --- Core Collection Methods ---
+    def __len__(self) -> int:
+        return len(self._pdfs)
+
+    def __getitem__(self, key) -> Union['PDF', 'PDFCollection']:
+        # Use dynamic import here as well
+        PDF = self._get_pdf_class()
+        if isinstance(key, slice):
+            # Create a new collection with the sliced PDFs and original options
+            new_collection = PDFCollection.__new__(PDFCollection) # Create blank instance
+            new_collection._pdfs = self._pdfs[key]
+            new_collection._pdf_options = self._pdf_options
+            new_collection._recursive = self._recursive
+            # Search context is not copied/inherited anymore
+            return new_collection
+        elif isinstance(key, int):
+            # Check bounds
+            if 0 <= key < len(self._pdfs):
+                return self._pdfs[key]
+            else:
+                 raise IndexError(f"PDF index {key} out of range (0-{len(self._pdfs)-1}).")
+        else:
+             raise TypeError(f"PDF indices must be integers or slices, not {type(key)}.")
+
+    def __iter__(self):
+        return iter(self._pdfs)
+
+    def __repr__(self) -> str:
+        # Removed search status
+        return f"<PDFCollection(count={len(self)})>"
+
+    @property
+    def pdfs(self) -> List['PDF']:
+         """Returns the list of PDF objects held by the collection."""
+         return self._pdfs
+
+    # --- Other Methods (e.g., apply_ocr_to_pages - could leverage service in future?) ---
+    def apply_ocr_to_pages(self, *args, **kwargs):
+        PDF = self._get_pdf_class()
+        # Delegate to individual PDF objects
+        logger.info("Applying OCR to relevant PDFs in collection...")
+        results = []
+        for pdf in self._pdfs:
+             # We need to figure out which pages belong to which PDF if batching here
+             # For now, simpler to call on each PDF
+             try:
+                 # Assume apply_ocr_to_pages exists on PDF and accepts similar args
+                 pdf.apply_ocr_to_pages(*args, **kwargs)
+             except Exception as e:
+                 logger.error(f"Failed applying OCR to {pdf.path}: {e}", exc_info=True)
+        return self
+
+    # --- Advanced Method Placeholders ---
+    # Placeholder for categorize removed as find_relevant is now implemented
+
+    def categorize(self, categories: List[str], **kwargs):
+        """Categorizes PDFs in the collection based on content or features."""
+        # Implementation requires integrating with classification models or logic
+        raise NotImplementedError("categorize requires classification implementation.") 
+
+    # --- Mixin Required Implementation --- 
+    def get_indexable_items(self) -> Iterable[Indexable]:
+        """Yields Page objects from the collection, conforming to Indexable."""
+        if not self._pdfs:
+             return # Return empty iterator if no PDFs
+             
+        for pdf in self._pdfs:
+             if not pdf.pages: # Handle case where a PDF might have 0 pages after loading
+                 logger.warning(f"PDF '{pdf.path}' has no pages. Skipping.")
+                 continue
+             for page in pdf.pages:
+                 # Optional: Add filtering here if needed (e.g., skip empty pages)
+                 # Assuming Page object conforms to Indexable
+                 # We might still want the empty page check here for efficiency
+                 # if not page.extract_text(use_exclusions=False).strip():
+                 #     logger.debug(f"Skipping empty page {page.page_number} from PDF '{pdf.path}'.")
+                 #     continue
+                 yield page