structx 0.6.2__tar.gz → 0.6.4__tar.gz

{structx-0.6.2/structx.egg-info → structx-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.2
+Version: 0.6.4
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -49,6 +49,12 @@ Requires-Dist: docling-slim[convert-core,format-docx,format-html,format-latex,fo
 Requires-Dist: torch>=2.13.0; extra == "docs"
 Requires-Dist: torchvision>=0.28.0; extra == "docs"
 Requires-Dist: weasyprint>=69.0; extra == "docs"
+Provides-Extra: measurement
+Requires-Dist: pypdfium2>=5.12.1; extra == "measurement"
+Provides-Extra: measurement-ocr
+Requires-Dist: pypdfium2>=5.12.1; extra == "measurement-ocr"
+Requires-Dist: rapidocr>=3.9.0; extra == "measurement-ocr"
+Requires-Dist: onnxruntime>=1.22.0; extra == "measurement-ocr"
 Provides-Extra: mkdocs
 Requires-Dist: mkdocs>=1.6.1; extra == "mkdocs"
 Requires-Dist: mkdocs-material>=9.7.6; extra == "mkdocs"
@@ -64,7 +70,7 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.2-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.4-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
 See the [project roadmap](docs/ROADMAP.md) for planned portable business rules
@@ -140,12 +146,21 @@ non-PDF document formats:
 pip install "structx[docs]"
 ```
 
+For estimating PDF page and text counts before extraction, without running an
+extraction:
+
+```bash
+pip install "structx[measurement]"        # embedded text only
+pip install "structx[measurement-ocr]"    # adds local OCR for scanned pages
+```
+
 ### 🔧 What The Package Provides
 
 - Structured readers for CSV, Excel, JSON, Parquet, and Feather
 - Instructor multimodal vision support
 - Optional Docling document parsing with CPU-only PyTorch resolution for uv on Linux
 - Optional WeasyPrint PDF rendering for non-PDF document formats
+- Optional standalone document measurement, separate from the extraction path
 
 ## Quick Start
 
@@ -193,6 +208,22 @@ result = extractor.extract(
 )
 ```
 
+### 📏 Document Measurement Before Extraction
+
+Install `structx[measurement]` to size a PDF without extracting it. This path is
+independent of extraction: it never converts or replaces the input file.
+
+```python
+from structx.measurement import DocumentMeasurer
+
+measurement = DocumentMeasurer(ocr_mode="auto").measure(
+    "scripts/example_input/S0305SampleInvoice.pdf"
+)
+
+# Estimates, plus whether every page could actually be measured
+print(measurement.page_count, measurement.character_count, measurement.status)
+```
+
 ### 📊 Token Usage Monitoring
 
 ```python

{structx-0.6.2 → structx-0.6.4}/README.md

@@ -4,7 +4,7 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.2-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.4-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
 See the [project roadmap](docs/ROADMAP.md) for planned portable business rules
@@ -80,12 +80,21 @@ non-PDF document formats:
 pip install "structx[docs]"
 ```
 
+For estimating PDF page and text counts before extraction, without running an
+extraction:
+
+```bash
+pip install "structx[measurement]"        # embedded text only
+pip install "structx[measurement-ocr]"    # adds local OCR for scanned pages
+```
+
 ### 🔧 What The Package Provides
 
 - Structured readers for CSV, Excel, JSON, Parquet, and Feather
 - Instructor multimodal vision support
 - Optional Docling document parsing with CPU-only PyTorch resolution for uv on Linux
 - Optional WeasyPrint PDF rendering for non-PDF document formats
+- Optional standalone document measurement, separate from the extraction path
 
 ## Quick Start
 
@@ -133,6 +142,22 @@ result = extractor.extract(
 )
 ```
 
+### 📏 Document Measurement Before Extraction
+
+Install `structx[measurement]` to size a PDF without extracting it. This path is
+independent of extraction: it never converts or replaces the input file.
+
+```python
+from structx.measurement import DocumentMeasurer
+
+measurement = DocumentMeasurer(ocr_mode="auto").measure(
+    "scripts/example_input/S0305SampleInvoice.pdf"
+)
+
+# Estimates, plus whether every page could actually be measured
+print(measurement.page_count, measurement.character_count, measurement.status)
+```
+
 ### 📊 Token Usage Monitoring
 
 ```python

{structx-0.6.2 → structx-0.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structx"
-version = "0.6.2"
+version = "0.6.4"
 description = "Structured data extraction from text using LLMs and dynamic model generation"
 authors = [{ name = "blacksuan19", email = "py@aolabs.dev" }]
 license-files = ["LICENSE"]
@@ -68,6 +68,20 @@ docs = [
     "weasyprint>=69.0",
 ]
 
+# Optional standalone document measurement (structx.measurement). Independent
+# of extraction: it estimates page and text counts for callers that need a
+# size estimate before running an extraction.
+measurement = [
+    "pypdfium2>=5.12.1",
+]
+
+# Local OCR for measuring pages that have no embedded text layer.
+measurement-ocr = [
+    "pypdfium2>=5.12.1",
+    "rapidocr>=3.9.0",
+    "onnxruntime>=1.22.0",
+]
+
 # Documentation site tooling.
 mkdocs = [
     "mkdocs>=1.6.1",
@@ -92,7 +106,7 @@ torchvision = [
 ]
 
 [tool.bumpver]
-current_version = "0.6.2"
+current_version = "0.6.4"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "chore(release): bump version {old_version} -> {new_version}"
 commit = true

{structx-0.6.2 → structx-0.6.4}/structx/__init__.py

@@ -3,6 +3,7 @@ structx: Structured data extraction using LLMs
 """
 
 from structx.core.config import ExtractionConfig, StepConfig
+from structx.core.input import PreparedInput
 from structx.core.models import (
     ExtractionPlan,
     ExtractionRequest,
@@ -21,11 +22,12 @@ from structx.schema import (
     model_to_extraction_request,
 )
 
-__version__ = "0.6.2"
+__version__ = "0.6.4"
 __all__ = [
     "Extractor",
     "ExtractionConfig",
     "StepConfig",
+    "PreparedInput",
     "ModelField",
     "ExtractionPlan",
     "ExtractionRequest",

{structx-0.6.2 → structx-0.6.4}/structx/core/input.py

@@ -47,11 +47,32 @@ class PreparedInput:
     pdf_rows: Dict[int, PdfRow] = field(default_factory=dict)
     planning_sample: Optional[str] = None
     owned_paths: List[Path] = field(default_factory=list)
+    _closed: bool = field(default=False, init=False, repr=False)
+
+    @property
+    def closed(self) -> bool:
+        """Whether temporary resources owned by this input were released."""
+        return self._closed
+
+    def ensure_open(self) -> None:
+        """Reject reuse after explicit cleanup."""
+        if self._closed:
+            raise RuntimeError("Prepared input is closed")
+
+    def close(self) -> None:
+        """Release owned temporary resources. This operation is idempotent."""
+        if self._closed:
+            return
+        for path in self.owned_paths:
+            Path(path).unlink(missing_ok=True)
+        self.owned_paths.clear()
+        self._closed = True
 
     def row_payload(
         self, position: int, row: pd.Series, target_columns: List[str]
     ) -> RowPayload:
         """Build the text or PDF payload for one positional input row."""
+        self.ensure_open()
         pdf_row = self.pdf_rows.get(position)
         if pdf_row is not None:
             return pdf_row

{structx-0.6.2 → structx-0.6.4}/structx/extraction/extractor.py

@@ -1,12 +1,12 @@
 """Public orchestration for structured extraction operations."""
 
 import asyncio
+from contextlib import asynccontextmanager, contextmanager
 from dataclasses import dataclass
 from functools import partial
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Type, Union
+from typing import Any, AsyncGenerator, Dict, Generator, List, Optional, Type, Union
 
-import pandas as pd
 from instructor import AsyncInstructor, Instructor
 from loguru import logger
 from pydantic import BaseModel
@@ -19,7 +19,7 @@ from structx.extraction.core.llm_core import LLMCore
 from structx.extraction.engines.extraction_engine import ExtractionEngine
 from structx.extraction.processors.batch_processor import BatchProcessor
 from structx.extraction.processors.content_analyzer import ContentAnalyzer
-from structx.extraction.processors.input_processor import InputProcessor
+from structx.extraction.processors.input_processor import InputData, InputProcessor
 from structx.extraction.processors.model_operations import ModelOperations
 from structx.extraction.result_manager import ResultCollector
 from structx.utils.helpers import handle_errors
@@ -138,6 +138,24 @@ class Extractor:
             raise ValueError("queries must not contain duplicates")
         return validated
 
+    @contextmanager
+    def prepare_input(
+        self, *, data: InputData, **kwargs: Any
+    ) -> Generator[PreparedInput, None, None]:
+        """Prepare input once and release owned resources after the context."""
+        with self.input_processor.prepared(data, **kwargs) as prepared_input:
+            yield prepared_input
+
+    @asynccontextmanager
+    async def prepare_input_async(
+        self, *, data: InputData, **kwargs: Any
+    ) -> AsyncGenerator[PreparedInput, None]:
+        """Prepare input off-loop and release resources after the async context."""
+        async with self.input_processor.prepared_async(
+            data, **kwargs
+        ) as prepared_input:
+            yield prepared_input
+
     def _build_strategy(
         self,
         prepared_input: PreparedInput,
@@ -377,7 +395,7 @@ class Extractor:
     def extract(
         self,
         *,
-        data: Union[str, Path, pd.DataFrame, List[Dict[str, str]]],
+        data: InputData,
         query: str,
         model: Optional[Type[BaseModel]] = None,
         return_df: bool = False,
@@ -407,7 +425,7 @@ class Extractor:
     async def extract_async(
         self,
         *,
-        data: Union[str, Path, pd.DataFrame, List[Dict[str, str]]],
+        data: InputData,
         query: str,
         model: Optional[Type[BaseModel]] = None,
         return_df: bool = False,
@@ -443,7 +461,7 @@ class Extractor:
     def extract_queries(
         self,
         *,
-        data: Union[str, Path, pd.DataFrame, List[Dict[str, str]]],
+        data: InputData,
         queries: List[str],
         return_df: bool = True,
         expand_nested: bool = False,
@@ -478,7 +496,7 @@ class Extractor:
     async def extract_queries_async(
         self,
         *,
-        data: Union[str, Path, pd.DataFrame, List[Dict[str, str]]],
+        data: InputData,
         queries: List[str],
         return_df: bool = True,
         expand_nested: bool = False,
@@ -518,7 +536,7 @@ class Extractor:
     def get_schema(
         self,
         *,
-        data: Union[str, Path, pd.DataFrame, List[Dict[str, str]]],
+        data: InputData,
         query: str,
         **kwargs: Any,
     ) -> Type[BaseModel]:
@@ -557,7 +575,7 @@ class Extractor:
     async def get_schema_async(
         self,
         *,
-        data: Union[str, Path, pd.DataFrame, List[Dict[str, str]]],
+        data: InputData,
         query: str,
         **kwargs: Any,
     ) -> Type[BaseModel]:

{structx-0.6.2 → structx-0.6.4}/structx/extraction/processors/input_processor.py

@@ -3,7 +3,7 @@
 import asyncio
 from contextlib import asynccontextmanager, contextmanager
 from pathlib import Path
-from typing import Any, AsyncIterator, Dict, Iterator, List, Union
+from typing import Any, AsyncGenerator, Dict, Generator, List, Union
 
 import pandas as pd
 
@@ -11,35 +11,44 @@ from structx.core.exceptions import FileError
 from structx.core.input import PreparedInput
 from structx.utils.file_reader import FileReader
 
-InputData = Union[str, Path, pd.DataFrame, List[Dict[str, str]]]
+InputData = Union[str, Path, pd.DataFrame, List[Dict[str, str]], PreparedInput]
 
 
 class InputProcessor:
     """Prepare supported inputs and own any temporary files they create."""
 
     @contextmanager
-    def prepared(self, data: InputData, **kwargs: Any) -> Iterator[PreparedInput]:
+    def prepared(
+        self, data: InputData, **kwargs: Any
+    ) -> Generator[PreparedInput, None, None]:
         """Yield normalized data and always release owned temporary files."""
+        owns_prepared_input = not isinstance(data, PreparedInput)
         prepared_input = self.prepare(data, **kwargs)
         try:
             yield prepared_input
         finally:
-            self.cleanup(prepared_input)
+            if owns_prepared_input:
+                self.cleanup(prepared_input)
 
     @asynccontextmanager
     async def prepared_async(
         self, data: InputData, **kwargs: Any
-    ) -> AsyncIterator[PreparedInput]:
+    ) -> AsyncGenerator[PreparedInput, None]:
         """Prepare blocking file inputs off-loop and own their lifetime."""
+        owns_prepared_input = not isinstance(data, PreparedInput)
         prepared_input = await asyncio.to_thread(self.prepare, data, **kwargs)
         try:
             yield prepared_input
         finally:
-            await asyncio.to_thread(self.cleanup, prepared_input)
+            if owns_prepared_input:
+                await asyncio.to_thread(self.cleanup, prepared_input)
 
     def prepare(self, data: InputData, **kwargs: Any) -> PreparedInput:
         """Normalize a supported input and retain its explicit resource metadata."""
-        if isinstance(data, pd.DataFrame):
+        if isinstance(data, PreparedInput):
+            data.ensure_open()
+            prepared_input = data
+        elif isinstance(data, pd.DataFrame):
             prepared_input = PreparedInput(dataframe=data)
         elif isinstance(data, list) and all(isinstance(item, dict) for item in data):
             prepared_input = PreparedInput(dataframe=pd.DataFrame(data))
@@ -102,6 +111,4 @@ class InputProcessor:
     @staticmethod
     def cleanup(prepared_input: PreparedInput) -> None:
         """Remove temporary artifacts owned by a prepared input."""
-        for path in prepared_input.owned_paths:
-            Path(path).unlink(missing_ok=True)
-        prepared_input.owned_paths.clear()
+        prepared_input.close()