natural-pdf 0.1.4__tar.gz → 0.1.6__tar.gz

{natural_pdf-0.1.4 → natural_pdf-0.1.6}/.gitignore

@@ -1,4 +1,6 @@
 .notebook_cache.json
+.venv
+output
 Untitled.ipynb
 conversation.md
 docs/tutorials/pdfs
@@ -10,6 +12,9 @@ results
 docs/tutorials/needs-ocr-searchable.pdf
 sample.py
 sample2.py
+requirements.lock
+pdfs/hidden
+*.hocr
 
 # Created by https://www.toptal.com/developers/gitignore/api/python,macos,visualstudiocode,jupyternotebooks
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,macos,visualstudiocode,jupyternotebooks

{natural_pdf-0.1.4 → natural_pdf-0.1.6}/CLAUDE.md

@@ -213,7 +213,7 @@ region = page.create_region(50, 50, page.width - 50, page.height - 50)
 sections = region.get_sections(start_elements='text:bold')
 
 # Expand the region around a section
-expanded_section = sections[0].expand(left=20, right=20, top_expand=10, bottom_expand=30)
+expanded_section = sections[0].expand(left=20, right=20, top=10, bottom=30)
 
 # Use percentage-based expansion
 expanded_section = sections[0].expand(width_factor=1.5, height_factor=1.2)  # 50% wider, 20% taller

{natural_pdf-0.1.4 → natural_pdf-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natural-pdf
-Version: 0.1.4
+Version: 0.1.6
 Summary: A more intuitive interface for working with PDFs
 Author-email: Jonathan Soma <jonathan.soma@gmail.com>
 License-Expression: MIT
@@ -16,38 +16,70 @@ Requires-Dist: Pillow
 Requires-Dist: colour
 Requires-Dist: numpy
 Requires-Dist: urllib3
-Requires-Dist: torch
-Requires-Dist: torchvision
-Requires-Dist: transformers
-Requires-Dist: huggingface_hub
-Requires-Dist: ocrmypdf
-Requires-Dist: pikepdf
+Requires-Dist: tqdm
 Provides-Extra: interactive
 Requires-Dist: ipywidgets<9.0.0,>=7.0.0; extra == "interactive"
 Provides-Extra: haystack
 Requires-Dist: haystack-ai; extra == "haystack"
 Requires-Dist: chroma-haystack; extra == "haystack"
 Requires-Dist: sentence-transformers; extra == "haystack"
+Requires-Dist: protobuf<4; extra == "haystack"
+Requires-Dist: natural-pdf[core-ml]; extra == "haystack"
 Provides-Extra: easyocr
 Requires-Dist: easyocr; extra == "easyocr"
+Requires-Dist: natural-pdf[core-ml]; 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"
+Requires-Dist: natural-pdf[core-ml]; extra == "layout-yolo"
 Provides-Extra: surya
 Requires-Dist: surya-ocr; extra == "surya"
+Requires-Dist: natural-pdf[core-ml]; extra == "surya"
 Provides-Extra: qa
+Requires-Dist: natural-pdf[core-ml]; extra == "qa"
+Provides-Extra: docling
+Requires-Dist: docling; extra == "docling"
+Requires-Dist: natural-pdf[core-ml]; extra == "docling"
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == "llm"
+Requires-Dist: pydantic; extra == "llm"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: nox; extra == "dev"
+Requires-Dist: nox-uv; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: uv; extra == "dev"
+Requires-Dist: pipdeptree; extra == "dev"
+Requires-Dist: nbformat; extra == "dev"
+Requires-Dist: jupytext; extra == "dev"
+Requires-Dist: nbclient; extra == "dev"
 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"
-Requires-Dist: haystack-ai; extra == "all"
-Requires-Dist: chroma-haystack; extra == "all"
-Requires-Dist: sentence-transformers; extra == "all"
+Requires-Dist: natural-pdf[interactive]; extra == "all"
+Requires-Dist: natural-pdf[haystack]; extra == "all"
+Requires-Dist: natural-pdf[easyocr]; extra == "all"
+Requires-Dist: natural-pdf[paddle]; extra == "all"
+Requires-Dist: natural-pdf[layout_yolo]; extra == "all"
+Requires-Dist: natural-pdf[surya]; extra == "all"
+Requires-Dist: natural-pdf[qa]; extra == "all"
+Requires-Dist: natural-pdf[ocr-export]; extra == "all"
+Requires-Dist: natural-pdf[docling]; extra == "all"
+Requires-Dist: natural-pdf[llm]; extra == "all"
+Requires-Dist: natural-pdf[test]; extra == "all"
+Provides-Extra: core-ml
+Requires-Dist: torch; extra == "core-ml"
+Requires-Dist: torchvision; extra == "core-ml"
+Requires-Dist: transformers; extra == "core-ml"
+Requires-Dist: huggingface_hub; extra == "core-ml"
+Provides-Extra: ocr-export
+Requires-Dist: ocrmypdf; extra == "ocr-export"
+Requires-Dist: pikepdf; extra == "ocr-export"
 Dynamic: license-file
 
 # Natural PDF
@@ -75,6 +107,10 @@ pip install natural-pdf[easyocr]
 pip install natural-pdf[surya]
 pip install natural-pdf[paddle]
 
+# Example: Install support for features using Large Language Models (e.g., via OpenAI-compatible APIs)
+pip install natural-pdf[llm]
+# (May require setting API key environment variables, e.g., GOOGLE_API_KEY for Gemini)
+
 # Example: Install with interactive viewer support
 pip install natural-pdf[interactive]
 
@@ -127,7 +163,7 @@ Natural PDF offers a range of features for working with PDFs:
 *   **Spatial Navigation:** Select content relative to other elements (`heading.below()`, `element.select_until(...)`).
 *   **Text & Table Extraction:** Get clean text or structured table data, automatically handling exclusions.
 *   **OCR Integration:** Extract text from scanned documents using engines like EasyOCR, PaddleOCR, or Surya.
-*   **Layout Analysis:** Detect document structures (titles, paragraphs, tables) using AI models.
+*   **Layout Analysis:** Detect document structures (titles, paragraphs, tables) using various engines (e.g., YOLO, Paddle, LLM via API).
 *   **Document QA:** Ask natural language questions about your document's content.
 *   **Semantic Search:** Index PDFs and find relevant pages or documents based on semantic meaning using Haystack.
 *   **Visual Debugging:** Highlight elements and use an interactive viewer or save images to understand your selections.

{natural_pdf-0.1.4 → natural_pdf-0.1.6}/README.md

@@ -23,6 +23,10 @@ pip install natural-pdf[easyocr]
 pip install natural-pdf[surya]
 pip install natural-pdf[paddle]
 
+# Example: Install support for features using Large Language Models (e.g., via OpenAI-compatible APIs)
+pip install natural-pdf[llm]
+# (May require setting API key environment variables, e.g., GOOGLE_API_KEY for Gemini)
+
 # Example: Install with interactive viewer support
 pip install natural-pdf[interactive]
 
@@ -75,7 +79,7 @@ Natural PDF offers a range of features for working with PDFs:
 *   **Spatial Navigation:** Select content relative to other elements (`heading.below()`, `element.select_until(...)`).
 *   **Text & Table Extraction:** Get clean text or structured table data, automatically handling exclusions.
 *   **OCR Integration:** Extract text from scanned documents using engines like EasyOCR, PaddleOCR, or Surya.
-*   **Layout Analysis:** Detect document structures (titles, paragraphs, tables) using AI models.
+*   **Layout Analysis:** Detect document structures (titles, paragraphs, tables) using various engines (e.g., YOLO, Paddle, LLM via API).
 *   **Document QA:** Ask natural language questions about your document's content.
 *   **Semantic Search:** Index PDFs and find relevant pages or documents based on semantic meaning using Haystack.
 *   **Visual Debugging:** Highlight elements and use an interactive viewer or save images to understand your selections.

{natural_pdf-0.1.4 → natural_pdf-0.1.6}/docs/ocr/index.md

@@ -92,26 +92,6 @@ surya_opts = SuryaOCROptions(
 ocr_elements = page.apply_ocr(engine='surya', options=surya_opts)
 ```
 
-## Multiple Languages
-
-OCR supports multiple languages:
-
-```python
-# Recognize English and Spanish text
-pdf = PDF('multilingual.pdf', ocr={
-    'enabled': True,
-    'languages': ['en', 'es']
-})
-
-# Multiple languages with PaddleOCR
-pdf = PDF('multilingual_document.pdf', 
-          ocr_engine='paddleocr',
-          ocr={
-              'enabled': True,
-              'languages': ['zh', 'ja', 'ko', 'en']  # Chinese, Japanese, Korean, English
-          })
-```
-
 ## Applying OCR Directly
 
 The `page.apply_ocr(...)` and `region.apply_ocr(...)` methods are the primary way to run OCR:
@@ -179,39 +159,46 @@ high_conf = page.find_all('text[source=ocr][confidence>=0.8]')
 high_conf.highlight(color="green", label="High Confidence OCR")
 ```
 
-## OCR Debugging
+## Detect + LLM OCR
+
+Sometimes you have a difficult piece of content where you need to use a local model to identify the content, then send it off in pieces to be identified by the LLM. You can do this with Natural PDF!
+
+```python
+from natural_pdf import PDF
+from natural_pdf.ocr.utils import direct_ocr_llm
+import openai
+
+pdf = PDF("needs-ocr.pdf")
+page = pdf.pages[0]
+
+# Detect
+page.apply_ocr('paddle', resolution=120, detect_only=True)
+
+# Build the framework
+client = openai.OpenAI(base_url="https://api.anthropic.com/v1/",  api_key='sk-XXXXX')
+prompt = """OCR this image. Return only the exact text from the image. Include misspellings,
+punctuation, etc. Do not surround it with quotation marks. Do not include translations or comments.
+The text is from a Greek spreadsheet, so most likely content is Modern Greek or numeric."""
+
+# This returns the cleaned-up text
+def correct(region):
+    return direct_ocr_llm(region, client, prompt=prompt, resolution=300, model="claude-3-5-haiku-20241022")
+
+# Run 'correct' on each text element
+page.correct_ocr(correct)
+
+# You're done!
+```
 
-For troubleshooting OCR problems:
+## Debugging OCR
 
 ```python
-# Create an interactive HTML debug report
-pdf.debug_ocr("ocr_debug.html")
+from natural_pdf.utils.packaging import create_correction_task_package
 
-# Specify which pages to include
-pdf.debug_ocr("ocr_debug.html", pages=[0, 1, 2])
+create_correction_task_package(pdf, "original.zip", overwrite=True)
 ```
 
-The debug report shows:
-- The original image
-- Text found with confidence scores
-- Boxes around each detected word
-- Options to sort and filter results
-
-## OCR Parameter Tuning
-
-### Parameter Recommendation Table
-
-| Issue | Engine | Parameter | Recommended Value | Effect |
-|-------|--------|-----------|-------------------|--------|
-| Missing text | EasyOCR | `text_threshold` | 0.1 - 0.3 (default: 0.7) | Lower values detect more text but may increase false positives |
-| Missing text | PaddleOCR | `det_db_thresh` | 0.1 - 0.3 (default: 0.3) | Lower values detect more text areas |
-| Low quality scan | EasyOCR | `contrast_ths` | 0.05 - 0.1 (default: 0.1) | Lower values help with low contrast documents |
-| Low quality scan | PaddleOCR | `det_limit_side_len` | 1280 - 2560 (default: 960) | Higher values improve detail detection |
-| Accuracy vs. speed | EasyOCR | `decoder` | "wordbeamsearch" (accuracy)<br>"greedy" (speed) | Word beam search is more accurate but slower |
-| Accuracy vs. speed | PaddleOCR | `rec_batch_num` | 1 (accuracy)<br>8+ (speed) | Larger batches process faster but use more memory |
-| Small text | Both | `min_confidence` | 0.3 - 0.4 (default: 0.5) | Lower confidence threshold to capture small/blurry text |
-| Text orientation | PaddleOCR | `use_angle_cls` | `True` | Enable angle classification for rotated text |
-| Asian languages | PaddleOCR | `lang` | "ch", "japan", "korea" | Use PaddleOCR for Asian languages |
+This will at *some point* be official-ized, but for now you can look at `templates/spa` and see the correction package.
 
 ## Next Steps