natural-pdf 25.3.16.2__py3-none-any.whl → 25.3.17.2__py3-none-any.whl

natural_pdf/elements/region.py

@@ -18,7 +18,7 @@ class Region:
     Represents a rectangular region on a page.
     """
     
-    def __init__(self, page: 'Page', bbox: Tuple[float, float, float, float], polygon: List[Tuple[float, float]] = None):
+    def __init__(self, page: 'Page', bbox: Tuple[float, float, float, float], polygon: List[Tuple[float, float]] = None, parent=None):
         """
         Initialize a region.
         
@@ -26,6 +26,7 @@ class Region:
             page: Parent page
             bbox: Bounding box as (x0, top, x1, bottom)
             polygon: Optional list of coordinate points [(x1,y1), (x2,y2), ...] for non-rectangular regions
+            parent: Optional parent region (for hierarchical document structure)
         """
         self._page = page
         self._bbox = bbox
@@ -48,6 +49,12 @@ class Region:
         # Region management attributes
         self.name = None
         self.source = None  # Will be set by creation methods
+        
+        # Hierarchy support for nested document structure
+        self.parent_region = parent
+        self.child_regions = []
+        self.text_content = None  # Direct text content (e.g., from Docling)
+        self.associated_text_elements = []  # Native text elements that overlap with this region
     
     @property
     def page(self) -> 'Page':
@@ -387,6 +394,11 @@ class Region:
         """
         Extract text from this region using pdfplumber's native functionality.
         
+        For regions created by Docling, this will first try to use:
+        1. Associated text elements from the PDF (if available)
+        2. Direct text content from Docling (if available)
+        3. Fall back to standard pdfplumber extraction
+        
         Args:
             keep_blank_chars: Whether to keep blank characters (legacy parameter)
             apply_exclusions: Whether to apply exclusion regions
@@ -398,6 +410,28 @@ class Region:
         Returns:
             Extracted text as string
         """
+        import logging
+        logger = logging.getLogger("natural_pdf.elements.region")
+        
+        # Check for Docling model or if we have direct text content
+        if self.model == 'docling' or hasattr(self, 'text_content'):
+            # First priority: check if we have associated native text elements
+            if hasattr(self, 'associated_text_elements') and self.associated_text_elements:
+                source_count = len(self.associated_text_elements)
+                logger.info(f"Region {self.region_type}: Using {source_count} native PDF text elements")
+                # Sort elements in reading order
+                sorted_elements = sorted(self.associated_text_elements, key=lambda e: (e.top, e.x0))
+                # Extract and join their text
+                text_result = " ".join(elem.text for elem in sorted_elements)
+                return text_result
+                
+            # Second priority: use direct text content from Docling
+            elif self.text_content:
+                logger.info(f"Region {self.region_type}: Using Docling OCR text content")
+                return self.text_content
+                
+            logger.debug(f"Region {self.region_type}: No Docling text found, falling back to standard extraction")
+                
         # Handle preserve_whitespace parameter for consistency with Page.extract_text
         if preserve_whitespace is not None:
             keep_blank_chars = preserve_whitespace
@@ -1346,21 +1380,142 @@ class Region:
                 "source_elements": list of elements that contain the answer (if found)
             }
         """
-        try:
-            from natural_pdf.qa.document_qa import get_qa_engine
-            
-            # Get or initialize QA engine with specified model
-            qa_engine = get_qa_engine(model_name=model) if model else get_qa_engine()
-            
-            # Ask the question using the QA engine
-            return qa_engine.ask_pdf_region(self, question, min_confidence=min_confidence, debug=debug, **kwargs)
-        except ImportError as e:
-            import logging
-            logger = logging.getLogger("natural_pdf.elements.region")
-            logger.warning(f"QA functionality not available: {e}")
-            return {
-                "answer": "",
-                "confidence": 0.0,
-                "error": "QA functionality not available",
-                "found": False
-            }
+        from natural_pdf.qa.document_qa import get_qa_engine
+        
+        # Get or initialize QA engine with specified model
+        qa_engine = get_qa_engine(model_name=model) if model else get_qa_engine()
+        
+        # Ask the question using the QA engine
+        
+    def add_child(self, child):
+        """
+        Add a child region to this region.
+        
+        Used for hierarchical document structure when using models like Docling
+        that understand document hierarchy.
+        
+        Args:
+            child: Region object to add as a child
+            
+        Returns:
+            Self for method chaining
+        """
+        self.child_regions.append(child)
+        child.parent_region = self
+        return self
+        
+    def get_children(self, selector=None):
+        """
+        Get immediate child regions, optionally filtered by selector.
+        
+        Args:
+            selector: Optional selector to filter children
+            
+        Returns:
+            List of child regions matching the selector
+        """
+        import logging
+        logger = logging.getLogger("natural_pdf.elements.region")
+        
+        if selector is None:
+            return self.child_regions
+        
+        # Use existing selector parser to filter
+        from natural_pdf.selectors.parser import match_elements_with_selector
+        matched = match_elements_with_selector(self.child_regions, selector)
+        logger.debug(f"get_children: found {len(matched)} of {len(self.child_regions)} children matching '{selector}'")
+        return matched
+        
+    def get_descendants(self, selector=None):
+        """
+        Get all descendant regions (children, grandchildren, etc.), optionally filtered by selector.
+        
+        Args:
+            selector: Optional selector to filter descendants
+            
+        Returns:
+            List of descendant regions matching the selector
+        """
+        import logging
+        logger = logging.getLogger("natural_pdf.elements.region")
+        
+        all_descendants = []
+        
+        # First add direct children
+        all_descendants.extend(self.child_regions)
+        
+        # Then recursively add their descendants
+        for child in self.child_regions:
+            all_descendants.extend(child.get_descendants())
+            
+        logger.debug(f"get_descendants: found {len(all_descendants)} total descendants")
+            
+        # Filter by selector if provided
+        if selector is not None:
+            from natural_pdf.selectors.parser import match_elements_with_selector
+            matched = match_elements_with_selector(all_descendants, selector)
+            logger.debug(f"get_descendants: filtered to {len(matched)} matching '{selector}'")
+            return matched
+        
+        return all_descendants
+        
+    def find_all(self, selector, recursive=True, **kwargs):
+        """
+        Find all matching elements within this region, with optional recursion through child regions.
+        
+        Args:
+            selector: The selector to find elements with
+            recursive: Whether to search recursively through child regions
+            **kwargs: Additional parameters to pass to the selector parser
+            
+        Returns:
+            Collection of matching elements
+        """
+        # Get direct matches 
+        direct_matches = self.page.find_all(selector, region=self, **kwargs)
+        
+        if not recursive or not self.child_regions:
+            return direct_matches
+            
+        # Get recursive matches from children
+        from natural_pdf.elements.collections import ElementCollection
+        all_matches = list(direct_matches)
+        
+        for child in self.child_regions:
+            child_matches = child.find_all(selector, recursive=True, **kwargs)
+            for match in child_matches:
+                if match not in all_matches:
+                    all_matches.append(match)
+                    
+        return ElementCollection(all_matches)
+    
+    def ask(self, question: str, min_confidence: float = 0.1, model: str = None, debug: bool = False, **kwargs) -> Dict[str, Any]:
+        """
+        Ask a question about the region content using document QA.
+        
+        This method uses a document question answering model to extract answers from the region content.
+        It leverages both textual content and layout information for better understanding.
+        
+        Args:
+            question: The question to ask about the region content
+            min_confidence: Minimum confidence threshold for answers (0.0-1.0)
+            model: Optional model name to use for QA (if None, uses default model)
+            **kwargs: Additional parameters to pass to the QA engine
+            
+        Returns:
+            Dictionary with answer details: {
+                "answer": extracted text,
+                "confidence": confidence score,
+                "found": whether an answer was found,
+                "page_num": page number,
+                "region": reference to this region,
+                "source_elements": list of elements that contain the answer (if found)
+            }
+        """
+        from natural_pdf.qa.document_qa import get_qa_engine
+        
+        # Get or initialize QA engine with specified model
+        qa_engine = get_qa_engine(model_name=model) if model else get_qa_engine()
+        
+        # Ask the question using the QA engine
+        return qa_engine.ask_pdf_region(self, question, min_confidence=min_confidence, debug=debug, **kwargs)

natural_pdf/qa/document_qa.py

@@ -1,7 +1,7 @@
 import logging
 from typing import List, Dict, Any, Optional, Union, Tuple
 import numpy as np
-from PIL import Image
+from PIL import Image, ImageDraw
 import os
 import tempfile
 import json
@@ -207,47 +207,38 @@ class DocumentQA:
                 logger.info(f"Visualization: {vis_path}")
         
         # Run the query through the pipeline
-        try:
-            logger.info(f"Running document QA pipeline with question: {question}")
-            result = self.pipe(query)[0]
-            logger.info(f"Raw result: {result}")
-            
-            # Save the result if debugging
-            if debug:
-                result_path = os.path.join(debug_output_dir, "debug_qa_result.json")
-                with open(result_path, 'w') as f:
-                    # Convert any non-serializable data
-                    serializable_result = {k: str(v) if not isinstance(v, (str, int, float, bool, list, dict, type(None))) else v 
-                                        for k, v in result.items()}
-                    json.dump(serializable_result, f, indent=2)
-            
-            # Check confidence against threshold
-            if result["score"] < min_confidence:
-                logger.info(f"Answer confidence {result['score']:.4f} below threshold {min_confidence}")
-                return {
-                    "answer": "",
-                    "confidence": result["score"],
-                    "start": result.get("start", -1),
-                    "end": result.get("end", -1),
-                    "found": False
-                }
-            
-            return {
-                "answer": result["answer"],
-                "confidence": result["score"],
-                "start": result.get("start", 0),
-                "end": result.get("end", 0),
-                "found": True
-            }
-            
-        except Exception as e:
-            logger.error(f"Error in document QA: {e}")
+        logger.info(f"Running document QA pipeline with question: {question}")
+        result = self.pipe(query)[0]
+        logger.info(f"Raw result: {result}")
+        
+        # Save the result if debugging
+        if debug:
+            result_path = os.path.join(debug_output_dir, "debug_qa_result.json")
+            with open(result_path, 'w') as f:
+                # Convert any non-serializable data
+                serializable_result = {k: str(v) if not isinstance(v, (str, int, float, bool, list, dict, type(None))) else v 
+                                    for k, v in result.items()}
+                json.dump(serializable_result, f, indent=2)
+        
+        # Check confidence against threshold
+        if result["score"] < min_confidence:
+            logger.info(f"Answer confidence {result['score']:.4f} below threshold {min_confidence}")
             return {
                 "answer": "",
-                "confidence": 0.0,
-                "error": str(e),
+                "confidence": result["score"],
+                "start": result.get("start", -1),
+                "end": result.get("end", -1),
                 "found": False
             }
+        
+        return {
+            "answer": result["answer"],
+            "confidence": result["score"],
+            "start": result.get("start", 0),
+            "end": result.get("end", 0),
+            "found": True
+        }
+        
     
     def ask_pdf_page(self, page, question: str, min_confidence: float = 0.1, debug: bool = False) -> Dict[str, Any]:
         """

natural_pdf/selectors/parser.py

@@ -162,8 +162,12 @@ def selector_to_filter_func(selector: Dict[str, Any], **kwargs) -> callable:
                     return False
                     
                 # If 'type' attribute specified, it will be checked in the attributes section
-            # Otherwise, require exact match
-            elif element.type != selector['type']:
+            # Check for Docling-specific types (section-header, etc.)
+            elif hasattr(element, 'normalized_type') and element.normalized_type == selector['type']:
+                # This is a direct match with a Docling region type
+                pass
+            # Otherwise, require exact match with the element's type attribute
+            elif not hasattr(element, 'type') or element.type != selector['type']:
                 return False
         
         # Check attributes

{natural_pdf-25.3.16.2.dist-info → natural_pdf-25.3.17.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: natural-pdf
-Version: 25.3.16.2
+Version: 25.3.17.2
 Summary: A more intuitive interface for working with PDFs
 Home-page: https://github.com/jsoma/natural-pdf
 Author: Jonathan Soma
@@ -60,7 +60,7 @@ A friendly library for working with PDFs, built on top of [pdfplumber](https://g
 Natural PDF lets you find and extract content from PDFs using simple code that makes sense.
 
 - [Complete documentation here](https://jsoma.github.io/natural-pdf)
-- [Live demo here](https://colab.research.google.com/github/jsoma/)
+- [Live demo here](https://colab.research.google.com/github/jsoma/natural-pdf/blob/main/notebooks/Examples.ipynb)
 
 ## Features
 
@@ -268,6 +268,23 @@ Logs follow a hierarchical structure matching the library's module organization:
 - `natural_pdf.analyzers` - Layout analysis operations
 - `natural_pdf.ocr` - OCR engine operations
 
+## Document QA
+
+Ask questions directly to your documents:
+
+```python
+# Ask questions about the document content
+result = pdf.ask("What was the company's revenue in 2022?")
+print(f"Answer: {result['answer']}")
+print(f"Confidence: {result['confidence']:.2f}")
+
+# Access more details in the result dictionary
+result = pdf.ask("Who is the CEO?")
+print(f"Answer: {result['answer']}")
+print(f"Found on page: {result['page_num']}")
+print(f"Source text: {result.get('source_text', 'N/A')}")
+```
+
 ## More details
 
 [Complete documentation here](https://jsoma.github.io/natural-pdf)

{natural_pdf-25.3.16.2.dist-info → natural_pdf-25.3.17.2.dist-info}/RECORD

@@ -10,7 +10,11 @@ examples/color_test.py,sha256=owJ64qH5j5WgVhb7Nl2F-v89ilr1mQNwFm1xphvNnX4,2320
 examples/debug_ocr.py,sha256=oHTHWyamz2B9Est1uuYaC1W4Acubh7YNQcb_4eTMZPw,2521
 examples/direct_ocr_test.py,sha256=eO151awEYv24qKToj1704G4gq0SLgnx9bDXJgMHln64,5661
 examples/direct_paddle_test.py,sha256=awoHkR0WLpDEzcOD_HtxhXoBe9FmVBjzzBwtN4HcbVE,3335
-examples/direct_qa_example.py,sha256=0XxN1I617Tu9fPWoBFFwtyF9oA2Rlhw8HexHzomwJms,5709
+examples/direct_qa_example.py,sha256=bT79h491kVg3SAtK5jBSX6n1GPSW9egPbHfF9HpRr4g,2311
+examples/docling_comprehensive_test.py,sha256=0SxnIuvjVCzBRdbWIVMBT8P9lfBFam9SzvNWc2MmoIE,11129
+examples/docling_example.py,sha256=BUZFaA2aUpY7v-bF5AQCKL_iq8DZipeAgyXtwx_khc4,6582
+examples/docling_hierarchy_example.py,sha256=Il5L-LNr8yale5fhB-x4HmDja1I7843wBygxmVtdHFQ,8032
+examples/docling_text_sources.py,sha256=mjgkvNZ66Js0hdeaQFOOcAMzusSlWQ0835ICKiRVeZ0,8212
 examples/document_layout_analysis.py,sha256=zpr2LroZrrTqoGeb0BWhexc3gwfBIPB6FeEL-VhKyqU,4928
 examples/document_qa_example.py,sha256=IKe7FKnKbdaDPwQ-1uwm3KJenxennzqigQJGiQBIL1g,7240
 examples/exclusion_count_debug.py,sha256=UKrWiFkV42iuXShMR1AlzZyCVJpl9IoalIRcfazbVm4,4990
@@ -30,6 +34,7 @@ examples/highlight_test.py,sha256=nlirCchUB6P3jV9shn55kVSABZd5YcVozx1R47c39Gk,58
 examples/highlighting_example.py,sha256=8WoXL92nef61e4IDAEqL2EMC_nH06dM09OTXG7EJZO0,4893
 examples/image_width_example.py,sha256=jq5Xekx9oWHzNFfVOGt_H9nIcdlM1xZGbNjRWzdq9Kc,3414
 examples/improved_api_example.py,sha256=R_y_mzZYLJR1WnsAblgIBVGNBPKesLBMvnNEwhlhGpQ,4807
+examples/improved_qa_example.py,sha256=kpai2QjnmgZ6AeP4DXnm_LrYf0TLXlA4u-dLIteA5rc,2406
 examples/layout_confidence_display_test.py,sha256=9Ywg5YYUb8yLICtkKWmnRuyHkFsnwC3e4kBfqvq2MSE,2605
 examples/layout_confidence_test.py,sha256=hDr0Fwrv6p1UZ1vfMRXT3oR_SOgwj5GkLw3pd3D_Qaw,3438
 examples/layout_coordinate_debug.py,sha256=H8qG7kAsdw1ZkmOTdcH9tU3WGgMdMGpFj8DDnNAXTO8,11405
@@ -74,26 +79,26 @@ examples/url_pdf_example.py,sha256=WjZMlKyIlcXhJNdSe9uMmWdTHixnRfeacnp64gQkNAo,1
 examples/very_basics.py,sha256=cNLnr1z701ri0LgE1cVM4gfMMND0C9UnvvWybnwum6g,418
 natural_pdf/__init__.py,sha256=kKHL7SWzk0_ydDDX12X5W3s9-vEKgVYOBubXzp_SCdM,1784
 natural_pdf/analyzers/__init__.py,sha256=XhxlbwiqbGpeIlS88c4P2t7-MLP98U3CcIr-3nGp488,188
-natural_pdf/analyzers/document_layout.py,sha256=VHZTiiEZByhYUBHqOqmNIgj59zhc3ZNKU5yVaZOa5Fw,31030
+natural_pdf/analyzers/document_layout.py,sha256=vAvHCXAykdJnar6GqwC2YH1N1APzEtKORUT6coib51w,43431
 natural_pdf/analyzers/text_structure.py,sha256=ZmUsBMNBENjEYcABHqwziDXIHyCVYdUaEyAW0Ohagzc,5208
 natural_pdf/core/__init__.py,sha256=GUuFtj2Apc9biAdUOlnL8leL3BQncEzubvpiAUaU3ss,37
-natural_pdf/core/page.py,sha256=1DqF6mvpFKqsmRnFFrByV6C-MqGJ2MWyOQIwWiCs8PA,106040
-natural_pdf/core/pdf.py,sha256=sGhn0OaadU74Ozoa9QA_HsAZikUKOncyCSME0mImdLo,25475
+natural_pdf/core/page.py,sha256=zkBApbTMjaND_bu65veZSwd53uVDOtstXEnU-hCmqlQ,108813
+natural_pdf/core/pdf.py,sha256=lqTY6tCS-ZN9A4_LJ0w39Sr1tvgjpGRu0W3RK_0BEXQ,24878
 natural_pdf/elements/__init__.py,sha256=6FGHZm2oONd8zErahMEawuB4AvJR5jOZPt4KtEwbj80,40
 natural_pdf/elements/base.py,sha256=QJmhk6sYDKErLGrQ5VYhloytuntufxiP6wTzGfZ__9w,22754
 natural_pdf/elements/collections.py,sha256=vFFeMS0XiBL3p9PyNmwXndKMlPhlwp8os3xKLveN_8k,31558
 natural_pdf/elements/line.py,sha256=GrlpcfwcjugUGlneSDLaGa4ojz98A0l16wknlzrBCe0,4056
 natural_pdf/elements/rect.py,sha256=dls9g-R213O78HvfAJMak3_eV14Zh654Zw7hqTTXxDQ,3949
-natural_pdf/elements/region.py,sha256=2xXw6DyFp_nCGiQm6nNT7JfFvi82963R8rheZrkWpC8,57986
+natural_pdf/elements/region.py,sha256=MNzZtawVlhrRBO1EQY6OOw1RLGZBLsDp-7Ujq0HD2Xk,64701
 natural_pdf/elements/text.py,sha256=OAuy0ozaemj6yjMwhXPsJ76VZtRPeJbmrFTzpDJA2_U,11017
 natural_pdf/ocr/__init__.py,sha256=m2_hQRNEQihg9yIx6tMkurKfAnsBU7jbREvZyR_c2fs,2206
 natural_pdf/ocr/easyocr_engine.py,sha256=wwAgOf6IrCETyTGppjaVN6d46VlYRgK9ehbpwCE0LVA,9392
 natural_pdf/ocr/engine.py,sha256=NuvZszyHRQoEGwJC7cNdR8UMumgaLADwWiwK0ey9sls,5679
 natural_pdf/ocr/paddleocr_engine.py,sha256=iPKxfZhOLO146rOekOhRRB8y2BqqVTqrm8pkDgkaJgI,9157
 natural_pdf/qa/__init__.py,sha256=kagdfqNMpTnyzjC2EFy_PBX5us38NnJL548ESSQVzfI,107
-natural_pdf/qa/document_qa.py,sha256=kZwI1YWqnbzQafeIFJeNvhvqSIwLuF-85rAmdO0P_sE,16225
+natural_pdf/qa/document_qa.py,sha256=x_AYE0kbs7_4n5NC7zWcxQpHFh0vxP3g3q-l_w4RgSU,15845
 natural_pdf/selectors/__init__.py,sha256=Jfk-JBZEpQ7V5FWVGuLJQLH-qOfqNLC2AdicncMhrmY,121
-natural_pdf/selectors/parser.py,sha256=ornrWpc4m9ABxnoMkL3mkZ8BdL0fFRSrcE0wPDPeqC0,14209
+natural_pdf/selectors/parser.py,sha256=SFbiL0UdbX4VlA1bF26ahOq33fjXmBOUQEAGbqji65g,14536
 natural_pdf/templates/__init__.py,sha256=i7N8epDxZoDDsK4p2iUiMwzKVs97i_KtNk8ATArqlC4,19
 natural_pdf/templates/ocr_debug.html,sha256=Zy9StzBeHFQU8ity6cjFSZLe3TY0QOabUux4c5WQUzs,19171
 natural_pdf/utils/__init__.py,sha256=iAq5tqNSGcX5-t5CZkyyt6EFpAwH84spIXTCuJ46YMc,87
@@ -103,8 +108,8 @@ natural_pdf/utils/reading_order.py,sha256=1oihH9ZTqQvIVDYc2oVEYqIXyPzi94ERtelp6T
 natural_pdf/utils/visualization.py,sha256=Dujxp5xKbEap6UpoVEpArpkHChJLa_Je7FGz2S3Iwvw,5403
 tests/__init__.py,sha256=34RJiJqy8uDxasGCbzXIaJlHQklHprscPcA4xp2s97g,30
 tests/test_pdf.py,sha256=Ud-DI-GHAvnSJGMJewM_EwHtI_UgWTi7Gn9uIwQcpfE,1001
-natural_pdf-25.3.16.2.dist-info/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
-natural_pdf-25.3.16.2.dist-info/METADATA,sha256=3pd3i8n5ZtwJ2oGLSkJJJ61lXKaK93ALGuY9HvENhLg,8548
-natural_pdf-25.3.16.2.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
-natural_pdf-25.3.16.2.dist-info/top_level.txt,sha256=2AueS3xkctrmlcDA_te2-_WG0A0wGhS0UQNwnr_cbFQ,27
-natural_pdf-25.3.16.2.dist-info/RECORD,,
+natural_pdf-25.3.17.2.dist-info/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
+natural_pdf-25.3.17.2.dist-info/METADATA,sha256=YqtGq0o7CHwugehRetW1fvvZTH-6JC8mia7cRXamApk,9082
+natural_pdf-25.3.17.2.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+natural_pdf-25.3.17.2.dist-info/top_level.txt,sha256=2AueS3xkctrmlcDA_te2-_WG0A0wGhS0UQNwnr_cbFQ,27
+natural_pdf-25.3.17.2.dist-info/RECORD,,