structx 0.6.1__tar.gz → 0.6.3__tar.gz

{structx-0.6.1/structx.egg-info → structx-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.1
+Version: 0.6.3
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -64,7 +64,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.1-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.3-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

{structx-0.6.1 → structx-0.6.3}/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.1-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.3-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

{structx-0.6.1 → structx-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structx"
-version = "0.6.1"
+version = "0.6.3"
 description = "Structured data extraction from text using LLMs and dynamic model generation"
 authors = [{ name = "blacksuan19", email = "py@aolabs.dev" }]
 license-files = ["LICENSE"]
@@ -92,9 +92,9 @@ torchvision = [
 ]
 
 [tool.bumpver]
-current_version = "0.6.1"
+current_version = "0.6.3"
 version_pattern = "MAJOR.MINOR.PATCH"
-commit_message = "Bump version {old_version} -> {new_version}"
+commit_message = "chore(release): bump version {old_version} -> {new_version}"
 commit = true
 tag = true
 push = true

{structx-0.6.1 → structx-0.6.3}/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.1"
+__version__ = "0.6.3"
 __all__ = [
     "Extractor",
     "ExtractionConfig",
     "StepConfig",
+    "PreparedInput",
     "ModelField",
     "ExtractionPlan",
     "ExtractionRequest",

{structx-0.6.1 → structx-0.6.3}/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.1 → structx-0.6.3}/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.1 → structx-0.6.3}/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()

{structx-0.6.1 → structx-0.6.3/structx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.1
+Version: 0.6.3
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -64,7 +64,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.1-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.3-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

{structx-0.6.1 → structx-0.6.3}/tests/test_extractor_async.py

@@ -85,3 +85,32 @@ def test_extract_async_requires_an_async_client_for_provider_calls():
                 model=AsyncRecord,
             )
         )
+
+
+def test_explicit_prepared_input_can_be_inspected_and_reused_async():
+    completions = TrackingAsyncCompletions()
+    extractor = Extractor(
+        client=SimpleNamespace(),
+        async_client=SimpleNamespace(chat=SimpleNamespace(completions=completions)),
+        model_name="provider/model",
+        max_threads=1,
+        max_retries=0,
+    )
+
+    async def prepare_and_extract():
+        async with extractor.prepare_input_async(
+            data=[{"text": "row-0"}]
+        ) as prepared_input:
+            assert prepared_input.dataframe.shape == (1, 1)
+            result = await extractor.extract_async(
+                data=prepared_input,
+                query="extract value",
+                model=AsyncRecord,
+            )
+            assert not prepared_input.closed
+            return result, prepared_input
+
+    result, prepared_input = asyncio.run(prepare_and_extract())
+
+    assert [item.value for item in result.data] == ["row-0"]
+    assert prepared_input.closed

{structx-0.6.1 → structx-0.6.3}/tests/test_extractor_flow.py

@@ -1,8 +1,9 @@
-from types import SimpleNamespace
 from contextlib import contextmanager
+from types import SimpleNamespace
 
 import pandas as pd
 import pytest
+from pydantic import BaseModel
 
 from structx.core.exceptions import ConfigurationError, ExtractionError
 from structx.core.input import PreparedInput
@@ -85,3 +86,45 @@ def test_extract_queries_prepares_and_cleans_data_once(monkeypatch):
         "cleanup": 1,
         "process": ["payment", "termination"],
     }
+
+
+def test_get_schema_accepts_caller_owned_prepared_input(monkeypatch):
+    class GeneratedRecord(BaseModel):
+        value: str
+
+    extractor = Extractor(client=_unused_client(), model_name="provider/model")
+    monkeypatch.setattr(
+        extractor.model_operations,
+        "generate_extraction_plan",
+        lambda **kwargs: SimpleNamespace(extraction_schema=object()),
+    )
+    monkeypatch.setattr(
+        extractor.model_operations,
+        "create_model_from_schema",
+        lambda schema: GeneratedRecord,
+    )
+
+    with extractor.prepare_input(
+        data=pd.DataFrame({"text": ["agreement"]})
+    ) as prepared_input:
+        model = extractor.get_schema(
+            data=prepared_input,
+            query="extract value",
+        )
+
+        assert model is GeneratedRecord
+        assert not prepared_input.closed
+
+    assert prepared_input.closed
+
+
+def test_prepare_input_context_cleans_up_after_an_error():
+    extractor = Extractor(client=_unused_client(), model_name="provider/model")
+
+    with pytest.raises(RuntimeError, match="stop inspection"):
+        with extractor.prepare_input(
+            data=pd.DataFrame({"text": ["agreement"]})
+        ) as prepared_input:
+            raise RuntimeError("stop inspection")
+
+    assert prepared_input.closed

{structx-0.6.1 → structx-0.6.3}/tests/test_input_and_batch_processors.py

@@ -161,3 +161,28 @@ def test_cleanup_data_removes_all_owned_temporary_paths(tmp_path):
 
     assert all(not path.exists() for path in paths)
     assert prepared_input.owned_paths == []
+    assert prepared_input.closed
+
+
+def test_explicitly_prepared_input_is_reused_without_automatic_cleanup(tmp_path):
+    owned_path = tmp_path / "rendered.pdf"
+    owned_path.write_text("temporary", encoding="utf-8")
+    prepared_input = PreparedInput(
+        dataframe=pd.DataFrame({"source": ["document.docx"]}),
+        owned_paths=[owned_path],
+    )
+    processor = InputProcessor()
+
+    with processor.prepared(prepared_input) as reused:
+        assert reused is prepared_input
+
+    assert owned_path.exists()
+    assert not prepared_input.closed
+
+    prepared_input.close()
+    prepared_input.close()
+
+    assert not owned_path.exists()
+    assert prepared_input.closed
+    with pytest.raises(RuntimeError, match="closed"):
+        processor.prepare(prepared_input)