natural-pdf 0.1.28__py3-none-any.whl → 0.1.31__py3-none-any.whl

optimization/test_memory_fix.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Test script to verify character duplication fix works correctly.
+
+This test verifies that:
+1. Memory usage is reduced by eliminating character duplication
+2. All existing functionality still works correctly
+3. Character access through words remains functional
+"""
+
+import gc
+import os
+import psutil
+import sys
+from pathlib import Path
+import pytest
+
+import natural_pdf as npdf
+
+
+def get_memory_usage():
+    """Get current memory usage in MB"""
+    process = psutil.Process()
+    return process.memory_info().rss / 1024 / 1024
+
+
+class TestCharacterMemoryFix:
+    """Test suite for character memory optimization"""
+    
+    @pytest.fixture
+    def test_pdf_path(self):
+        """Get path to a test PDF"""
+        # Use the practice PDF for testing
+        test_path = Path("pdfs/01-practice.pdf")
+        if not test_path.exists():
+            pytest.skip("Test PDF not found")
+        return str(test_path)
+    
+    def test_character_access_still_works(self, test_pdf_path):
+        """Test that character access through words still works after optimization"""
+        pdf = npdf.PDF(test_pdf_path)
+        page = pdf.pages[0]
+        
+        # Force loading of elements  
+        text_elements = page.find_all("text")
+        
+        # Test that we have text elements
+        assert len(text_elements) > 0, "Should have text elements"
+        print(f"Found {len(text_elements)} text elements")
+        
+        # Test that words can access their constituent characters  
+        for word in text_elements[:5]:  # Test first 5 words
+            if hasattr(word, '_char_indices') and word._char_indices:
+                # New optimized approach
+                constituent_chars = word.chars
+                assert isinstance(constituent_chars, list), "word.chars should return a list"
+                assert len(constituent_chars) > 0, "Should have constituent characters"
+                
+                # Test character properties
+                for char in constituent_chars[:3]:  # Test first 3 chars of each word
+                    assert hasattr(char, 'text'), "Character should have text attribute"
+                    assert hasattr(char, 'x0'), "Character should have x0 coordinate"
+                
+            elif hasattr(word, '_char_dicts') and word._char_dicts:
+                # Old approach - should still work for compatibility
+                char_dicts = word._char_dicts
+                assert isinstance(char_dicts, list), "word._char_dicts should be a list"
+                assert len(char_dicts) > 0, "Should have character dictionaries"
+    
+    def test_memory_usage_improvement(self, test_pdf_path):
+        """Test that memory usage is improved with the optimization"""
+        # This test will compare memory usage patterns
+        # Note: Exact numbers will vary, but we should see improvement
+        
+        pdf = npdf.PDF(test_pdf_path)
+        page = pdf.pages[0]
+        
+        # Measure memory before loading elements
+        gc.collect()
+        memory_before = get_memory_usage()
+        
+        # Load elements (this triggers the optimization)
+        chars = page.find_all("text")
+        words = page.find_all("words")
+        
+        # Measure memory after loading
+        gc.collect()
+        memory_after = get_memory_usage()
+        
+        memory_used = memory_after - memory_before
+        
+        # Log the memory usage for analysis
+        print(f"\nMemory usage analysis:")
+        print(f"Characters loaded: {len(chars)}")
+        print(f"Words loaded: {len(words)}")
+        print(f"Memory used: {memory_used:.2f} MB")
+        print(f"Memory per character: {memory_used / len(chars) * 1024:.2f} KB" if chars else "N/A")
+        
+        # The memory usage should be reasonable (not exact test due to variability)
+        # Main goal is to verify no crashes and reasonable memory usage
+        assert memory_used < 100, f"Memory usage seems too high: {memory_used:.2f} MB"
+    
+    def test_word_text_extraction_works(self, test_pdf_path):
+        """Test that text extraction from words still works correctly"""
+        pdf = npdf.PDF(test_pdf_path)
+        page = pdf.pages[0]
+        
+        words = page.find_all("text")  # All text elements are words in this PDF
+        
+        # Test text extraction from words
+        for word in words[:10]:  # Test first 10 words
+            word_text = word.text
+            assert isinstance(word_text, str), "Word text should be a string"
+            
+            # Text should not be empty for actual words
+            if word_text.strip():  # Skip empty/whitespace words
+                assert len(word_text) > 0, "Non-empty words should have text content"
+    
+    def test_backwards_compatibility(self, test_pdf_path):
+        """Test that existing code patterns still work"""
+        pdf = npdf.PDF(test_pdf_path)
+        page = pdf.pages[0]
+        
+        # Test that existing element access patterns work
+        all_elements = page.find_all("text")
+        assert len(all_elements) > 0, "Should find text elements"
+        
+        # Test that element properties are accessible
+        for element in all_elements[:5]:
+            assert hasattr(element, 'text'), "Element should have text attribute"
+            assert hasattr(element, 'x0'), "Element should have x0 coordinate"
+            assert hasattr(element, 'top'), "Element should have top coordinate"
+            assert hasattr(element, 'width'), "Element should have width"
+            assert hasattr(element, 'height'), "Element should have height"
+
+
+def main():
+    """Run the memory fix test"""
+    print("Running character memory optimization test...")
+    
+    # Check if test PDF exists
+    test_pdf = Path("pdfs/01-practice.pdf")
+    if not test_pdf.exists():
+        print(f"ERROR: Test PDF not found at {test_pdf}")
+        print("Please ensure the test PDF exists before running this test.")
+        return 1
+    
+    # Run pytest on just this file
+    exit_code = pytest.main([__file__, "-v", "-s"])
+    
+    if exit_code == 0:
+        print("\n✅ All memory optimization tests passed!")
+        print("The character duplication fix is working correctly.")
+    else:
+        print("\n❌ Some tests failed!")
+        print("The memory optimization needs investigation.")
+    
+    return exit_code
+
+
+if __name__ == "__main__":
+    exit(main())

tools/bad_pdf_eval/__init__.py

@@ -0,0 +1 @@
+ 

tools/bad_pdf_eval/analyser.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import re
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+import natural_pdf as npdf
+from PIL import Image
+from rich.table import Table
+from rich.console import Console
+
+from .utils import slugify
+from .reporter import save_json, log_section
+
+console = Console()
+
+
+class BadPDFAnalyzer:
+    """Run a battery of Natural-PDF probes on a PDF and dump artefacts."""
+
+    def __init__(
+        self,
+        pdf_path: Path,
+        output_dir: Path,
+        submission_meta: Dict[str, Any],
+        pages: List[int],
+        resolution: int = 216,
+    ):
+        self.pdf_path = pdf_path
+        self.output_dir = output_dir
+        self.meta = submission_meta
+        self.pages_to_analyze = pages
+        self.resolution = resolution
+
+    # ---------------------------------------------------------------------
+    # Helpers
+    # ---------------------------------------------------------------------
+    def _save_page_image(self, page, page_num: int) -> Path:
+        """Render and save page image as high-quality JPG."""
+        img: Image.Image = page.to_image(resolution=self.resolution)
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+        img_path = self.output_dir / f"page_{page_num:04d}.jpg"
+        img.save(img_path, "JPEG", quality=90, optimize=True, progressive=True)
+        return img_path
+
+    # ------------------------------------------------------------------
+    def run(self) -> Dict[str, Any]:
+        """Return master JSON summary (also persisted inside output_dir)."""
+        console.print(f"[green]Analyzing[/] {self.pdf_path.name}  ↦  pages {self.pages_to_analyze}")
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        pdf = npdf.PDF(str(self.pdf_path))
+        summary: Dict[str, Any] = {
+            "submission_id": self.meta["Submission ID"],
+            "pdf": str(self.pdf_path),
+            "total_pages": len(pdf.pages),
+            "pages": [],
+            "goal": self.meta.get("What are we trying to get out of the PDF?", ""),
+            "language": self.meta.get("What language(s) or script is the content in?", ""),
+            "issues": self.meta.get("What do you think makes this PDF bad?", ""),
+            "description": self.meta.get("What is the PDF, and/or where did it come from?", ""),
+        }
+
+        for page_idx_1based in self.pages_to_analyze:
+            if page_idx_1based < 1 or page_idx_1based > len(pdf.pages):
+                console.print(f"[yellow]- skipping page {page_idx_1based} (out of range)")
+                continue
+            page = pdf.pages[page_idx_1based - 1]
+            page_result: Dict[str, Any] = {"page_number": page_idx_1based}
+            difficulties: List[str] = []
+
+            # ---------------- image
+            img_path = self._save_page_image(page, page_idx_1based)
+            page_result["image"] = str(img_path)
+
+            # ---------------- describe / inspect
+            try:
+                descr = page.describe()
+                page_result["describe"] = str(descr)
+            except Exception as e:
+                page_result["describe_error"] = str(e)
+
+            try:
+                page_result["inspect"] = str(page.inspect(limit=30))
+            except Exception as e:
+                page_result["inspect_error"] = str(e)
+
+            # ---------------- extract text
+            text = ""
+            try:
+                text = page.extract_text()
+                page_result["text_len"] = len(text or "")
+                if text:
+                    page_result["text_preview"] = text[:300]
+            except Exception as e:
+                page_result["extract_text_error"] = str(e)
+
+            # ---------------- tiny font detection
+            try:
+                words_sample = page.words[:5000]  # not expensive
+                if words_sample:
+                    small_fonts = sum(1 for w in words_sample if getattr(w, "size", 10) < 4)
+                    ratio = small_fonts / len(words_sample)
+                    page_result["tiny_font_ratio"] = round(ratio, 3)
+                    if ratio >= 0.2:
+                        difficulties.append("tiny_font")
+            except Exception:
+                pass
+
+            # ---------------- extract table simple
+            try:
+                table_data = page.extract_table()
+                if table_data and table_data[0]:
+                    page_result["table_found"] = True
+                    page_result["table_dims"] = [len(table_data), len(table_data[0])]
+                else:
+                    page_result["table_found"] = False
+            except Exception as e:
+                page_result["table_error"] = str(e)
+
+            # ---------------- layout YOLO
+            try:
+                yolo_layout = page.analyze_layout()
+                page_result["layout_yolo_count"] = len(yolo_layout)
+                page_result["layout_yolo_regions"] = [
+                    {
+                        "type": getattr(r, "type", "unknown"),
+                        "bbox": [r.x0, r.top, r.x1, r.bottom],
+                        "confidence": getattr(r, "confidence", None),
+                    }
+                    for r in yolo_layout
+                ]
+            except Exception as e:
+                page_result["layout_yolo_error"] = str(e)
+
+            # ---------------- layout TATR for tables
+            try:
+                tatr_layout = page.analyze_layout("tatr", existing="append")
+                page_result["layout_tatr_count"] = len(tatr_layout)
+                page_result["layout_tatr_regions"] = [
+                    {
+                        "type": getattr(r, "type", "unknown"),
+                        "bbox": [r.x0, r.top, r.x1, r.bottom],
+                        "confidence": getattr(r, "confidence", None),
+                    }
+                    for r in tatr_layout
+                ]
+            except Exception as e:
+                page_result["layout_tatr_error"] = str(e)
+
+            # ---------------- color blob detection (rect fills / graphical anchors)
+            try:
+                blobs = page.detect_blobs()
+                page_result["blob_count"] = len(blobs)
+                page_result["blobs_sample"] = [
+                    {
+                        "color": getattr(b, "color", None),
+                        "bbox": [b.x0, b.top, b.x1, b.bottom],
+                    }
+                    for b in blobs[:20]
+                ]
+            except Exception as e:
+                page_result["blobs_error"] = str(e)
+
+            # ---------------- OCR pass (only if little native text)
+            ocr_elements = []
+            if page_result.get("text_len", 0) < 100:
+                start = time.time()
+                try:
+                    ocr_elements = page.extract_ocr_elements(engine="easyocr")
+                    page_result["ocr_text_elements"] = len(ocr_elements)
+                    page_result["ocr_runtime_sec"] = round(time.time() - start, 2)
+                    # Embed small OCR preview instead of separate file
+                    ocr_json = [
+                        {
+                            "text": el.text,
+                            "bbox": [el.x0, el.top, el.x1, el.bottom],
+                            "size": getattr(el, "size", None),
+                        }
+                        for el in ocr_elements[:500]
+                    ]
+                    page_result["ocr_sample"] = ocr_json[:30]
+                except Exception as e:
+                    page_result["ocr_error"] = str(e)
+            else:
+                page_result["ocr_text_elements"] = 0
+
+            # ---------------- tags – handle non-string entries (NaN etc.)
+            goal_raw = summary.get("goal", "")
+            # Convert to string to avoid attribute errors if the CSV cell is NaN/float
+            goal_str = str(goal_raw) if goal_raw is not None else ""
+            goal = goal_str.lower()
+
+            if "table" in goal:
+                page_result["goal_tag"] = "table_extraction"
+            elif any(word in goal for word in ["text", "content", "information"]):
+                page_result["goal_tag"] = "text_extraction"
+            else:
+                page_result["goal_tag"] = "unknown"
+
+            # Difficulties determination
+            if page_result.get("text_len", 0) < 100 and page_result.get("ocr_text_elements", 0) > 20:
+                difficulties.append("scanned_image")
+
+            page_result["difficulties"] = difficulties
+
+            # Suggested approach heuristic
+            approach = []
+            if "table" in goal:
+                if page_result.get("layout_tatr_count", 0) > 0:
+                    approach.append("Crop TATR regions → extract_table('tatr')")
+                else:
+                    approach.append("Anchor header text, .below(), extract_table(custom settings)")
+            if "text" in goal and "scanned_image" in difficulties:
+                approach.append("Apply OCR (paddle for non-Latin)")
+            if "tiny_font" in difficulties:
+                approach.append("Re-render at higher scale or adjust char_margin")
+            page_result["suggested_approach"] = "; ".join(approach)
+
+            # ---------------- code snippet suggestion
+            def _first_anchor_from_goal(g: str) -> str:
+                """Pick a plausible anchor token (capitalised word) from the free-form goal text."""
+                for tok in g.split():
+                    t = tok.strip().strip(".;:,()[]{}")
+                    if len(t) > 3 and t[0].isupper() and t.isalpha():
+                        return t
+                return "AnchorText"
+
+            import_lines = [
+                "from natural_pdf import PDF",
+            ]
+            if page_result["goal_tag"] == "table_extraction":
+                import_lines.append("import pandas as pd")
+
+            code_lines: List[str] = import_lines + [
+                f"pdf = PDF(\"{self.pdf_path}\")",
+                f"page = pdf.pages[{page_idx_1based - 1}]  # page {page_idx_1based}",
+            ]
+
+            thought_lines: List[str] = []
+            # build reasoning
+            thought_lines.append(f"Goal tag: {page_result['goal_tag']}. Detected difficulties: {', '.join(difficulties) or 'none'}.")
+
+            if page_result["goal_tag"] == "table_extraction":
+                thought_lines.append("Plan: rely on layout models to locate tables, then extract with Natural-PDF helper.")
+                if page_result.get("layout_tatr_count", 0) > 0:
+                    code_lines.append("page.analyze_layout('tatr')  # adds 'table' regions")
+                else:
+                    code_lines.append("page.analyze_layout()  # YOLO fallback")
+
+                if page_result.get("layout_tatr_count", 0) > 1:
+                    thought_lines.append("Multiple tables detected, choose second as goal mentions 'second table'.")
+                    code_lines.append("tables = page.find_all('table')")
+                    code_lines.append("tbl = tables[1]")
+                else:
+                    code_lines.append("tbl = page.find('table')  # first table")
+
+                code_lines.extend([
+                    "data = tbl.extract_table()",
+                    "columns, rows = data[0], data[1:]",
+                    "df = pd.DataFrame(rows, columns=columns)",
+                ])
+            elif page_result["goal_tag"] == "text_extraction":
+                anchor = _first_anchor_from_goal(goal_str)
+                if "scanned_image" in difficulties:
+                    thought_lines.append("No native text detected; need OCR before querying.")
+                    code_lines.append("page.apply_ocr(engine='paddle')")
+                thought_lines.append(f"Anchor on text '{anchor}' then read below region.")
+                code_lines.append(f"section = page.find(\"text:contains({anchor})\").below(0, 50)")
+                code_lines.append("text = section.extract_text()")
+            else:
+                thought_lines.append("Goal unclear; placeholder snippet provided.")
+                code_lines.append("# TODO: clarify extraction goal")
+
+            page_result["code_suggestion"] = "\n".join(code_lines)
+            page_result["thought_process"] = " ".join(thought_lines)
+
+            summary["pages"].append(page_result)
+
+            # Provide quick heuristic comment
+            if page_result.get("text_len", 0) == 0 and page_result.get("ocr_text_elements", 0) > 20:
+                page_result["auto_comment"] = "Likely scanned/needs OCR; no native text."
+            elif page_result.get("text_len", 0) > 1000 and page_result.get("layout_yolo_count", 0) == 0:
+                page_result["auto_comment"] = "Native dense text; YOLO found no regions – may be fine, fonts just small."
+            else:
+                page_result.setdefault("auto_comment", "")
+
+        # Save master summary
+        save_json(summary, self.output_dir / "summary.json")
+        return summary
+
+
+# -------------------------------------------------------------------------
+# Helper to parse specific pages mentioned in free text
+# -------------------------------------------------------------------------
+PAGE_REGEX = re.compile(r"page\s*(\d{1,4})", re.IGNORECASE)
+
+
+def extract_page_hints(text: str) -> List[int]:
+    return [int(m.group(1)) for m in PAGE_REGEX.finditer(text)] 

tools/bad_pdf_eval/collate_summaries.py

@@ -0,0 +1,130 @@
+import json
+from pathlib import Path
+from typing import List
+
+ROOT = Path(__file__).resolve().parent.parent.parent / "eval_results"
+
+
+def collect() -> List[dict]:
+    rows = []
+    for subdir in ROOT.iterdir():
+        if not subdir.is_dir():
+            continue
+        summary_path = subdir / "summary.json"
+        if not summary_path.exists():
+            continue
+        try:
+            data = json.loads(summary_path.read_text())
+        except Exception as e:
+            print(f"Failed to parse {summary_path}: {e}")
+            continue
+        submission_id = data.get("submission_id", subdir.name)
+        description = data.get("description", "")
+        language = data.get("language", "")
+        issues = data.get("issues", "")
+
+        # ---------------- document-level enrichment (added by llm_enrich.py) ----
+        doc_tp = (data.get("thought_process") or "").strip()
+        doc_cs = (data.get("code_suggestion") or "").strip()
+        doc_diff = data.get("difficult_elements", [])
+        doc_test = (data.get("test_case") or "").strip()
+
+        page_snippets = []
+        features = set()
+        for p in data.get("pages", [])[:5]:  # first 5 pages enough for summary
+            cs = (p.get("code_suggestion") or "").strip()
+            tp = (p.get("thought_process") or "").strip()
+            if not cs and not tp:
+                continue
+            page_snippets.append({
+                "page": p.get("page_number"),
+                "code": cs,
+                "thought": tp,
+            })
+            # --- lightweight feature tagging --------------------------------
+            gt = (p.get("goal_tag") or "").lower()
+            if "table" in gt:
+                features.add("table")
+            if "text" in gt:
+                features.add("text")
+            # look into region labels for structural hints
+            for reg in p.get("layout_tatr_regions", []) + p.get("layout_yolo_regions", []):
+                label = (reg.get("label") or reg.get("type") or "").lower()
+                if label == "table":
+                    features.add("table")
+                if label in {"figure", "isolate_formula"}:
+                    features.add("figure")
+            # parse difficulties hints in thought_process
+            difficulties = tp.lower()
+            if "scanned_image" in difficulties:
+                features.add("scanned_image")
+            if "tiny_font" in difficulties or "small font" in difficulties:
+                features.add("small_font")
+        # language-based feature
+        if language and language.lower() not in {"english", "en", "en-us"}:
+            features.add("non_english")
+
+        rows.append({
+            "id": submission_id,
+            "language": language,
+            "issues": issues,
+            "description": description,
+            "doc_thought": doc_tp,
+            "doc_code": doc_cs,
+            "doc_difficult": doc_diff,
+            "doc_test": doc_test,
+            "snippets": page_snippets,
+            "features": sorted(features),
+        })
+    return rows
+
+
+def export_markdown(rows: List[dict]):
+    lines = ["# Evaluation Summaries\n"]
+    for r in sorted(rows, key=lambda x: x["id"]):
+        lines.append(f"## {r['id']}")
+        if r["description"]:
+            lines.append(f"*Description*: {r['description']}")
+        if r["issues"]:
+            lines.append(f"*Issues*: {r['issues']}")
+        if r["language"]:
+            lines.append(f"*Language*: {r['language']}")
+        if r.get("features"):
+            lines.append(f"*Features*: {', '.join(r['features'])}")
+
+        # ---- document-level enrichment -----------------------------------
+        if r.get("doc_thought") or r.get("doc_code"):
+            lines.append("\n### Document-level enrichment")
+        if r.get("doc_thought"):
+            lines.append("**Doc thought process:**")
+            lines.append(f"```")
+            lines.append(r["doc_thought"])
+            lines.append(f"```")
+        if r.get("doc_code"):
+            lines.append("**Doc code suggestion:**")
+            lines.append(f"```python")
+            lines.append(r["doc_code"])
+            lines.append(f"```")
+        if r.get("doc_difficult"):
+            lines.append("*Difficult elements*: " + ", ".join(r["doc_difficult"]))
+        if r.get("doc_test"):
+            lines.append("*Suggested test*: " + r["doc_test"])
+
+        lines.append("")
+        for s in r["snippets"]:
+            lines.append(f"### Page {s['page']}")
+            if s["thought"]:
+                lines.append("**Thoughts**:")
+                lines.append(f"```\n{s['thought']}\n```")
+            if s["code"]:
+                lines.append("**Code suggestion**:")
+                lines.append(f"```python\n{s['code']}\n```")
+            lines.append("")
+        lines.append("\n---\n")
+    Path("eval_results/collated_summary.md").write_text("\n".join(lines))
+
+
+if __name__ == "__main__":
+    rows = collect()
+    export_markdown(rows)
+    print(f"Wrote {len(rows)} summaries to eval_results/collated_summary.md")