natural-pdf 0.1.0__py3-none-any.whl

natural_pdf/__init__.py

@@ -0,0 +1,55 @@
+"""
+Natural PDF - A more intuitive interface for working with PDFs.
+"""
+import logging
+
+# Create library logger
+logger = logging.getLogger("natural_pdf")
+
+# Add a NullHandler to prevent "No handler found" warnings
+# (Best practice for libraries)
+logger.addHandler(logging.NullHandler())
+
+# Utility function for users to easily configure logging
+def configure_logging(level=logging.INFO, handler=None):
+    """Configure Natural PDF's logging.
+    
+    Args:
+        level: The logging level (e.g., logging.INFO, logging.DEBUG)
+        handler: A custom handler, or None to use StreamHandler
+    """
+    # Remove NullHandler if present
+    if logger.handlers and isinstance(logger.handlers[0], logging.NullHandler):
+        logger.removeHandler(logger.handlers[0])
+    
+    if handler is None:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
+        handler.setFormatter(formatter)
+    
+    logger.addHandler(handler)
+    logger.setLevel(level)
+    
+    # Propagate level to all child loggers
+    for name in logging.root.manager.loggerDict:
+        if name.startswith("natural_pdf."):
+            logging.getLogger(name).setLevel(level)
+
+from natural_pdf.core.pdf import PDF
+from natural_pdf.core.page import Page
+from natural_pdf.elements.region import Region
+from natural_pdf.elements.collections import ElementCollection
+
+# Import QA module if available
+try:
+    from natural_pdf.qa import DocumentQA, get_qa_engine
+    HAS_QA = True
+except ImportError:
+    HAS_QA = False
+
+__version__ = "0.1.0"
+
+if HAS_QA:
+    __all__ = ["PDF", "Page", "Region", "ElementCollection", "configure_logging", "DocumentQA", "get_qa_engine"]
+else:
+    __all__ = ["PDF", "Page", "Region", "ElementCollection", "configure_logging"]

natural_pdf/analyzers/__init__.py

@@ -0,0 +1,6 @@
+"""
+Analyzers for natural-pdf.
+"""
+from .layout import *
+from .text_structure import TextStyleAnalyzer
+from .utils import convert_to_regions

natural_pdf/analyzers/layout/__init__.py

@@ -0,0 +1 @@
+from .base import LayoutDetector

natural_pdf/analyzers/layout/base.py

@@ -0,0 +1,151 @@
+# layout_detector_base.py
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, List, Any, Optional, Set, Union
+from PIL import Image
+
+# Assuming layout_options defines BaseLayoutOptions
+try:
+    from .layout_options import BaseLayoutOptions
+except ImportError:
+    # Placeholder if run standalone or options not found
+    class BaseLayoutOptions: pass
+
+logger = logging.getLogger(__name__)
+
+class LayoutDetector(ABC):
+    """
+    Abstract Base Class for layout detection engines.
+
+    Subclasses should implement is_available, _load_model_from_options, detect,
+    and override _get_cache_key if model loading depends on options beyond device.
+    They should also populate the 'supported_classes' set.
+    """
+
+    def __init__(self):
+        """Initializes the base layout detector."""
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+        self.logger.info(f"Initializing {self.__class__.__name__}")
+        self.supported_classes: Set[str] = set() # Subclasses should populate this
+        self._model_cache: Dict[str, Any] = {} # Cache for initialized models
+
+    @abstractmethod
+    def detect(self, image: Image.Image, options: BaseLayoutOptions) -> List[Dict[str, Any]]:
+        """
+        Detect layout elements in a given PIL Image.
+
+        Args:
+            image: PIL Image of the page to analyze.
+            options: An instance of a dataclass inheriting from BaseLayoutOptions
+                     containing configuration for this run.
+
+        Returns:
+            List of standardized detection dictionaries with at least:
+            - 'bbox': Tuple[float, float, float, float] - (x0, y0, x1, y1) relative to image size
+            - 'class': str - Original class name from the model
+            - 'confidence': float - Confidence score (0.0-1.0)
+            - 'normalized_class': str - Hyphenated, lowercase class name
+            - 'model': str - Name of the model used (e.g., 'yolo', 'tatr')
+            - 'source': str - Usually 'layout'
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Check if the detector's dependencies are installed and usable.
+
+        Returns:
+            True if the detector is available, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    def _get_cache_key(self, options: BaseLayoutOptions) -> str:
+        """
+        Generates a cache key for model loading based on relevant options.
+        Subclasses MUST override this to include options that change the loaded model
+        (e.g., model path, model name, specific configurations like TATR structure model).
+
+        Args:
+            options: The options dataclass instance.
+
+        Returns:
+            A string cache key.
+        """
+        # Base key only includes device, subclasses MUST add model specifics
+        device_key = str(options.device).lower()
+        return f"{self.__class__.__name__}_{device_key}"
+
+    def _get_model(self, options: BaseLayoutOptions) -> Any:
+        """
+        Gets or initializes the underlying model based on options, using caching.
+        Subclasses must implement _load_model_from_options.
+        """
+        cache_key = self._get_cache_key(options)
+        if cache_key not in self._model_cache:
+             self.logger.info(f"Loading model for cache key: {cache_key}")
+             try:
+                 # Ensure dependencies are met before loading
+                 if not self.is_available():
+                      raise RuntimeError(f"{self.__class__.__name__} dependencies are not met.")
+                 self._model_cache[cache_key] = self._load_model_from_options(options)
+                 self.logger.info(f"Model loaded successfully for key: {cache_key}")
+             except Exception as e:
+                  self.logger.error(f"Failed to load model for key {cache_key}: {e}", exc_info=True)
+                  # Remove potentially corrupted cache entry
+                  self._model_cache.pop(cache_key, None)
+                  raise # Re-raise exception after logging
+        else:
+             self.logger.debug(f"Using cached model for key: {cache_key}")
+        return self._model_cache[cache_key]
+
+    @abstractmethod
+    def _load_model_from_options(self, options: BaseLayoutOptions) -> Any:
+        """
+        Abstract method for subclasses to implement the actual model loading logic
+        based on the provided options. Should return the loaded model object(s).
+        Should handle necessary imports internally.
+        """
+        raise NotImplementedError("Subclasses must implement _load_model_from_options")
+
+    def _normalize_class_name(self, name: str) -> str:
+        """Convert class names with spaces/underscores to hyphenated lowercase format."""
+        if not isinstance(name, str): name = str(name) # Ensure string
+        return name.lower().replace(' ', '-').replace('_', '-')
+
+    def validate_classes(self, classes: List[str]) -> None:
+        """
+        Validate that the requested classes are supported by this detector.
+
+        Args:
+            classes: List of class names to validate.
+
+        Raises:
+            ValueError: If any class is not supported.
+        """
+        if not self.supported_classes:
+             self.logger.warning("Supported classes not defined for this detector. Skipping class validation.")
+             return
+
+        if classes:
+            # Normalize both requested and supported classes for comparison
+            normalized_supported = {self._normalize_class_name(c) for c in self.supported_classes}
+            normalized_requested = {self._normalize_class_name(c) for c in classes}
+            unsupported_normalized = normalized_requested - normalized_supported
+
+            if unsupported_normalized:
+                # Find original names of unsupported classes for better error message
+                unsupported_original = [
+                    c for c in classes if self._normalize_class_name(c) in unsupported_normalized
+                ]
+                raise ValueError(f"Classes not supported by {self.__class__.__name__}: {unsupported_original}. "
+                               f"Supported (normalized): {sorted(list(normalized_supported))}")
+
+    def __del__(self):
+        """Cleanup resources."""
+        self.logger.info(f"Cleaning up {self.__class__.__name__} resources.")
+        # Clear model cache to free up memory/GPU resources if models are large
+        # Consider implications if models are shared or expensive to reload
+        # del self._model_cache # Optional: uncomment if models should be released aggressively
+        self._model_cache.clear()
+

natural_pdf/analyzers/layout/docling.py

@@ -0,0 +1,247 @@
+# layout_detector_docling.py
+import logging
+import importlib.util
+import os
+import tempfile
+from typing import List, Dict, Any, Optional
+from PIL import Image
+
+# Assuming base class and options are importable
+try:
+    from .base import LayoutDetector
+    from .layout_options import DoclingLayoutOptions, BaseLayoutOptions
+except ImportError:
+    # Placeholders if run standalone or imports fail
+    class BaseLayoutOptions: pass
+    class DoclingLayoutOptions(BaseLayoutOptions): pass
+    class LayoutDetector:
+         def __init__(self): self.logger=logging.getLogger(); self.supported_classes=set()
+         def _get_model(self, options): raise NotImplementedError
+         def _normalize_class_name(self, n): return n
+         def validate_classes(self, c): pass
+    logging.basicConfig()
+
+logger = logging.getLogger(__name__)
+
+# Check for dependency
+docling_spec = importlib.util.find_spec("docling")
+DocumentConverter = None
+if docling_spec:
+    try:
+        from docling.document_converter import DocumentConverter
+    except ImportError as e:
+        logger.warning(f"Could not import Docling dependencies: {e}")
+else:
+    logger.warning("docling not found. DoclingLayoutDetector will not be available.")
+
+
+class DoclingLayoutDetector(LayoutDetector):
+    """Document layout and text recognition using Docling."""
+
+    def __init__(self):
+        super().__init__()
+        # Docling classes are dynamic/hierarchical, define common ones
+        self.supported_classes = {
+            'Header', 'Footer', 'Paragraph', 'Heading', 'List', 'ListItem',
+            'Table', 'Figure', 'Caption', 'Footnote', 'PageNumber', 'Equation',
+            'Code', 'Title', 'Author', 'Abstract', 'Section', 'Unknown', 'Metadata' # Add more as needed
+        }
+        self._docling_document_cache = {} # Cache the output doc per image/options if needed
+
+    def is_available(self) -> bool:
+        """Check if docling is installed."""
+        return DocumentConverter is not None
+
+    def _get_cache_key(self, options: BaseLayoutOptions) -> str:
+        """Generate cache key based on device and potentially converter args."""
+        if not isinstance(options, DoclingLayoutOptions):
+             options = DoclingLayoutOptions(device=options.device, extra_args=options.extra_args)
+
+        device_key = str(options.device).lower() if options.device else 'default_device'
+        # Include hash of extra_args if they affect model loading/converter init
+        extra_args_key = hash(frozenset(options.extra_args.items()))
+        return f"{self.__class__.__name__}_{device_key}_{extra_args_key}"
+
+    def _load_model_from_options(self, options: BaseLayoutOptions) -> Any:
+        """Load the Docling DocumentConverter."""
+        if not self.is_available():
+            raise RuntimeError("Docling dependency not installed.")
+
+        if not isinstance(options, DoclingLayoutOptions):
+            raise TypeError("Incorrect options type provided for Docling model loading.")
+
+        self.logger.info("Initializing Docling DocumentConverter...")
+        try:
+            # Pass device if converter accepts it, otherwise handle via extra_args
+            converter_args = options.extra_args.copy()
+
+            converter = DocumentConverter(**converter_args)
+            self.logger.info("Docling DocumentConverter initialized.")
+            return converter
+        except Exception as e:
+            self.logger.error(f"Failed to initialize Docling DocumentConverter: {e}", exc_info=True)
+            raise
+
+    def detect(self, image: Image.Image, options: BaseLayoutOptions) -> List[Dict[str, Any]]:
+        """Detect document structure and text using Docling."""
+        if not self.is_available():
+            raise RuntimeError("Docling dependency not installed.")
+
+        if not isinstance(options, DoclingLayoutOptions):
+             self.logger.warning("Received BaseLayoutOptions, expected DoclingLayoutOptions. Using defaults.")
+             options = DoclingLayoutOptions(
+                 confidence=options.confidence, classes=options.classes,
+                 exclude_classes=options.exclude_classes, device=options.device,
+                 extra_args=options.extra_args, verbose=options.extra_args.get('verbose', False)
+             )
+
+        # Validate classes before proceeding (note: Docling classes are case-sensitive)
+        # self.validate_classes(options.classes or []) # Validation might be tricky due to case sensitivity
+        # if options.exclude_classes:
+        #     self.validate_classes(options.exclude_classes)
+
+        # Get the cached/loaded converter instance
+        converter = self._get_model(options)
+
+        # Docling convert method requires an image path. Save temp file.
+        detections = []
+        docling_doc = None # To store the result
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_image_path = os.path.join(temp_dir, f"docling_input_{os.getpid()}.png")
+            try:
+                self.logger.debug(f"Saving temporary image for Docling detector to: {temp_image_path}")
+                image.convert("RGB").save(temp_image_path) # Ensure RGB
+
+                # Convert the document using Docling's DocumentConverter
+                self.logger.debug("Running Docling conversion...")
+                # Docling convert returns a Result object with a 'document' attribute
+                result = converter.convert(temp_image_path)
+                docling_doc = result.document # Store the DoclingDocument
+                self.logger.info(f"Docling conversion complete.")
+
+                # Convert Docling document to our detection format
+                detections = self._convert_docling_to_detections(docling_doc, options)
+
+            except Exception as e:
+                self.logger.error(f"Error during Docling detection: {e}", exc_info=True)
+                raise # Re-raise the exception
+            finally:
+                 # Ensure temp file is removed
+                 if os.path.exists(temp_image_path):
+                      try: os.remove(temp_image_path)
+                      except OSError as e_rm: self.logger.warning(f"Could not remove temp file {temp_image_path}: {e_rm}")
+
+        # Cache the docling document if needed elsewhere (maybe associate with page?)
+        # self._docling_document_cache[image_hash] = docling_doc # Needs a way to key this
+
+        self.logger.info(f"Docling detected {len(detections)} layout elements matching criteria.")
+        return detections
+
+    def _convert_docling_to_detections(self, doc, options: DoclingLayoutOptions) -> List[Dict[str, Any]]:
+        """Convert a Docling document to our standard detection format."""
+        if not doc or not hasattr(doc, 'pages') or not doc.pages:
+            self.logger.warning("Invalid or empty Docling document for conversion.")
+            return []
+
+        detections = []
+        id_to_detection_index = {} # Map Docling ID to index in detections list
+
+        # 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()
+
+        # --- Iterate through elements using Docling's structure ---
+        # This requires traversing the hierarchy (e.g., doc.body.children)
+        # or iterating through specific lists like doc.texts, doc.tables etc.
+        elements_to_process = []
+        if hasattr(doc, 'texts'): elements_to_process.extend(doc.texts)
+        if hasattr(doc, 'tables'): elements_to_process.extend(doc.tables)
+        if hasattr(doc, 'pictures'): elements_to_process.extend(doc.pictures)
+        # Add other element types from DoclingDocument as needed
+
+        self.logger.debug(f"Converting {len(elements_to_process)} Docling elements...")
+
+        for elem in elements_to_process:
+            try:
+                # Get Provenance (bbox and page number)
+                if not hasattr(elem, 'prov') or not elem.prov: continue
+                prov = elem.prov[0] # Use first provenance
+                if not hasattr(prov, 'bbox') or not prov.bbox: continue
+                bbox = prov.bbox
+                page_no = prov.page_no
+
+                # Get Page Dimensions (crucial for coordinate conversion)
+                if not hasattr(doc.pages.get(page_no), 'size'): continue
+                page_height = doc.pages[page_no].size.height
+                page_width = doc.pages[page_no].size.width # Needed? Bbox seems absolute
+
+                # Convert coordinates from Docling's system (often bottom-left origin)
+                # to standard top-left origin (0,0 at top-left)
+                # Docling Bbox: l, b, r, t (relative to bottom-left)
+                x0 = float(bbox.l)
+                x1 = float(bbox.r)
+                # Convert y: top_y = page_height - bottom_left_t
+                #            bottom_y = page_height - bottom_left_b
+                y0 = float(page_height - bbox.t) # Top y
+                y1 = float(page_height - bbox.b) # Bottom y
+
+                # Ensure y0 < y1
+                if y0 > y1: y0, y1 = y1, y0
+                # Ensure x0 < x1
+                if x0 > x1: x0, x1 = x1, x0
+
+                # Get Class Label
+                label_orig = str(getattr(elem, 'label', 'Unknown')) # Default if no label
+                normalized_label = self._normalize_class_name(label_orig)
+
+                # Apply Class Filtering
+                if normalized_classes_req and normalized_label not in normalized_classes_req: continue
+                if normalized_label in normalized_classes_excl: continue
+
+                # Get Confidence (Docling often doesn't provide per-element confidence)
+                confidence = getattr(elem, 'confidence', 0.95) # Assign default confidence
+                if confidence < options.confidence: continue # Apply confidence threshold
+
+                # Get Text Content
+                text_content = getattr(elem, 'text', None)
+
+                # Get IDs for hierarchy
+                docling_id = getattr(elem, 'self_ref', None)
+                parent_id_obj = getattr(elem, 'parent', None)
+                parent_id = getattr(parent_id_obj, 'self_ref', None) if parent_id_obj else None
+
+                # Create Detection Dictionary
+                detection = {
+                    'bbox': (x0, y0, x1, y1),
+                    'class': label_orig,
+                    'normalized_class': normalized_label,
+                    'confidence': confidence,
+                    'text': text_content,
+                    'docling_id': docling_id,
+                    'parent_id': parent_id,
+                    'page_number': page_no, # Add page number if useful
+                    'source': 'layout',
+                    'model': 'docling'
+                }
+                detections.append(detection)
+
+                # Store index for hierarchy linking (if needed later)
+                # if docling_id: id_to_detection_index[docling_id] = len(detections) - 1
+
+            except Exception as conv_e:
+                 self.logger.warning(f"Could not convert Docling element: {elem}. Error: {conv_e}")
+                 continue
+
+        return detections
+
+    def get_docling_document(self, image: Image.Image, options: BaseLayoutOptions):
+        """
+        Get the raw DoclingDocument object after running detection.
+        Ensures detection is run if not already cached for these options/image.
+        """
+        # This requires caching the doc based on image/options or re-running.
+        # For simplicity, let's just re-run detect if needed.
+        self.logger.warning("get_docling_document: Re-running detection to ensure document is generated.")
+        self.detect(image, options) # Run detect to populate internal doc
+        return getattr(self, '_docling_document', None) # Return the stored doc
+

natural_pdf/analyzers/layout/layout_analyzer.py

@@ -0,0 +1,166 @@
+import logging
+from typing import List, Dict, Any, Optional, Union
+from PIL import Image
+
+from natural_pdf.elements.region import Region
+from natural_pdf.analyzers.layout.layout_manager import LayoutManager
+from natural_pdf.analyzers.layout.layout_options import LayoutOptions
+
+logger = logging.getLogger(__name__)
+
+class LayoutAnalyzer:
+    """
+    Handles layout analysis for PDF pages, including image rendering,
+    coordinate scaling, region creation, and result storage.
+    """
+    
+    def __init__(self, page, layout_manager: Optional[LayoutManager] = None):
+        """
+        Initialize the layout analyzer.
+        
+        Args:
+            page: The Page object to analyze
+            layout_manager: Optional LayoutManager instance. If None, will try to get from page's parent.
+        """
+        self._page = page
+        self._layout_manager = layout_manager or getattr(page._parent, '_layout_manager', None)
+        
+        if not self._layout_manager:
+            logger.warning(f"LayoutManager not available for page {page.number}. Layout analysis will fail.")
+    
+    def analyze_layout(
+        self,
+        engine: Optional[str] = None,
+        options: Optional[LayoutOptions] = None,
+        confidence: Optional[float] = None,
+        classes: Optional[List[str]] = None,
+        exclude_classes: Optional[List[str]] = None,
+        device: Optional[str] = None,
+        existing: str = "replace"
+    ) -> List[Region]:
+        """
+        Analyze the page layout using the configured LayoutManager.
+        
+        Args:
+            engine: Name of the layout engine (e.g., 'yolo', 'tatr'). Uses manager's default if None.
+            options: Specific LayoutOptions object for advanced configuration.
+            confidence: Minimum confidence threshold (simple mode).
+            classes: Specific classes to detect (simple mode).
+            exclude_classes: Classes to exclude (simple mode).
+            device: Device for inference (simple mode).
+            existing: How to handle existing detected regions: 'replace' (default) or 'append'.
+            
+        Returns:
+            List of created Region objects.
+        """
+        if not self._layout_manager:
+            logger.error(f"Page {self._page.number}: LayoutManager not available. Cannot analyze layout.")
+            return []
+
+        logger.info(f"Page {self._page.number}: Analyzing layout (Engine: {engine or 'default'}, Options: {options is not None})...")
+
+        # --- Render Page Image ---
+        logger.debug(f"  Rendering page {self._page.number} to image for layout analysis...")
+        try:
+            # Use a resolution suitable for layout analysis, potentially configurable
+            layout_scale = getattr(self._page._parent, '_config', {}).get('layout_image_scale', 1.5) # ~108 DPI default
+            layout_resolution = layout_scale * 72
+            # Render without existing highlights to avoid interference
+            page_image = self._page.to_image(resolution=layout_resolution, include_highlights=False)
+            logger.debug(f"  Rendered image size: {page_image.width}x{page_image.height}")
+        except Exception as e:
+            logger.error(f"  Failed to render page {self._page.number} to image: {e}", exc_info=True)
+            return []
+
+        # --- Prepare Arguments for Layout Manager ---
+        manager_args = {'image': page_image, 'options': options, 'engine': engine}
+        if confidence is not None: manager_args['confidence'] = confidence
+        if classes is not None: manager_args['classes'] = classes
+        if exclude_classes is not None: manager_args['exclude_classes'] = exclude_classes
+        if device is not None: manager_args['device'] = device
+
+        # --- Call Layout Manager ---
+        logger.debug(f"  Calling Layout Manager...")
+        try:
+            detections = self._layout_manager.analyze_layout(**manager_args)
+            logger.info(f"  Layout Manager returned {len(detections)} detections.")
+        except Exception as e:
+            logger.error(f"  Layout analysis failed: {e}", exc_info=True)
+            return []
+
+        # --- Process Detections (Convert to Regions, Scale Coords) ---
+        # Calculate scale factor to convert from image back to PDF coordinates
+        if page_image.width == 0 or page_image.height == 0:
+            logger.error(f"Page {self._page.number}: Invalid rendered image dimensions ({page_image.width}x{page_image.height}). Cannot scale layout results.")
+            return []
+        scale_x = self._page.width / page_image.width
+        scale_y = self._page.height / page_image.height
+        logger.debug(f"  Scaling factors: x={scale_x:.4f}, y={scale_y:.4f}")
+
+        layout_regions = []
+        docling_id_to_region = {} # For hierarchy if using Docling
+
+        for detection in detections:
+            try:
+                x_min, y_min, x_max, y_max = detection['bbox']
+
+                # Convert coordinates from image to PDF space
+                pdf_x0 = x_min * scale_x
+                pdf_y0 = y_min * scale_y
+                pdf_x1 = x_max * scale_x
+                pdf_y1 = y_max * scale_y
+
+                # Create a Region object
+                region = Region(self._page, (pdf_x0, pdf_y0, pdf_x1, pdf_y1))
+                region.region_type = detection.get('class', 'unknown') # Original class name
+                region.normalized_type = detection.get('normalized_class', 'unknown') # Hyphenated name
+                region.confidence = detection.get('confidence', 0.0)
+                region.model = detection.get('model', engine or 'unknown') # Store model name
+                region.source = 'detected'
+
+                # Add extra info if available
+                if 'text' in detection: region.text_content = detection['text']
+                if 'docling_id' in detection: region.docling_id = detection['docling_id']
+                if 'parent_id' in detection: region.parent_id = detection['parent_id']
+                # Add other fields like polygon, position, row/col index if needed
+
+                layout_regions.append(region)
+
+                # Track Docling IDs for hierarchy
+                if hasattr(region, 'docling_id') and region.docling_id:
+                    docling_id_to_region[region.docling_id] = region
+
+            except (KeyError, IndexError, TypeError, ValueError) as e:
+                logger.warning(f"Could not process layout detection: {detection}. Error: {e}")
+                continue
+
+        # --- Build Hierarchy (if Docling results detected) ---
+        if docling_id_to_region:
+            logger.debug("Building Docling region hierarchy...")
+            for region in layout_regions:
+                if hasattr(region, 'parent_id') and region.parent_id:
+                    parent_region = docling_id_to_region.get(region.parent_id)
+                    if parent_region:
+                        if hasattr(parent_region, 'add_child'):
+                            parent_region.add_child(region)
+                        else:
+                            logger.warning("Region object missing add_child method for hierarchy.")
+
+        # --- Store Results ---
+        logger.debug(f"Storing {len(layout_regions)} processed layout regions (mode: {existing}).")
+        # Handle existing regions based on mode
+        if existing.lower() == 'append':
+            if 'detected' not in self._page._regions: self._page._regions['detected'] = []
+            self._page._regions['detected'].extend(layout_regions)
+        else: # Default is 'replace'
+            self._page._regions['detected'] = layout_regions
+
+        # Add regions to the element manager
+        for region in layout_regions:
+            self._page._element_mgr.add_region(region)
+
+        # Store layout regions in a dedicated attribute for easier access
+        self._page.detected_layout_regions = self._page._regions['detected']
+        logger.info(f"Layout analysis complete for page {self._page.number}.")
+        
+        return layout_regions