natural-pdf 0.1.0__py3-none-any.whl

natural_pdf-0.1.0.dist-info/METADATA

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: natural-pdf
+Version: 0.1.0
+Summary: A more intuitive interface for working with PDFs
+Author-email: Jonathan Soma <jonathan.soma@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jsoma/natural-pdf
+Project-URL: Repository, https://github.com/jsoma/natural-pdf
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber>=0.7.0
+Requires-Dist: Pillow>=8.0.0
+Requires-Dist: colour>=0.1.5
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: urllib3>=1.26.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchvision>=0.15.0
+Requires-Dist: transformers>=4.30.0
+Requires-Dist: huggingface_hub>=0.19.0
+Provides-Extra: interactive
+Requires-Dist: ipywidgets<9.0.0,>=7.0.0; extra == "interactive"
+Provides-Extra: easyocr
+Requires-Dist: easyocr; extra == "easyocr"
+Provides-Extra: paddle
+Requires-Dist: paddlepaddle; extra == "paddle"
+Requires-Dist: paddleocr; extra == "paddle"
+Provides-Extra: layout-yolo
+Requires-Dist: doclayout_yolo; extra == "layout-yolo"
+Provides-Extra: surya
+Requires-Dist: surya-ocr; extra == "surya"
+Provides-Extra: qa
+Provides-Extra: all
+Requires-Dist: ipywidgets<9.0.0,>=7.0.0; extra == "all"
+Requires-Dist: easyocr; extra == "all"
+Requires-Dist: paddlepaddle; extra == "all"
+Requires-Dist: paddleocr; extra == "all"
+Requires-Dist: doclayout_yolo; extra == "all"
+Requires-Dist: surya-ocr; extra == "all"
+Dynamic: license-file
+
+# Natural PDF
+
+A friendly library for working with PDFs, built on top of [pdfplumber](https://github.com/jsvine/pdfplumber).
+
+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/natural-pdf/blob/main/notebooks/Examples.ipynb)
+
+## Features
+
+- **Fluent API** for chaining operations
+- **CSS-like selectors** for finding elements
+- **Spatial navigation** with intuitive methods like `above()`, `below()`, and `select_until()`
+- **Element collections** for batch operations
+- **Visual highlighting** for debugging (persistent highlights)
+- **Interactive element viewer** for Jupyter environments (`.viewer()`)
+- **Region visualization** with direct image extraction of specific regions
+- **Text style analysis** for document structure
+- **Exclusion zones** for headers, footers, and other areas to ignore
+- **OCR integration** with multiple engines (EasyOCR, PaddleOCR, Surya)
+- **Document layout analysis** for detecting document structure with ML models
+- **Table extraction** with multiple detection methods
+- **Structured logging** with configurable levels and handlers
+
+## Installation
+
+```bash
+pip install natural-pdf
+```
+
+# Installs the core library along with required AI dependencies (PyTorch, Transformers)
+```bash
+# Install with support for specific OCR engines
+pip install natural-pdf[easyocr]   # EasyOCR engine
+pip install natural-pdf[paddle]    # PaddleOCR engine (requires paddlepaddle)
+pip install natural-pdf[surya]     # Surya OCR engine
+
+# Install with support for YOLO layout detection model
+pip install natural-pdf[layout_yolo]
+
+# Install with support for the interactive Jupyter widget
+pip install natural-pdf[interactive]
+
+# Install everything
+pip install natural-pdf[all]
+```
+
+## Quick Start
+
+```python
+from natural_pdf import PDF
+
+# Open a local PDF
+pdf = PDF('document.pdf')
+
+# Or open a PDF from a URL
+pdf = PDF('https://example.com/document.pdf')
+
+# Get the first page
+page = pdf.pages[0]
+
+# Find elements using CSS-like selectors
+heading = page.find('text:contains("Summary"):bold')
+
+# Extract content below the heading
+content = heading.below().extract_text()
+print(content)
+
+# Exclude headers and footers
+page.add_exclusion(page.find('text:contains("CONFIDENTIAL")').above())
+page.add_exclusion(page.find_all('line')[-1].below())
+
+# Extract clean text
+clean_text = page.extract_text()
+print(clean_text)
+```
+
+## Selectors
+
+The library supports CSS-like selectors for finding elements:
+
+```python
+# Find text containing a specific string
+element = page.find('text:contains("Revenue")')
+
+# Find bold text with a specific font size
+headings = page.find_all('text[size>=12]:bold')
+
+# Find thick red lines
+lines = page.find_all('line[width>=2][color~=(1,0,0)]')
+```
+
+## Spatial Navigation
+
+Navigate through the document with intuitive spatial methods:
+
+```python
+# Get content below a heading
+heading = page.find('text:contains("Introduction")')
+content = heading.below().extract_text()
+
+# Get content from one element to another
+start = page.find('text:contains("Start")')
+end = page.find('text:contains("End")')
+region = start.select_until(end)
+content = region.extract_text()
+```
+
+## Exclusion Zones
+
+Exclude headers, footers, or other areas from extraction:
+
+```python
+# Page-level exclusion
+page.add_exclusion(page.find('text:contains("Page")').above())
+page.add_exclusion(page.find_all('line')[-1].below())
+
+# PDF-level exclusion with lambdas
+pdf.add_exclusion(
+    lambda page: page.find('text:contains("Header")').above(),
+    label="headers"
+)
+
+# Extract text with exclusions applied
+text = pdf.extract_text()
+
+# Extract from a specific region with exclusions
+summary = page.find('text:contains("Summary")')
+conclusion = page.find('text:contains("Conclusion")')
+region = page.create_region(summary.x0, summary.top, conclusion.x1, conclusion.bottom)
+region_text = region.extract_text(apply_exclusions=True)  # Excludes headers/footers
+
+# Disable exclusions for a specific extraction
+full_text = page.extract_text(apply_exclusions=False)
+```
+
+Exclusions work efficiently with different region types:
+- Regions without intersection with exclusion zones → exclusions ignored entirely
+- Rectangular regions with header/footer exclusions → optimized cropping
+- Complex regions with partial exclusions → advanced filtering with warning
+
+## OCR Integration
+
+Extract text from scanned documents using OCR, with support for multiple engines (EasyOCR, PaddleOCR, Surya):
+
+```python
+# Apply OCR using a specific engine (e.g., PaddleOCR)
+ocr_elements = page.apply_ocr(engine='paddle', languages=['en', 'zh-cn'])
+
+# Extract text (will use previously applied OCR results if available)
+text = page.extract_text()
+
+# Configure advanced engine options using Options classes
+from natural_pdf.ocr import PaddleOCROptions
+paddle_opts = PaddleOCROptions(languages=['en'], use_angle_cls=False, rec_batch_num=8)
+ocr_elements = page.apply_ocr(engine='paddle', options=paddle_opts)
+
+# Force OCR regardless of existing text
+ocr_text = page.extract_text(ocr=True)
+
+# Find OCR-detected text with high confidence
+high_confidence = page.find_all('text[source=ocr][confidence>=0.8]')
+
+# Visualize OCR results with color-coded confidence levels
+for elem in page.find_all('text[source=ocr]'):
+    if elem.confidence >= 0.8:
+        color = (0, 1, 0, 0.3)  # Green for high confidence
+    elif elem.confidence >= 0.5:
+        color = (1, 1, 0, 0.3)  # Yellow for medium confidence
+    else:
+        color = (1, 0, 0, 0.3)  # Red for low confidence
+        
+    elem.highlight(color=color, label=f"OCR ({elem.confidence:.2f})")
+page.save_image('ocr_results.png', labels=True)
+```
+
+## Logging
+
+The library includes a structured logging system to provide visibility into its operations:
+
+```python
+import logging
+from natural_pdf import PDF, configure_logging
+
+# Configure logging with INFO level to console
+configure_logging(level=logging.INFO)
+
+# Or log to a file with DEBUG level
+file_handler = logging.FileHandler("natural_pdf.log")
+file_handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+configure_logging(level=logging.DEBUG, handler=file_handler)
+
+# Now operations will generate logs
+pdf = PDF("document.pdf")
+# Log: natural_pdf.core.pdf - INFO - Initializing PDF from document.pdf
+
+# Run layout detection with verbose logging
+regions = pdf.pages[0].analyze_layout(
+    model="paddle",
+    model_params={"verbose": True}
+)
+# Log: natural_pdf.analyzers.layout.paddle - INFO - Starting PaddleLayout detection...
+# Log: natural_pdf.analyzers.layout.paddle - DEBUG - Parameters: confidence=0.2...
+```
+
+Logs follow a hierarchical structure matching the library's module organization:
+- `natural_pdf.core` - Core PDF operations
+- `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)
+
+## Visual Debugging & Interactive Viewer
+
+Use highlighting to understand element selection and analysis results. Add persistent highlights using `.highlight()` and view them with the interactive `.viewer()` or static `.save_image()`. You can also generate temporary previews of selected elements using `ElementCollection.show()`.
+
+```python
+# Highlight selected elements persistently
+page.find_all('text:bold').highlight(label="Bold Text")
+
+# Launch the interactive widget in Jupyter (shows persistent highlights)
+# Requires: pip install natural-pdf[interactive]
+page.viewer()
+
+# Save a static image file with highlights and legend
+page.save_image("highlighted_page.png", labels=True)
+
+# Show a temporary preview image of specific elements, grouped by attribute
+preview_image = page.find_all('region[type*=table]').show(group_by='type')
+# In Jupyter, this image will display automatically
+preview_image
+```

natural_pdf-0.1.0.dist-info/RECORD

@@ -0,0 +1,52 @@
+natural_pdf/__init__.py,sha256=kKHL7SWzk0_ydDDX12X5W3s9-vEKgVYOBubXzp_SCdM,1784
+natural_pdf/analyzers/__init__.py,sha256=BkSmEqw5J76C2fvYHF86EXQJQWWFNIvjSwRMwfW-Ht0,140
+natural_pdf/analyzers/text_options.py,sha256=9IGRoem1O2mc1ZNGiM5-VPRZ3c8LLwEk1B3is9UxMoE,2777
+natural_pdf/analyzers/text_structure.py,sha256=e4G6v0bD7ZJCdo6DcuDD3iZt8KAwBfALMduwZHGh0wI,12415
+natural_pdf/analyzers/utils.py,sha256=u5_FAUPmEG1ydPVuxpu7bVw507NB3WzisMNSUhsnukY,2146
+natural_pdf/analyzers/layout/__init__.py,sha256=oq1uJ5UkGGMbBKGirV1aRKK3hxAUyjTLywYkPCQH1f0,33
+natural_pdf/analyzers/layout/base.py,sha256=D6KHDsbVKzZWCfW4vt0khPC3TA9JzQD3cF4VtTSyf28,6752
+natural_pdf/analyzers/layout/docling.py,sha256=iNeD10ZfolDVJNqayAUd0-Bs2tVr5INE7WK9c_Mll_8,11930
+natural_pdf/analyzers/layout/layout_analyzer.py,sha256=oQeqPDHL6vpj_3NHuzS5ja7KVAAL7PhQ7IOwustDBBo,8008
+natural_pdf/analyzers/layout/layout_manager.py,sha256=Qr5pxcv_Wk5IJRJr0IoYJJAz71RGJvQgqXONNBhNLOw,9221
+natural_pdf/analyzers/layout/layout_options.py,sha256=vZvTSg_M27OirZomcC5uWLSmPYXjvnnCEo5QKy9RjaQ,3503
+natural_pdf/analyzers/layout/paddle.py,sha256=QCasH_Z9UITX6wRGlE_HjmwkBuANz9Yyw5Yk7QvRVcw,12519
+natural_pdf/analyzers/layout/surya.py,sha256=hmPDfXzTkF2PQPgvg1xjTJSBKFuCmjZB3GTCHa-kpA4,6477
+natural_pdf/analyzers/layout/tatr.py,sha256=H0Xygk9jA46-vlPleoal94cuDyz-LHTSxVb3e6gpmV8,11956
+natural_pdf/analyzers/layout/yolo.py,sha256=NSQK3TcS1qN8D2MDxCvcwTpS_kvzGy3I2LepJDUceoQ,7699
+natural_pdf/core/__init__.py,sha256=GUuFtj2Apc9biAdUOlnL8leL3BQncEzubvpiAUaU3ss,37
+natural_pdf/core/element_manager.py,sha256=H1896JSt48ASLSmG22xEXMY-xSKcpYsUlYmYMD48i6Q,17117
+natural_pdf/core/highlighting_service.py,sha256=gcWZnvlscg32anJrh0m3gVgIyrRKTMDHIL5Ft8OOTjA,29454
+natural_pdf/core/page.py,sha256=rKXxdnG4cl8qjRoKEBxXL9ncLWvujDoVWQ9_D9ouHxc,64428
+natural_pdf/core/pdf.py,sha256=VAAe-BU8bcbCTiQ43fp8lsVy8q8KSfN9eAbFp9mJOWw,28296
+natural_pdf/elements/__init__.py,sha256=6FGHZm2oONd8zErahMEawuB4AvJR5jOZPt4KtEwbj80,40
+natural_pdf/elements/base.py,sha256=Bi6hylE1N252d-GSPZy1mFMvnWh18b9dEGbIRXthq88,32057
+natural_pdf/elements/collections.py,sha256=qkpUZuf08n-NPhCrOE40cRg-T2F5jpba1Xhuo2CKr-c,59982
+natural_pdf/elements/line.py,sha256=QvVdhf_K6rwJkq3q67JmgdZpDhrBgWuSMF-Q25malP4,4783
+natural_pdf/elements/rect.py,sha256=dls9g-R213O78HvfAJMak3_eV14Zh654Zw7hqTTXxDQ,3949
+natural_pdf/elements/region.py,sha256=GVenh3ICfojVpSpwKMEayUBBesywowPTTk7y44MLo6g,76835
+natural_pdf/elements/text.py,sha256=OAuy0ozaemj6yjMwhXPsJ76VZtRPeJbmrFTzpDJA2_U,11017
+natural_pdf/ocr/__init__.py,sha256=mbUUsCfeU6yRsEqNn3I4Len-XY6FfjfKhTAoWDLA1f4,1943
+natural_pdf/ocr/engine.py,sha256=xDnvhnm4Lr7d83ezglDqOtl9xfx74zOOTyYW-fZHQEQ,4183
+natural_pdf/ocr/engine_easyocr.py,sha256=6srZhXqlH3UpNWw5iFq7u4TS5HQsMSTWYuuWo3oYZp8,8273
+natural_pdf/ocr/engine_paddle.py,sha256=9nnG-0zyEH9fj_QRmxjX6OaxzfyKKmyW_SCs40edTWs,9065
+natural_pdf/ocr/engine_surya.py,sha256=gWV_BEuLMqmJcKVlag9i45SsO2uLAtI-dayBm1xbDQ0,7719
+natural_pdf/ocr/ocr_manager.py,sha256=mAyCntdAnrNv8TIvGYlGs40G2tDAdMQ_Jqb3owiPWW8,9934
+natural_pdf/ocr/ocr_options.py,sha256=A2CQV172id-90zMpPZWb8CD09ZP0BuQnnCZGEFP4SaQ,3787
+natural_pdf/qa/__init__.py,sha256=kagdfqNMpTnyzjC2EFy_PBX5us38NnJL548ESSQVzfI,107
+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=scYuM0Kp-Bidc2KaYwOMiMYSeR-6q970-2Xwy5zsdNE,13784
+natural_pdf/templates/__init__.py,sha256=i7N8epDxZoDDsK4p2iUiMwzKVs97i_KtNk8ATArqlC4,19
+natural_pdf/templates/ocr_debug.html,sha256=Zy9StzBeHFQU8ity6cjFSZLe3TY0QOabUux4c5WQUzs,19171
+natural_pdf/utils/__init__.py,sha256=s3M8FggaK1P3EBYn6R_-HgSDjNc9C73gyKe1hihtNWg,43
+natural_pdf/utils/highlighting.py,sha256=9H8vbWhwgxzjrL7MhAePXUWZZctLPboNocJzy-1TE_g,675
+natural_pdf/utils/reading_order.py,sha256=1oihH9ZTqQvIVDYc2oVEYqIXyPzi94ERtelp6TyzmWU,7594
+natural_pdf/utils/visualization.py,sha256=p2855QGyRXUFNH8rzgrIVzCSbuf8WXwV_j1YgP518uo,8876
+natural_pdf/widgets/__init__.py,sha256=qckw3DjdVTsASPLJ8uUrGKg3MFhvzHndUpeNGlqwg6A,215
+natural_pdf/widgets/viewer.py,sha256=h_amj_uvf-vRqEsFg4P00fgKxawLAd9jjC1ohUza4BY,37479
+natural_pdf/widgets/frontend/viewer.js,sha256=w8ywfz_IOAAv2nP_qaf2VBUkF1KhjT3zorhJxM1-CfU,4371
+natural_pdf-0.1.0.dist-info/licenses/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
+natural_pdf-0.1.0.dist-info/METADATA,sha256=_RZKF1mkrpUxpdOO0oMy_HGjj0ZlrvAGIblwmheKCQQ,9960
+natural_pdf-0.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+natural_pdf-0.1.0.dist-info/top_level.txt,sha256=XtfS3IiR1fTjaQG9TjGDjZsB1Ih2GXQteDbJ2dXlLvQ,12
+natural_pdf-0.1.0.dist-info/RECORD,,

natural_pdf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

natural_pdf-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2025 Jonathan Soma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

natural_pdf-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+natural_pdf