natural-pdf 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

natural_pdf/analyzers/shape_detection_mixin.py

@@ -63,7 +63,7 @@ class ShapeDetectionMixin:
                 logger.debug(f"Shape detection on Region: {self}")
                 page_obj = self._page
                 pil_image = self.to_image(
-                    resolution=resolution, crop_only=True, include_highlights=False
+                    resolution=resolution, crop=True, include_highlights=False
                 )
                 if pil_image:  # Ensure pil_image is not None before accessing attributes
                     origin_offset_pdf = (self.x0, self.top)
@@ -681,7 +681,7 @@ class ShapeDetectionMixin:
         if hasattr(self, "to_image") and hasattr(self, "width") and hasattr(self, "height"):
             if hasattr(self, "x0") and hasattr(self, "top") and hasattr(self, "_page"):
                 pil_image_for_dims = self.to_image(
-                    resolution=resolution, crop_only=True, include_highlights=False
+                    resolution=resolution, crop=True, include_highlights=False
                 )
             else:
                 pil_image_for_dims = self.to_image(resolution=resolution, include_highlights=False)
@@ -1204,7 +1204,7 @@ class ShapeDetectionMixin:
         if hasattr(self, "to_image") and hasattr(self, "width") and hasattr(self, "height"):
             if hasattr(self, "x0") and hasattr(self, "top") and hasattr(self, "_page"):
                 pil_image_for_dims = self.to_image(
-                    resolution=resolution, crop_only=True, include_highlights=False
+                    resolution=resolution, crop=True, include_highlights=False
                 )
             else:
                 pil_image_for_dims = self.to_image(resolution=resolution, include_highlights=False)
@@ -1490,6 +1490,45 @@ class ShapeDetectionMixin:
 
         element_manager = page_object_for_elements._element_mgr
 
+        # ------------------------------------------------------------------
+        # CLEAN-UP existing table-related regions from earlier runs to avoid duplicates
+        # ------------------------------------------------------------------
+        try:
+            _purge_types = {"table", "table_row", "table_column", "table_cell"}
+
+            if (
+                hasattr(element_manager, "_elements")
+                and "regions" in element_manager._elements
+            ):
+                _orig_len = len(element_manager._elements["regions"])
+                element_manager._elements["regions"] = [
+                    r
+                    for r in element_manager._elements["regions"]
+                    if not (
+                        getattr(r, "source", None) == source_label
+                        and getattr(r, "region_type", None) in _purge_types
+                    )
+                ]
+                _removed = _orig_len - len(element_manager._elements["regions"])
+                if _removed:
+                    logger.info(
+                        f"Removed {_removed} previous table-related regions (source='{source_label}') before regeneration."
+                    )
+
+            if hasattr(page_object_for_elements, "_regions") and "detected" in page_object_for_elements._regions:
+                page_object_for_elements._regions["detected"] = [
+                    r
+                    for r in page_object_for_elements._regions["detected"]
+                    if not (
+                        getattr(r, "source", None) == source_label
+                        and getattr(r, "region_type", None) in _purge_types
+                    )
+                ]
+        except Exception as _cleanup_err:
+            logger.warning(
+                f"Table-region cleanup failed: {_cleanup_err}", exc_info=True
+            )
+
         # Get lines with the specified source
         all_lines = element_manager.lines  # Access lines from the correct element manager
         filtered_lines = [
@@ -1724,6 +1763,7 @@ class ShapeDetectionMixin:
         logger.info(
             f"Created {tables_created} table, {rows_created} rows, {cols_created} columns, and {cells_created} table cells from detected lines (source: '{source_label}') for {self}."
         )
+
         return self
 
 

natural_pdf/classification/manager.py

@@ -90,7 +90,7 @@ class ClassificationManager:
         if not _check_classification_dependencies():
             raise ImportError(
                 "Classification dependencies missing. "
-                'Install with: pip install "natural-pdf[core-ml]"'
+                'Install with: pip install "natural-pdf[ai]"'
             )
 
         self.pipelines: Dict[Tuple[str, str], "Pipeline"] = (

natural_pdf/classification/mixin.py

@@ -2,6 +2,7 @@ import logging
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Union
 
 from PIL import Image
+import warnings
 
 from .results import ClassificationResult
 
@@ -74,32 +75,52 @@ class ClassificationMixin:
         try:
             manager = self._get_classification_manager()
 
-            # Determine the effective model ID and engine type
+            # ------------------------------------------------------------
+            # Resolve engine ('text' vs 'vision')
+            # ------------------------------------------------------------
+            engine: Optional[str] = using  # rename for clarity
+
+            content = None  # will hold final content
+
+            if engine is None:
+                # Try text first
+                try:
+                    tentative_text = self._get_classification_content("text", **kwargs)
+                    if tentative_text and not (isinstance(tentative_text, str) and tentative_text.isspace()):
+                        engine = "text"
+                        content = tentative_text
+                    else:
+                        raise ValueError("Empty text")
+                except Exception:
+                    warnings.warn(
+                        "No text found for classification; falling back to vision model. "
+                        "Pass using='vision' explicitly to silence this message.",
+                        UserWarning,
+                    )
+                    engine = "vision"
+
+            # If engine determined but content not yet retrieved, get it now
+            if content is None:
+                content = self._get_classification_content(model_type=engine, **kwargs)
+
+            # ------------------------------------------------------------
+            # Determine model ID default based on engine
+            # ------------------------------------------------------------
             effective_model_id = model
-            inferred_using = manager.infer_using(
-                model if model else manager.DEFAULT_TEXT_MODEL, using
-            )
-
-            # If model was not provided, use the manager's default for the inferred engine type
             if effective_model_id is None:
                 effective_model_id = (
-                    manager.DEFAULT_TEXT_MODEL
-                    if inferred_using == "text"
-                    else manager.DEFAULT_VISION_MODEL
+                    manager.DEFAULT_TEXT_MODEL if engine == "text" else manager.DEFAULT_VISION_MODEL
                 )
                 logger.debug(
-                    f"No model provided, using default for mode '{inferred_using}': '{effective_model_id}'"
+                    f"No model provided, using default for mode '{engine}': '{effective_model_id}'"
                 )
 
-            # Get content based on the *final* determined engine type
-            content = self._get_classification_content(model_type=inferred_using, **kwargs)
-
             # Manager now returns a ClassificationResult object
             result_obj: ClassificationResult = manager.classify_item(
                 item_content=content,
                 labels=labels,
                 model_id=effective_model_id,
-                using=inferred_using,
+                using=engine,
                 min_confidence=min_confidence,
                 multi_label=multi_label,
                 **kwargs,

natural_pdf/classification/results.py

@@ -3,6 +3,7 @@ import logging
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Dict, List, Optional
+from collections.abc import Mapping
 
 logger = logging.getLogger(__name__)
 
@@ -20,7 +21,7 @@ class CategoryScore:
 
 
 @dataclass
-class ClassificationResult:
+class ClassificationResult(Mapping):
     """Results from a classification operation."""
 
     category: Optional[str]  # Can be None if scores are empty
@@ -86,3 +87,17 @@ class ClassificationResult:
 
     def __repr__(self) -> str:
         return f"<ClassificationResult category='{self.category}' score={self.score:.3f} model='{self.model_id}'>"
+
+    def __iter__(self):
+        """Iterate over mapping keys (linked to ``to_dict`` so it stays in sync)."""
+        return iter(self.to_dict())
+
+    def __getitem__(self, key):
+        """Dictionary-style access to attributes."""
+        try:
+            return self.to_dict()[key]
+        except KeyError as exc:
+            raise KeyError(key) from exc
+
+    def __len__(self):
+        return len(self.to_dict())

natural_pdf/cli.py

@@ -21,6 +21,7 @@ INSTALL_RECIPES: Dict[str, list[str]] = {
     "deskew": [f"{__package__.split('.')[0]}[deskew]"],
     "search": [f"{__package__.split('.')[0]}[search]"],
     "easyocr": ["easyocr"],
+    "ai": [f"{__package__.split('.')[0]}[ai]"],
 }
 
 

natural_pdf/core/highlighting_service.py

@@ -727,6 +727,7 @@ class HighlightingService:
         legend_position: str = "right",
         render_ocr: bool = False,
         resolution: Optional[float] = None,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
         **kwargs,
     ) -> Optional[Image.Image]:
         """
@@ -741,6 +742,9 @@ class HighlightingService:
             legend_position: Position of the legend.
             render_ocr: Whether to render OCR text.
             resolution: Resolution for base page image rendering if width/height not used.
+            crop_bbox: Optional bounding box (x0, top, x1, bottom) in PDF coordinate
+                space to crop the output image to, before legends or other overlays are
+                applied. If None, no cropping is performed.
             **kwargs: Additional args for pdfplumber's to_image (e.g., width, height).
 
         Returns:
@@ -855,6 +859,25 @@ class HighlightingService:
             )
             rendered_image = renderer.render()
 
+            # --- Optional Cropping BEFORE legend addition ---
+            if crop_bbox is not None:
+                cb_x0, cb_top, cb_x1, cb_bottom = crop_bbox
+                # Convert to pixel coordinates using actual scales
+                left_px = int(cb_x0 * actual_scale_x) - 1
+                top_px = int(cb_top * actual_scale_y) - 1
+                right_px = int(cb_x1 * actual_scale_x) + 1
+                bottom_px = int(cb_bottom * actual_scale_y) + 1
+
+                # Safeguard coordinates within bounds
+                left_px = max(0, min(left_px, rendered_image.width - 1))
+                top_px = max(0, min(top_px, rendered_image.height - 1))
+                right_px = max(left_px + 1, min(right_px, rendered_image.width))
+                bottom_px = max(top_px + 1, min(bottom_px, rendered_image.height))
+
+                rendered_image = rendered_image.crop(
+                    (left_px, top_px, right_px, bottom_px)
+                )
+
             legend = None
             if labels:
                 preview_labels = {h.label: h.color for h in preview_highlights if h.label}

natural_pdf/core/page.py

@@ -2235,12 +2235,12 @@ class Page(ClassificationMixin, ExtractionMixin, ShapeDetectionMixin, DescribeMi
 
     def ask(
         self,
-        question: str,
+        question: Union[str, List[str], Tuple[str, ...]],
         min_confidence: float = 0.1,
         model: str = None,
         debug: bool = False,
         **kwargs,
-    ) -> Dict[str, Any]:
+    ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
         """
         Ask a question about the page content using document QA.
         """
@@ -2808,3 +2808,33 @@ class Page(ClassificationMixin, ExtractionMixin, ShapeDetectionMixin, DescribeMi
             return None
 
     # --- End Skew Detection and Correction --- #
+
+    # ------------------------------------------------------------------
+    # Unified analysis storage (maps to metadata["analysis"])
+    # ------------------------------------------------------------------
+
+    @property
+    def analyses(self) -> Dict[str, Any]:
+        if not hasattr(self, "metadata") or self.metadata is None:
+            self.metadata = {}
+        return self.metadata.setdefault("analysis", {})
+
+    @analyses.setter
+    def analyses(self, value: Dict[str, Any]):
+        if not hasattr(self, "metadata") or self.metadata is None:
+            self.metadata = {}
+        self.metadata["analysis"] = value
+
+    def inspect(self, limit: int = 30) -> "InspectionSummary":
+        """
+        Inspect all elements on this page with detailed tabular view.
+        Equivalent to page.find_all('*').inspect().
+
+        Args:
+            limit: Maximum elements per type to show (default: 30)
+
+        Returns:
+            InspectionSummary with element tables showing coordinates,
+            properties, and other details for each element
+        """
+        return self.find_all('*').inspect(limit=limit)

natural_pdf/core/pdf.py

@@ -263,7 +263,7 @@ class PDF(ExtractionMixin, ExportMixin, ClassificationMixin):
 
         self._initialize_managers()
         self._initialize_highlighter()
-        self.analyses: Dict[str, Any] = {}
+        # Analysis results accessed via self.analyses property (see below)
 
         # --- Automatic cleanup when object is garbage-collected ---
         self._finalizer = weakref.finalize(
@@ -1490,7 +1490,7 @@ class PDF(ExtractionMixin, ExportMixin, ClassificationMixin):
             if not is_classification_available():
                 raise ImportError(
                     "Classification dependencies missing. "
-                    'Install with: pip install "natural-pdf[core-ml]"'
+                    'Install with: pip install "natural-pdf[ai]"'
                 )
             raise ClassificationError("ClassificationManager not available.")
 
@@ -1802,6 +1802,26 @@ class PDF(ExtractionMixin, ExportMixin, ClassificationMixin):
 
     # --- End Classification Mixin Implementation ---
 
+    # ------------------------------------------------------------------
+    # Unified analysis storage (maps to metadata["analysis"])
+    # ------------------------------------------------------------------
+
+    @property
+    def analyses(self) -> Dict[str, Any]:
+        if not hasattr(self, "metadata") or self.metadata is None:
+            # For PDF, metadata property returns self._pdf.metadata which may be None
+            self._pdf.metadata = self._pdf.metadata or {}
+        if self.metadata is None:
+            # Fallback safeguard
+            self._pdf.metadata = {}
+        return self.metadata.setdefault("analysis", {})  # type: ignore[attr-defined]
+
+    @analyses.setter
+    def analyses(self, value: Dict[str, Any]):
+        if not hasattr(self, "metadata") or self.metadata is None:
+            self._pdf.metadata = self._pdf.metadata or {}
+        self.metadata["analysis"] = value  # type: ignore[attr-defined]
+
     # Static helper for weakref.finalize to avoid capturing 'self'
     @staticmethod
     def _finalize_cleanup(plumber_pdf, temp_file_obj, is_stream):
@@ -1816,5 +1836,5 @@ class PDF(ExtractionMixin, ExportMixin, ClassificationMixin):
                 path = temp_file_obj.name if hasattr(temp_file_obj, "name") else None
                 if path and os.path.exists(path):
                     os.unlink(path)
-            except Exception:
-                pass
+            except Exception as e:
+                logger.warning(f"Failed to clean up temporary file '{path}': {e}")

natural_pdf/describe/base.py

@@ -269,7 +269,7 @@ def _get_columns_for_type(element_type: str, show_page_column: bool) -> List[str
     base_columns = ['x0', 'top', 'x1', 'bottom']
     
     if element_type == 'word':
-        columns = ['text'] + base_columns + ['font_family', 'size', 'bold', 'italic', 'source', 'confidence']
+        columns = ['text'] + base_columns + ['font_family', 'font_variant', 'size', 'bold', 'italic', 'source', 'confidence']
         # Add color for text elements
         columns.append('color')
     elif element_type == 'rect':
@@ -315,6 +315,16 @@ def _extract_element_value(element: "Element", column: str) -> Any:
             # Fallback to fontname
             return getattr(element, 'fontname', '')
         
+        elif column == 'font_variant':
+            variant = getattr(element, 'font_variant', None)
+            if variant:
+                return variant
+            # Fallback – try to derive from fontname if property missing
+            fontname = getattr(element, 'fontname', '')
+            if "+" in fontname:
+                return fontname.split("+", 1)[0]
+            return ''
+        
         elif column in ['bold', 'italic']:
             value = getattr(element, column, False)
             return value if isinstance(value, bool) else False

natural_pdf/describe/summary.py

@@ -128,6 +128,32 @@ class ElementSummary:
             ""
         ]
 
+    # Added for better VS Code and other frontends support
+    def _repr_html_(self) -> str:  # type: ignore
+        """Return HTML representation so rich rendering works in more frontends.
+
+        Many notebook frontends (including VS Code) give priority to the
+        ``_repr_html_`` method over Markdown. When available, we convert the
+        generated Markdown to HTML using the *markdown* library. If the
+        library is not installed we simply wrap the Markdown in a ``<pre>``
+        block so that at least the plain-text representation is visible.
+        """
+        md_source = self._to_markdown()
+        try:
+            import markdown as _markdown  # pylint: disable=import-error
+
+            # Convert markdown to HTML. We explicitly enable tables so the
+            # element and inspection summaries render nicely.
+            return _markdown.markdown(md_source, extensions=["tables"])
+        except Exception:  # noqa: BLE001, broad-except
+            # Fallback: present the Markdown as-is inside a <pre> block.
+            escaped = (
+                md_source.replace("&", "&amp;")
+                .replace("<", "&lt;")
+                .replace(">", "&gt;")
+            )
+            return f"<pre>{escaped}</pre>"
+
 
 class InspectionSummary(ElementSummary):
     """

natural_pdf/elements/base.py

@@ -9,11 +9,13 @@ from PIL import Image
 # Import selector parsing functions
 from natural_pdf.selectors.parser import parse_selector, selector_to_filter_func
 from natural_pdf.describe.mixin import DescribeMixin
+from natural_pdf.classification.mixin import ClassificationMixin
 
 if TYPE_CHECKING:
     from natural_pdf.core.page import Page
     from natural_pdf.elements.collections import ElementCollection
     from natural_pdf.elements.region import Region
+    from natural_pdf.classification.manager import ClassificationManager  # noqa: F401
 
 
 def extract_bbox(obj: Any) -> Optional[Tuple[float, float, float, float]]:
@@ -172,8 +174,8 @@ class DirectionalMixin:
                 # Adjust cross boundaries if cross_size is 'element'
                 if cross_size == "element":
                     if is_horizontal:  # Adjust y0, y1
-                        y0 = min(y0, self.y0)
-                        y1 = max(y1, self.y1)
+                        y0 = min(y0, self.top)
+                        y1 = max(y1, self.bottom)
                     else:  # Adjust x0, x1
                         x0 = min(x0, self.x0)
                         x1 = max(x1, self.x1)
@@ -413,7 +415,7 @@ class DirectionalMixin:
         return new_region
 
 
-class Element(DirectionalMixin, DescribeMixin):
+class Element(DirectionalMixin, ClassificationMixin, DescribeMixin):
     """
     Base class for all PDF elements.
 
@@ -432,6 +434,10 @@ class Element(DirectionalMixin, DescribeMixin):
         self._obj = obj
         self._page = page
 
+        # Containers for per-element metadata and analysis results (e.g., classification)
+        self.metadata: Dict[str, Any] = {}
+        # Access analysis results via self.analyses property (see below)
+
     @property
     def type(self) -> str:
         """Element type."""
@@ -850,6 +856,7 @@ class Element(DirectionalMixin, DescribeMixin):
         color: Optional[Union[Tuple, str]] = "red",  # Default color for single element
         label: Optional[str] = None,
         width: Optional[int] = None,  # Add width parameter
+        crop: bool = False,  # NEW: Crop to element bounds before legend
     ) -> Optional["Image.Image"]:
         """
         Show the page with only this element highlighted temporarily.
@@ -861,6 +868,8 @@ class Element(DirectionalMixin, DescribeMixin):
             color: Color to highlight this element (default: red)
             label: Optional label for this element in the legend
             width: Optional width for the output image in pixels
+            crop: If True, crop the rendered image to this element's
+                        bounding box before legends/overlays are added.
 
         Returns:
             PIL Image of the page with only this element highlighted, or None if error.
@@ -887,6 +896,9 @@ class Element(DirectionalMixin, DescribeMixin):
             "use_color_cycling": False,  # Explicitly false for single preview
         }
 
+        # Determine crop bbox
+        crop_bbox = self.bbox if crop else None
+
         # Check if we actually got geometry data
         if temp_highlight_data["bbox"] is None and temp_highlight_data["polygon"] is None:
             logger.warning(f"Cannot show element, failed to get bbox or polygon: {self}")
@@ -901,6 +913,7 @@ class Element(DirectionalMixin, DescribeMixin):
                 width=width,  # Pass the width parameter
                 labels=labels,
                 legend_position=legend_position,
+                crop_bbox=crop_bbox,
             )
         except Exception as e:
             logger.error(f"Error calling render_preview for element {self}: {e}", exc_info=True)
@@ -1070,3 +1083,68 @@ class Element(DirectionalMixin, DescribeMixin):
             case=case,
             **kwargs,
         )
+
+    # ------------------------------------------------------------------
+    # ClassificationMixin requirements
+    # ------------------------------------------------------------------
+
+    def _get_classification_manager(self) -> "ClassificationManager":
+        """Access the shared ClassificationManager via the parent PDF."""
+        if (
+            not hasattr(self, "page")
+            or not hasattr(self.page, "pdf")
+            or not hasattr(self.page.pdf, "get_manager")
+        ):
+            raise AttributeError(
+                "ClassificationManager cannot be accessed: Parent Page, PDF, or get_manager method missing."
+            )
+
+        return self.page.pdf.get_manager("classification")
+
+    def _get_classification_content(self, model_type: str, **kwargs):  # type: ignore[override]
+        """Return either text or an image, depending on model_type (text|vision)."""
+        if model_type == "text":
+            text_content = self.extract_text(layout=False)  # type: ignore[arg-type]
+            if not text_content or text_content.isspace():
+                raise ValueError(
+                    "Cannot classify element with 'text' model: No text content found."
+                )
+            return text_content
+
+        elif model_type == "vision":
+            # Delegate to Region implementation via a temporary expand()
+            resolution = kwargs.get("resolution", 150)
+            from natural_pdf.elements.region import Region  # Local import to avoid cycles
+
+            return self.expand().to_image(
+                resolution=resolution,
+                include_highlights=False,
+                crop=True,
+            )
+        else:
+            raise ValueError(f"Unsupported model_type for classification: {model_type}")
+
+    # ------------------------------------------------------------------
+    # Lightweight to_image proxy (vision models, previews, etc.)
+    # ------------------------------------------------------------------
+
+    def to_image(self, *args, **kwargs):  # type: ignore[override]
+        """Generate an image of this element by delegating to a temporary Region."""
+        return self.expand().to_image(*args, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Unified analysis storage (maps to metadata["analysis"])
+    # ------------------------------------------------------------------
+
+    @property
+    def analyses(self) -> Dict[str, Any]:
+        """Dictionary holding model-generated analysis objects (classification, extraction, …)."""
+        if not hasattr(self, "metadata") or self.metadata is None:
+            self.metadata = {}
+        return self.metadata.setdefault("analysis", {})
+
+    @analyses.setter
+    def analyses(self, value: Dict[str, Any]):
+        if not hasattr(self, "metadata") or self.metadata is None:
+            self.metadata = {}
+        self.metadata["analysis"] = value