structx 0.5.1__tar.gz → 0.6.0__tar.gz

{structx-0.5.1/structx.egg-info → structx-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.5.1
+Version: 0.6.0
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -11,7 +11,6 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Database
 Classifier: Topic :: Documentation
@@ -29,34 +28,34 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: instructor==1.8.0
-Requires-Dist: litellm==1.68.1
-Requires-Dist: loguru==0.7.3
-Requires-Dist: omegaconf==2.3.0
-Requires-Dist: openpyxl==3.1.5
-Requires-Dist: pandas==2.2.3
-Requires-Dist: pydantic==2.11.4
-Requires-Dist: tabulate==0.9.0
-Requires-Dist: tenacity==9.1.2
-Requires-Dist: tqdm==4.68.4
+Requires-Dist: instructor>=1.15.4
+Requires-Dist: litellm>=1.91.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings[yaml]>=2.14.2
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: tqdm>=4.68.4
 Provides-Extra: dev
-Requires-Dist: black==25.1.0; extra == "dev"
-Requires-Dist: bumpver==2024.1130; extra == "dev"
-Requires-Dist: pip-tools==7.4.1; extra == "dev"
-Requires-Dist: pytest==9.1.1; extra == "dev"
-Requires-Dist: wheel==0.45.1; extra == "dev"
+Requires-Dist: black>=25.1.0; extra == "dev"
+Requires-Dist: bumpver>=2024.1130; extra == "dev"
+Requires-Dist: pip-tools>=7.4.1; extra == "dev"
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: wheel>=0.45.1; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: docling-slim[convert-core,format-docx,format-html,format-latex,format-markdown,format-opendocument,format-pdf,format-pptx,format-web,models-local]==2.111.0; extra == "docs"
-Requires-Dist: torch==2.13.0; extra == "docs"
-Requires-Dist: torchvision==0.28.0; extra == "docs"
-Requires-Dist: weasyprint==69.0; extra == "docs"
+Requires-Dist: docling-slim[convert-core,format-docx,format-html,format-latex,format-markdown,format-opendocument,format-pdf,format-pptx,format-web,models-local]>=2.111.0; extra == "docs"
+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: mkdocs
-Requires-Dist: mkdocs==1.6.1; extra == "mkdocs"
-Requires-Dist: mkdocs-material==9.7.6; extra == "mkdocs"
-Requires-Dist: mkdocstrings[python]==0.29.1; extra == "mkdocs"
-Requires-Dist: mkdocs-git-revision-date-localized-plugin==1.4.5; extra == "mkdocs"
-Requires-Dist: mkdocs-material[imaging]==9.7.6; extra == "mkdocs"
-Requires-Dist: mkdocs-mermaid2-plugin==1.2.3; extra == "mkdocs"
+Requires-Dist: mkdocs>=1.6.1; extra == "mkdocs"
+Requires-Dist: mkdocs-material>=9.7.6; extra == "mkdocs"
+Requires-Dist: mkdocstrings[python]>=0.29.1; extra == "mkdocs"
+Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.4.5; extra == "mkdocs"
+Requires-Dist: mkdocs-material[imaging]>=9.7.6; extra == "mkdocs"
+Requires-Dist: mkdocs-mermaid2-plugin>=1.2.3; extra == "mkdocs"
 Dynamic: license-file
 
 # structx
@@ -65,13 +64,13 @@ 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.5.1-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.0-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")
 
 `structx` is a powerful Python library for extracting structured data from text,
-tables, and documents using Large Language Models (LLMs). With the optional
-`docs` extra, it provides a multimodal PDF pipeline that passes PDFs directly to
-vision-capable models and converts other document formats to PDF first.
+tables, and documents using Large Language Models (LLMs). It passes existing
+PDFs directly to vision-capable models; the optional `docs` extra converts other
+document formats to PDF first.
 
 ## 🔔 Package rename notice (PyPI)
 
@@ -90,7 +89,7 @@ pip install -U structx
 ```
 
 If you previously pinned `structx-llm` in requirements or lock files, replace it
-with `structx`. For document/PDF processing, install `structx[docs]`.
+with `structx`. Install `structx[docs]` for non-PDF document conversion.
 
 ## ✨ Key Features
 
@@ -102,8 +101,8 @@ with `structx`. For document/PDF processing, install `structx[docs]`.
   PDFs and images
 - **🔄 Smart Format Detection**: Automatic processing mode selection for best
   results
-- **📊 Flexible File Support**: CSV, Excel, JSON, Parquet in the base install,
-  with PDF, DOCX, TXT, Markdown, and more via `structx[docs]`
+- **📊 Flexible File Support**: CSV, Excel, JSON, Parquet, raw text, and existing
+  PDFs in the base install; DOCX, PPTX, images, and more via `structx[docs]`
 
 ### 🚀 **Intelligent Data Extraction**
 
@@ -117,11 +116,12 @@ with `structx`. For document/PDF processing, install `structx[docs]`.
 
 ### ⚡ **Performance & Reliability**
 
-- **🚀 High-Performance Processing**: Multi-threaded and async operations
+- **🚀 High-Performance Processing**: Threaded sync and native async row requests
 - **🔄 Robust Error Handling**: Automatic retry mechanism with exponential
   backoff
 - **📈 Token Usage Tracking**: Detailed step-by-step metrics for cost monitoring
-- **� Flexible Configuration**: Configurable extraction using OmegaConf
+- **Flexible Configuration**: Model settings from arguments, YAML, environment
+  variables, dotenv files, and secrets through Pydantic Settings
 - **🔌 Multiple LLM Providers**: Support through litellm integration
 
 ## Installation
@@ -130,7 +130,8 @@ with `structx`. For document/PDF processing, install `structx[docs]`.
 pip install structx
 ```
 
-For document and multimodal PDF support:
+For converting DOCX, PowerPoint, OpenDocument, markup, image, and other
+non-PDF document formats:
 
 ```bash
 pip install "structx[docs]"
@@ -166,14 +167,14 @@ result = extractor.extract(
 )
 
 # Access results
-print(f"Extracted {result.success_count} items")
+print(f"Successful rows: {result.success_count}")
 print(result.data[0].model_dump_json(indent=2))
 ```
 
 ### 📄 Document Processing with Multimodal Support
 
 Install `structx[docs]` before using non-PDF document formats. Existing PDFs can
-be passed directly through the multimodal path.
+be passed directly through the multimodal path with the base installation.
 
 ```python
 # Process a PDF invoice through the multimodal pipeline
@@ -193,10 +194,11 @@ result = extractor.extract(
 
 ```python
 # Check token usage for cost monitoring
-usage = result.get_token_usage()
+usage = result.usage
 if usage:
     print(f"Total tokens: {usage.total_tokens}")
-    print(f"By step: {[(s.name, s.tokens) for s in usage.steps]}")
+    for step, calls in usage.steps.items():
+        print(step.value, [call.total_tokens for call in calls])
 ```
 
 ## 🚀 Why Multimodal PDF Processing?
@@ -221,6 +223,7 @@ For comprehensive documentation, examples, and guides, visit our
 
 - [Getting Started](https://structx.aolabs.dev/getting-started)
 - [Basic Extraction](https://structx.aolabs.dev/guides/basic-extraction)
+- [Working with Results](https://structx.aolabs.dev/guides/working-with-results)
 - [Unstructured Text Processing](https://structx.aolabs.dev/guides/unstructured-text)
 - [Async Operations](https://structx.aolabs.dev/guides/async-operations)
 - [Multiple Queries](https://structx.aolabs.dev/guides/multiple-queries)

{structx-0.5.1 → structx-0.6.0}/README.md

@@ -4,13 +4,13 @@ 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.5.1-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.0-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")
 
 `structx` is a powerful Python library for extracting structured data from text,
-tables, and documents using Large Language Models (LLMs). With the optional
-`docs` extra, it provides a multimodal PDF pipeline that passes PDFs directly to
-vision-capable models and converts other document formats to PDF first.
+tables, and documents using Large Language Models (LLMs). It passes existing
+PDFs directly to vision-capable models; the optional `docs` extra converts other
+document formats to PDF first.
 
 ## 🔔 Package rename notice (PyPI)
 
@@ -29,7 +29,7 @@ pip install -U structx
 ```
 
 If you previously pinned `structx-llm` in requirements or lock files, replace it
-with `structx`. For document/PDF processing, install `structx[docs]`.
+with `structx`. Install `structx[docs]` for non-PDF document conversion.
 
 ## ✨ Key Features
 
@@ -41,8 +41,8 @@ with `structx`. For document/PDF processing, install `structx[docs]`.
   PDFs and images
 - **🔄 Smart Format Detection**: Automatic processing mode selection for best
   results
-- **📊 Flexible File Support**: CSV, Excel, JSON, Parquet in the base install,
-  with PDF, DOCX, TXT, Markdown, and more via `structx[docs]`
+- **📊 Flexible File Support**: CSV, Excel, JSON, Parquet, raw text, and existing
+  PDFs in the base install; DOCX, PPTX, images, and more via `structx[docs]`
 
 ### 🚀 **Intelligent Data Extraction**
 
@@ -56,11 +56,12 @@ with `structx`. For document/PDF processing, install `structx[docs]`.
 
 ### ⚡ **Performance & Reliability**
 
-- **🚀 High-Performance Processing**: Multi-threaded and async operations
+- **🚀 High-Performance Processing**: Threaded sync and native async row requests
 - **🔄 Robust Error Handling**: Automatic retry mechanism with exponential
   backoff
 - **📈 Token Usage Tracking**: Detailed step-by-step metrics for cost monitoring
-- **� Flexible Configuration**: Configurable extraction using OmegaConf
+- **Flexible Configuration**: Model settings from arguments, YAML, environment
+  variables, dotenv files, and secrets through Pydantic Settings
 - **🔌 Multiple LLM Providers**: Support through litellm integration
 
 ## Installation
@@ -69,7 +70,8 @@ with `structx`. For document/PDF processing, install `structx[docs]`.
 pip install structx
 ```
 
-For document and multimodal PDF support:
+For converting DOCX, PowerPoint, OpenDocument, markup, image, and other
+non-PDF document formats:
 
 ```bash
 pip install "structx[docs]"
@@ -105,14 +107,14 @@ result = extractor.extract(
 )
 
 # Access results
-print(f"Extracted {result.success_count} items")
+print(f"Successful rows: {result.success_count}")
 print(result.data[0].model_dump_json(indent=2))
 ```
 
 ### 📄 Document Processing with Multimodal Support
 
 Install `structx[docs]` before using non-PDF document formats. Existing PDFs can
-be passed directly through the multimodal path.
+be passed directly through the multimodal path with the base installation.
 
 ```python
 # Process a PDF invoice through the multimodal pipeline
@@ -132,10 +134,11 @@ result = extractor.extract(
 
 ```python
 # Check token usage for cost monitoring
-usage = result.get_token_usage()
+usage = result.usage
 if usage:
     print(f"Total tokens: {usage.total_tokens}")
-    print(f"By step: {[(s.name, s.tokens) for s in usage.steps]}")
+    for step, calls in usage.steps.items():
+        print(step.value, [call.total_tokens for call in calls])
 ```
 
 ## 🚀 Why Multimodal PDF Processing?
@@ -160,6 +163,7 @@ For comprehensive documentation, examples, and guides, visit our
 
 - [Getting Started](https://structx.aolabs.dev/getting-started)
 - [Basic Extraction](https://structx.aolabs.dev/guides/basic-extraction)
+- [Working with Results](https://structx.aolabs.dev/guides/working-with-results)
 - [Unstructured Text Processing](https://structx.aolabs.dev/guides/unstructured-text)
 - [Async Operations](https://structx.aolabs.dev/guides/async-operations)
 - [Multiple Queries](https://structx.aolabs.dev/guides/multiple-queries)

{structx-0.5.1 → structx-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structx"
-version = "0.5.1"
+version = "0.6.0"
 description = "Structured data extraction from text using LLMs and dynamic model generation"
 authors = [{ name = "blacksuan19", email = "py@aolabs.dev" }]
 license-files = ["LICENSE"]
@@ -19,7 +19,6 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3",
     "Topic :: Database",
     "Topic :: Documentation",
@@ -37,25 +36,25 @@ classifiers = [
 ]
 
 dependencies = [
-    "instructor==1.8.0",
-    "litellm==1.68.1",
-    "loguru==0.7.3",
-    "omegaconf==2.3.0",
-    "openpyxl==3.1.5",
-    "pandas==2.2.3",
-    "pydantic==2.11.4",
-    "tabulate==0.9.0", # required for pandas .to_markdown()
-    "tenacity==9.1.2",
-    "tqdm==4.68.4",
+    "instructor>=1.15.4",
+    "litellm>=1.91.1",
+    "loguru>=0.7.3",
+    "openpyxl>=3.1.5",
+    "pandas>=2.2.3",
+    "pydantic>=2.11.7",
+    "pydantic-settings[yaml]>=2.14.2",
+    "tabulate>=0.9.0", # required for pandas .to_markdown()
+    "tenacity>=9.1.2",
+    "tqdm>=4.68.4",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "black==25.1.0",
-    "bumpver==2024.1130",
-    "pip-tools==7.4.1",
-    "pytest==9.1.1",
-    "wheel==0.45.1",
+    "black>=25.1.0",
+    "bumpver>=2024.1130",
+    "pip-tools>=7.4.1",
+    "pytest>=9.1.1",
+    "wheel>=0.45.1",
 ]
 
 # Optional document processing support. Kept out of the base install because
@@ -63,20 +62,20 @@ dev = [
 # The format-pdf extra is still needed because DocumentConverter imports its
 # PDF backend dependencies even when existing PDFs are passed through directly.
 docs = [
-    "docling-slim[convert-core,format-docx,format-html,format-latex,format-markdown,format-opendocument,format-pdf,format-pptx,format-web,models-local]==2.111.0",
-    "torch==2.13.0",
-    "torchvision==0.28.0",
-    "weasyprint==69.0",
+    "docling-slim[convert-core,format-docx,format-html,format-latex,format-markdown,format-opendocument,format-pdf,format-pptx,format-web,models-local]>=2.111.0",
+    "torch>=2.13.0",
+    "torchvision>=0.28.0",
+    "weasyprint>=69.0",
 ]
 
 # Documentation site tooling.
 mkdocs = [
-    "mkdocs==1.6.1",
-    "mkdocs-material==9.7.6",
-    "mkdocstrings[python]==0.29.1",
-    "mkdocs-git-revision-date-localized-plugin==1.4.5",
-    "mkdocs-material[imaging]==9.7.6",
-    "mkdocs-mermaid2-plugin==1.2.3",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=0.29.1",
+    "mkdocs-git-revision-date-localized-plugin>=1.4.5",
+    "mkdocs-material[imaging]>=9.7.6",
+    "mkdocs-mermaid2-plugin>=1.2.3",
 ]
 
 [[tool.uv.index]]
@@ -93,7 +92,7 @@ torchvision = [
 ]
 
 [tool.bumpver]
-current_version = "0.5.1"
+current_version = "0.6.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "Bump version {old_version} -> {new_version}"
 commit = true
@@ -112,6 +111,7 @@ include = ["structx*"]
 
 [tool.pytest.ini_options]
 filterwarnings = [
+    "ignore:There is no current event loop:DeprecationWarning:litellm\\._service_logger",
     "ignore:This field is deprecated.*:DeprecationWarning:docling\\.pipeline\\.standard_pdf_pipeline",
     "ignore:torch\\.ao\\.quantization is deprecated.*:DeprecationWarning:torch\\.ao\\.quantization\\.quantize",
     "ignore:torch\\.quantize_per_tensor.*:UserWarning:torch\\.ao\\.nn\\.quantized\\.dynamic\\.modules\\.rnn",

{structx-0.5.1 → structx-0.6.0}/structx/__init__.py

@@ -4,21 +4,22 @@ structx: Structured data extraction using LLMs
 
 from structx.core.config import ExtractionConfig, StepConfig
 from structx.core.models import (
-    ExtractionGuide,
+    ExtractionPlan,
     ExtractionRequest,
+    ExtractionResult,
     ModelField,
-    QueryRefinement,
+    RowResult,
 )
 from structx.extraction.extractor import Extractor
 
-__version__ = "0.5.1"
+__version__ = "0.6.0"
 __all__ = [
     "Extractor",
     "ExtractionConfig",
     "StepConfig",
     "ModelField",
-    "QueryAnalysis",
-    "QueryRefinement",
-    "ExtractionGuide",
+    "ExtractionPlan",
     "ExtractionRequest",
+    "ExtractionResult",
+    "RowResult",
 ]

structx-0.6.0/structx/core/config.py

@@ -0,0 +1,101 @@
+"""Pydantic Settings configuration for model-backed extraction steps."""
+
+import json
+from pathlib import Path
+from typing import Any, Type
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+from structx.core.exceptions import ConfigurationError
+from structx.utils.types import DictStrAny
+
+
+class StepConfig(BaseModel):
+    """Provider-specific completion parameters for one extraction step."""
+
+    model_config = ConfigDict(validate_assignment=True, extra="allow")
+
+    @model_validator(mode="before")
+    @classmethod
+    def decode_scalar_values(cls, value: Any) -> Any:
+        """Decode numeric and boolean values supplied by nested environment keys."""
+        if not isinstance(value, dict):
+            return value
+        decoded = {}
+        for key, item in value.items():
+            if isinstance(item, str):
+                try:
+                    item = json.loads(item)
+                except json.JSONDecodeError:
+                    pass
+            decoded[key] = item
+        return decoded
+
+    def options(self) -> DictStrAny:
+        """Return explicitly configured provider parameters."""
+        return self.model_dump(exclude_none=True)
+
+
+class ExtractionConfig(BaseSettings):
+    """Settings loaded from arguments, environment, dotenv, YAML, or secrets.
+
+    Source priority is constructor values, environment variables, ``.env``,
+    YAML, then file secrets. Environment and secret names use the ``STRUCTX_``
+    prefix.
+    """
+
+    planning: StepConfig = Field(default_factory=StepConfig)
+    extraction: StepConfig = Field(default_factory=StepConfig)
+
+    model_config = SettingsConfigDict(
+        extra="ignore",
+        env_prefix="STRUCTX_",
+        env_nested_delimiter="__",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        yaml_file=None,
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: Type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Use conventional precedence with YAML below dotenv values."""
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            YamlConfigSettingsSource(settings_cls),
+            file_secret_settings,
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path, **overrides: Any) -> "ExtractionConfig":
+        """Load settings from a YAML file with optional highest-priority overrides."""
+        yaml_path = Path(path).expanduser()
+        if not yaml_path.is_file():
+            raise ConfigurationError(f"Configuration file not found: {yaml_path}")
+
+        class YamlExtractionConfig(cls):
+            model_config = SettingsConfigDict(
+                **{**cls.model_config, "yaml_file": yaml_path}
+            )
+
+        return YamlExtractionConfig(**overrides)
+
+    def for_step(self, step: str) -> DictStrAny:
+        """Return provider kwargs for ``planning`` or ``extraction``."""
+        if step not in {"planning", "extraction"}:
+            raise ConfigurationError(f"Unknown extraction step: {step}")
+        return getattr(self, step).options()

structx-0.6.0/structx/core/exceptions.py

@@ -0,0 +1,34 @@
+class StructXError(Exception):
+    """Base exception for errors raised directly by Structx."""
+
+    pass
+
+
+class ConfigurationError(StructXError):
+    """Raised for invalid Structx configuration or runtime settings."""
+
+    pass
+
+
+class ExtractionError(StructXError):
+    """Raised when a public extraction operation cannot complete."""
+
+    pass
+
+
+class ValidationError(StructXError):
+    """Raised for Structx-specific input validation failures."""
+
+    pass
+
+
+class ModelGenerationError(StructXError):
+    """Raised when an extraction schema cannot become a Pydantic model."""
+
+    pass
+
+
+class FileError(StructXError):
+    """Raised for invalid paths, unsupported files, or conversion failures."""
+
+    pass

structx-0.6.0/structx/core/input.py

@@ -0,0 +1,58 @@
+"""Typed contracts for prepared extraction inputs."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class PdfRow:
+    """A PDF payload associated with one source row.
+
+    Attributes:
+        pdf_path: PDF sent to Instructor's multimodal input.
+        source: Original user-supplied document path. For converted documents,
+            this differs from ``pdf_path``.
+    """
+
+    pdf_path: Path
+    source: Path
+
+
+RowPayload = Union[str, PdfRow]
+
+
+@dataclass
+class PreparedInput:
+    """Normalized extraction input and its owned resources.
+
+    ``InputProcessor`` creates this contract before planning or row processing.
+    Application code normally receives an ``ExtractionResult`` instead; this
+    type is primarily useful when calling ``FileReader`` directly.
+
+    Attributes:
+        dataframe: Source rows retained for planning, provenance, and optional
+            DataFrame output.
+        pdf_rows: Positional row mappings for multimodal PDF payloads.
+        planning_sample: Text extracted once from a converted document for
+            schema planning. Existing PDFs usually leave this unset and are
+            attached directly to the planning request.
+        owned_paths: Temporary files that must be deleted after processing.
+            ``InputProcessor.prepared`` handles this automatically.
+    """
+
+    dataframe: pd.DataFrame
+    pdf_rows: Dict[int, PdfRow] = field(default_factory=dict)
+    planning_sample: Optional[str] = None
+    owned_paths: List[Path] = field(default_factory=list)
+
+    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."""
+        pdf_row = self.pdf_rows.get(position)
+        if pdf_row is not None:
+            return pdf_row
+        return row[target_columns].to_markdown()