document-extraction-tools 0.0.1rc1__py3-none-any.whl

document_extraction_tools/base/__init__.py

@@ -0,0 +1,27 @@
+"""Public base component interfaces."""
+
+from document_extraction_tools.base.converter.base_converter import BaseConverter
+from document_extraction_tools.base.evaluator.base_evaluator import BaseEvaluator
+from document_extraction_tools.base.exporter.base_evaluation_exporter import (
+    BaseEvaluationExporter,
+)
+from document_extraction_tools.base.exporter.base_extraction_exporter import (
+    BaseExtractionExporter,
+)
+from document_extraction_tools.base.extractor.base_extractor import BaseExtractor
+from document_extraction_tools.base.file_lister.base_file_lister import BaseFileLister
+from document_extraction_tools.base.reader.base_reader import BaseReader
+from document_extraction_tools.base.test_data_loader.base_test_data_loader import (
+    BaseTestDataLoader,
+)
+
+__all__ = [
+    "BaseConverter",
+    "BaseEvaluationExporter",
+    "BaseEvaluator",
+    "BaseExtractionExporter",
+    "BaseExtractor",
+    "BaseFileLister",
+    "BaseReader",
+    "BaseTestDataLoader",
+]

document_extraction_tools/base/converter/base_converter.py

@@ -0,0 +1,40 @@
+"""Abstract Base Class for Document Converters.
+
+This module defines the interface that all converter implementations must satisfy.
+Converters are responsible for transforming raw binary data (DocumentBytes)
+into a structured Document object containing pages and content.
+"""
+
+from abc import ABC, abstractmethod
+
+from document_extraction_tools.config.base_converter_config import BaseConverterConfig
+from document_extraction_tools.types.document import Document
+from document_extraction_tools.types.document_bytes import DocumentBytes
+
+
+class BaseConverter(ABC):
+    """Abstract interface for document transformation."""
+
+    def __init__(self, config: BaseConverterConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseConverterConfig): Configuration specific to the converter implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    def convert(self, document_bytes: DocumentBytes) -> Document:
+        """Transforms raw document bytes into a structured Document object.
+
+        This method should handle the parsing logic and map the metadata from the
+        input bytes to the output document.
+
+        Args:
+            document_bytes (DocumentBytes): The standardized raw input containing
+                                            file bytes and source metadata.
+
+        Returns:
+            Document: The fully structured document model ready for extraction.
+        """
+        pass

document_extraction_tools/base/evaluator/base_evaluator.py

@@ -0,0 +1,40 @@
+"""Abstract Base Class for Evaluators.
+
+This module defines the interface that all evaluator implementations must satisfy.
+Evaluators are responsible for computing evaluation metrics by comparing
+predicted data against ground-truth data.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Generic
+
+from document_extraction_tools.config.base_evaluator_config import BaseEvaluatorConfig
+from document_extraction_tools.types.evaluation_result import EvaluationResult
+from document_extraction_tools.types.schema import ExtractionSchema
+
+
+class BaseEvaluator(ABC, Generic[ExtractionSchema]):
+    """Abstract interface for evaluation metrics."""
+
+    def __init__(self, config: BaseEvaluatorConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseEvaluatorConfig): Configuration specific to the evaluator implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    def evaluate(
+        self, true: ExtractionSchema, pred: ExtractionSchema
+    ) -> EvaluationResult:
+        """Compute a metric for a single document.
+
+        Args:
+            true (ExtractionSchema): Ground-truth data.
+            pred (ExtractionSchema): Predicted data.
+
+        Returns:
+            EvaluationResult: The metric result for this document.
+        """
+        pass

document_extraction_tools/base/exporter/base_evaluation_exporter.py

@@ -0,0 +1,43 @@
+"""Abstract Base Class for Evaluation Exporters.
+
+This module defines the interface that all evaluation exporter implementations must satisfy.
+Evaluation Exporters are responsible for taking evaluation results and persisting them
+to a target destination.
+"""
+
+from abc import ABC, abstractmethod
+
+from document_extraction_tools.config.base_evaluation_exporter_config import (
+    BaseEvaluationExporterConfig,
+)
+from document_extraction_tools.types.document import Document
+from document_extraction_tools.types.evaluation_result import EvaluationResult
+
+
+class BaseEvaluationExporter(ABC):
+    """Abstract interface for exporting evaluation results."""
+
+    def __init__(self, config: BaseEvaluationExporterConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseEvaluationExporterConfig): Configuration specific to the evaluation exporter implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    async def export(
+        self, results: list[tuple[Document, list[EvaluationResult]]]
+    ) -> None:
+        """Persist evaluation results to a target destination.
+
+        This is an asynchronous operation to support non-blocking I/O writes.
+
+        Args:
+            results (list[tuple[Document, list[EvaluationResult]]]):
+                A list of tuples containing documents and their associated evaluation results.
+
+        Returns:
+            None: The method should raise an exception if the export fails.
+        """
+        pass

document_extraction_tools/base/exporter/base_extraction_exporter.py

@@ -0,0 +1,41 @@
+"""Abstract Base Class for Extraction Exporters.
+
+This module defines the interface that all exporter implementations must satisfy.
+Extraction Exporters are responsible for taking the extracted, structured Pydantic data
+and persisting it to a target destination.
+"""
+
+from abc import ABC, abstractmethod
+
+from document_extraction_tools.config.base_extraction_exporter_config import (
+    BaseExtractionExporterConfig,
+)
+from document_extraction_tools.types.document import Document
+from document_extraction_tools.types.schema import ExtractionSchema
+
+
+class BaseExtractionExporter(ABC):
+    """Abstract interface for data persistence."""
+
+    def __init__(self, config: BaseExtractionExporterConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseExtractionExporterConfig): Configuration specific to the exporter implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    async def export(self, document: Document, data: ExtractionSchema) -> None:
+        """Persists extracted data to the configured destination.
+
+        This is an asynchronous operation to support non-blocking I/O writes.
+
+        Args:
+            document (Document): The source document for this extraction.
+            data (ExtractionSchema): The populated Pydantic model containing the extracted information.
+
+        Returns:
+            None: The method should raise an exception if the export fails.
+        """
+        pass

document_extraction_tools/base/extractor/base_extractor.py

@@ -0,0 +1,41 @@
+"""Abstract Base Class for Information Extractors.
+
+This module defines the interface that all extractor implementations must satisfy.
+Extractors are responsible for analyzing the structured Document
+and populating a target Pydantic schema with specific data points.
+"""
+
+from abc import ABC, abstractmethod
+
+from document_extraction_tools.config.base_extractor_config import BaseExtractorConfig
+from document_extraction_tools.types.document import Document
+from document_extraction_tools.types.schema import ExtractionSchema
+
+
+class BaseExtractor(ABC):
+    """Abstract interface for data extraction."""
+
+    def __init__(self, config: BaseExtractorConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseExtractorConfig): Configuration specific to the extractor implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    async def extract(
+        self, document: Document, schema: type[ExtractionSchema]
+    ) -> ExtractionSchema:
+        """Extracts structured data from a Document to match the provided Schema.
+
+        This is an asynchronous operation to support I/O-bound tasks.
+
+        Args:
+            document (Document): The fully parsed document.
+            schema (type[ExtractionSchema]): The Pydantic model class defining the target structure.
+
+        Returns:
+            ExtractionSchema: An instance of the schema populated with the extracted data.
+        """
+        pass

document_extraction_tools/base/file_lister/base_file_lister.py

@@ -0,0 +1,37 @@
+"""Abstract Base Class for File Listers.
+
+This module defines the interface that all file lister implementations must satisfy.
+File Listers are responsible for scanning a source
+and returning a list of standardized identifiers to be processed.
+"""
+
+from abc import ABC, abstractmethod
+
+from document_extraction_tools.config.base_file_lister_config import (
+    BaseFileListerConfig,
+)
+from document_extraction_tools.types.path_identifier import PathIdentifier
+
+
+class BaseFileLister(ABC):
+    """Abstract interface for file discovery."""
+
+    def __init__(self, config: BaseFileListerConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseFileListerConfig): Configuration specific to the file lister implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    def list_files(self) -> list[PathIdentifier]:
+        """Scans the target source and returns a list of file identifiers.
+
+        This method should handle the logic to return a clean list of work items.
+
+        Returns:
+            List[PathIdentifier]: A list of standardized objects containing the
+                                  path and any necessary execution context.
+        """
+        pass

document_extraction_tools/base/reader/base_reader.py

@@ -0,0 +1,36 @@
+"""Abstract Base Class for Document Readers.
+
+This module defines the interface that all reader implementations must satisfy.
+Readers are responsible for fetching raw file content from a source
+and returning it as a standardized DocumentBytes object.
+"""
+
+from abc import ABC, abstractmethod
+
+from document_extraction_tools.config.base_reader_config import BaseReaderConfig
+from document_extraction_tools.types.document_bytes import DocumentBytes
+from document_extraction_tools.types.path_identifier import PathIdentifier
+
+
+class BaseReader(ABC):
+    """Abstract interface for document ingestion."""
+
+    def __init__(self, config: BaseReaderConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseReaderConfig): Configuration specific to the reader implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    def read(self, path_identifier: PathIdentifier) -> DocumentBytes:
+        """Reads a document from a specific source and returns its raw bytes.
+
+        Args:
+            path_identifier (PathIdentifier): The identifier for the file.
+
+        Returns:
+            DocumentBytes: A standardized container with raw bytes and source metadata.
+        """
+        pass

document_extraction_tools/base/test_data_loader/base_test_data_loader.py

@@ -0,0 +1,44 @@
+"""Abstract Base Class for Test Data Loaders.
+
+This module defines the interface that all test data loader implementations must satisfy.
+Test Data Loaders are responsible for loading evaluation test examples from a specified source.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Generic
+
+from document_extraction_tools.config.base_test_data_loader_config import (
+    BaseTestDataLoaderConfig,
+)
+from document_extraction_tools.types.evaluation_example import EvaluationExample
+from document_extraction_tools.types.path_identifier import PathIdentifier
+from document_extraction_tools.types.schema import ExtractionSchema
+
+
+class BaseTestDataLoader(ABC, Generic[ExtractionSchema]):
+    """Abstract interface for loading evaluation test data."""
+
+    def __init__(self, config: BaseTestDataLoaderConfig) -> None:
+        """Initialize with a configuration object.
+
+        Args:
+            config (BaseTestDataLoaderConfig): Configuration specific to the test data loader implementation.
+        """
+        self.config = config
+
+    @abstractmethod
+    def load_test_data(
+        self, path_identifier: PathIdentifier
+    ) -> list[EvaluationExample[ExtractionSchema]]:
+        """Load test examples for evaluation.
+
+        This method should retrieve and return a list of EvaluationExample instances
+        based on the provided path identifier.
+
+        Args:
+            path_identifier (PathIdentifier): The source location for loading evaluation examples.
+
+        Returns:
+            list[EvaluationExample[ExtractionSchema]]: A list of evaluation examples for evaluation.
+        """
+        pass

document_extraction_tools/config/__init__.py

@@ -0,0 +1,51 @@
+"""Public config helpers and models."""
+
+from document_extraction_tools.config.base_converter_config import BaseConverterConfig
+from document_extraction_tools.config.base_evaluation_exporter_config import (
+    BaseEvaluationExporterConfig,
+)
+from document_extraction_tools.config.base_evaluator_config import BaseEvaluatorConfig
+from document_extraction_tools.config.base_extraction_exporter_config import (
+    BaseExtractionExporterConfig,
+)
+from document_extraction_tools.config.base_extractor_config import BaseExtractorConfig
+from document_extraction_tools.config.base_file_lister_config import (
+    BaseFileListerConfig,
+)
+from document_extraction_tools.config.base_reader_config import BaseReaderConfig
+from document_extraction_tools.config.base_test_data_loader_config import (
+    BaseTestDataLoaderConfig,
+)
+from document_extraction_tools.config.config_loader import (
+    load_config,
+    load_evaluation_config,
+)
+from document_extraction_tools.config.evaluation_orchestrator_config import (
+    EvaluationOrchestratorConfig,
+)
+from document_extraction_tools.config.evaluation_pipeline_config import (
+    EvaluationPipelineConfig,
+)
+from document_extraction_tools.config.extraction_orchestrator_config import (
+    ExtractionOrchestratorConfig,
+)
+from document_extraction_tools.config.extraction_pipeline_config import (
+    ExtractionPipelineConfig,
+)
+
+__all__ = [
+    "BaseConverterConfig",
+    "BaseEvaluationExporterConfig",
+    "BaseEvaluatorConfig",
+    "BaseExtractionExporterConfig",
+    "BaseExtractorConfig",
+    "BaseFileListerConfig",
+    "BaseReaderConfig",
+    "BaseTestDataLoaderConfig",
+    "EvaluationOrchestratorConfig",
+    "EvaluationPipelineConfig",
+    "ExtractionOrchestratorConfig",
+    "ExtractionPipelineConfig",
+    "load_config",
+    "load_evaluation_config",
+]

document_extraction_tools/config/base_converter_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Converter components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseConverterConfig(BaseModel):
+    """Base config for Converters.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "converter.yaml"

document_extraction_tools/config/base_evaluation_exporter_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Evaluation Exporter components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseEvaluationExporterConfig(BaseModel):
+    """Base config for Evaluation Exporters.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "evaluation_exporter.yaml"

document_extraction_tools/config/base_evaluator_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Evaluator components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseEvaluatorConfig(BaseModel):
+    """Base config for Evaluators.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "evaluator.yaml"

document_extraction_tools/config/base_extraction_exporter_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Extraction Exporter components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseExtractionExporterConfig(BaseModel):
+    """Base config for Exporters.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "extraction_exporter.yaml"

document_extraction_tools/config/base_extractor_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Extractor components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseExtractorConfig(BaseModel):
+    """Base config for Extractors.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "extractor.yaml"

document_extraction_tools/config/base_file_lister_config.py

@@ -0,0 +1,14 @@
+"""Configuration for File Lister components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseFileListerConfig(BaseModel):
+    """Base config for File Listers.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "file_lister.yaml"

document_extraction_tools/config/base_reader_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Reader components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseReaderConfig(BaseModel):
+    """Base config for Readers.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "reader.yaml"

document_extraction_tools/config/base_test_data_loader_config.py

@@ -0,0 +1,14 @@
+"""Configuration for Test Data Loader components."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class BaseTestDataLoaderConfig(BaseModel):
+    """Base config for Test Data Loaders.
+
+    Implementations should subclass this to add specific parameters.
+    """
+
+    filename: ClassVar[str] = "test_data_loader.yaml"