biblicus 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

biblicus/extractors/paddleocr_vl_text.py

@@ -0,0 +1,305 @@
+"""
+PaddleOCR-VL backed optical character recognition extractor plugin.
+
+This extractor uses PaddleOCR-VL, a vision-language model that provides
+improved optical character recognition accuracy especially for complex layouts and multilingual text.
+
+The extractor supports both local inference and application programming interface based inference via
+the inference backend abstraction.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, ClassVar, Dict, List, Optional, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..corpus import Corpus
+from ..errors import ExtractionRunFatalError
+from ..inference import ApiProvider, InferenceBackendConfig, InferenceBackendMode, resolve_api_key
+from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
+from .base import TextExtractor
+
+
+class PaddleOcrVlExtractorConfig(BaseModel):
+    """
+    Configuration for the PaddleOCR-VL extractor.
+
+    :ivar backend: Inference backend configuration for local or application programming interface execution.
+    :vartype backend: InferenceBackendConfig
+    :ivar min_confidence: Minimum confidence threshold for including text.
+    :vartype min_confidence: float
+    :ivar joiner: String used to join recognized text lines.
+    :vartype joiner: str
+    :ivar use_angle_cls: Whether to use angle classification for rotated text.
+    :vartype use_angle_cls: bool
+    :ivar lang: Language code for optical character recognition model.
+    :vartype lang: str
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    backend: InferenceBackendConfig = Field(default_factory=InferenceBackendConfig)
+    min_confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+    joiner: str = Field(default="\n")
+    use_angle_cls: bool = Field(default=True)
+    lang: str = Field(default="en")
+
+
+class PaddleOcrVlExtractor(TextExtractor):
+    """
+    Extractor plugin using PaddleOCR-VL for optical character recognition.
+
+    This extractor handles image media types and returns text with confidence scores.
+    It supports both local inference and application programming interface based inference.
+
+    :ivar extractor_id: Extractor identifier.
+    :vartype extractor_id: str
+    """
+
+    extractor_id = "ocr-paddleocr-vl"
+
+    _model_cache: ClassVar[Dict[Tuple[str, bool], Any]] = {}
+
+    def validate_config(self, config: Dict[str, Any]) -> BaseModel:
+        """
+        Validate extractor configuration and ensure prerequisites are available.
+
+        :param config: Configuration mapping.
+        :type config: dict[str, Any]
+        :return: Parsed configuration model.
+        :rtype: PaddleOcrVlExtractorConfig
+        :raises ExtractionRunFatalError: If required dependencies are missing.
+        """
+        import json
+
+        parsed_config = {}
+        for key, value in config.items():
+            if isinstance(value, str) and (value.startswith("{") or value.startswith("[")):
+                try:
+                    parsed_config[key] = json.loads(value)
+                except json.JSONDecodeError:
+                    parsed_config[key] = value
+            else:
+                parsed_config[key] = value
+
+        parsed = PaddleOcrVlExtractorConfig.model_validate(parsed_config)
+
+        if parsed.backend.mode == InferenceBackendMode.LOCAL:
+            try:
+                from paddleocr import PaddleOCR  # noqa: F401
+            except ImportError as import_error:
+                raise ExtractionRunFatalError(
+                    "PaddleOCR-VL extractor (local mode) requires paddleocr. "
+                    'Install it with pip install "biblicus[paddleocr]".'
+                ) from import_error
+        else:
+            # api_provider is guaranteed to be set by InferenceBackendConfig validator
+            api_key = resolve_api_key(
+                parsed.backend.api_provider,
+                config_override=parsed.backend.api_key,
+            )
+            if api_key is None:
+                provider_name = parsed.backend.api_provider.value.upper()
+                raise ExtractionRunFatalError(
+                    f"PaddleOCR-VL extractor (API mode) requires an API key for {provider_name}. "
+                    f"Set {provider_name}_API_KEY environment variable or configure "
+                    f"{parsed.backend.api_provider.value} in user config."
+                )
+
+        return parsed
+
+    def extract_text(
+        self,
+        *,
+        corpus: Corpus,
+        item: CatalogItem,
+        config: BaseModel,
+        previous_extractions: List[ExtractionStepOutput],
+    ) -> Optional[ExtractedText]:
+        """
+        Extract text from an image using PaddleOCR-VL.
+
+        :param corpus: Corpus containing the item bytes.
+        :type corpus: Corpus
+        :param item: Catalog item being processed.
+        :type item: CatalogItem
+        :param config: Parsed configuration model.
+        :type config: PaddleOcrVlExtractorConfig
+        :param previous_extractions: Prior step outputs for this item.
+        :type previous_extractions: list[ExtractionStepOutput]
+        :return: Extracted text with confidence, or None for non-image items.
+        :rtype: ExtractedText or None
+        """
+        _ = previous_extractions
+
+        if not item.media_type.startswith("image/"):
+            return None
+
+        parsed_config = (
+            config
+            if isinstance(config, PaddleOcrVlExtractorConfig)
+            else PaddleOcrVlExtractorConfig.model_validate(config)
+        )
+
+        source_path = corpus.root / item.relpath
+
+        if parsed_config.backend.mode == InferenceBackendMode.LOCAL:
+            text, confidence = self._extract_local(source_path, parsed_config)
+        else:
+            api_key = resolve_api_key(
+                parsed_config.backend.api_provider,
+                config_override=parsed_config.backend.api_key,
+            )
+            text, confidence = self._extract_via_api(
+                source_path, parsed_config, api_key
+            )
+
+        return ExtractedText(
+            text=text,
+            producer_extractor_id=self.extractor_id,
+            confidence=confidence,
+        )
+
+    def _extract_local(
+        self, source_path: Path, config: PaddleOcrVlExtractorConfig
+    ) -> Tuple[str, Optional[float]]:
+        """
+        Perform local inference using PaddleOCR.
+
+        :param source_path: Path to the image file.
+        :type source_path: Path
+        :param config: Parsed extractor configuration.
+        :type config: PaddleOcrVlExtractorConfig
+        :return: Tuple of extracted text and average confidence score.
+        :rtype: tuple[str, float or None]
+        """
+        from paddleocr import PaddleOCR
+
+        cache_key = (config.lang, config.use_angle_cls)
+        ocr = PaddleOcrVlExtractor._model_cache.get(cache_key)
+        if ocr is None:
+            ocr = PaddleOCR(
+                use_angle_cls=config.use_angle_cls,
+                lang=config.lang,
+            )
+            PaddleOcrVlExtractor._model_cache[cache_key] = ocr
+        result = ocr.ocr(str(source_path), cls=config.use_angle_cls)
+
+        if result is None or not result:
+            return "", None
+
+        lines: list[str] = []
+        confidences: list[float] = []
+
+        for page_result in result:
+            if page_result is None:
+                continue
+            for line_result in page_result:
+                if not isinstance(line_result, (list, tuple)) or len(line_result) < 2:
+                    continue
+                text_info = line_result[1]
+                if isinstance(text_info, (list, tuple)) and len(text_info) >= 2:
+                    text_value = text_info[0]
+                    conf_value = text_info[1]
+                    if isinstance(conf_value, (int, float)):
+                        confidence = float(conf_value)
+                        if confidence >= config.min_confidence:
+                            if isinstance(text_value, str) and text_value.strip():
+                                lines.append(text_value.strip())
+                                confidences.append(confidence)
+
+        text = config.joiner.join(lines).strip()
+        avg_confidence = sum(confidences) / len(confidences) if confidences else None
+
+        return text, avg_confidence
+
+    def _extract_via_api(
+        self, source_path: Path, config: PaddleOcrVlExtractorConfig, api_key: Optional[str]
+    ) -> Tuple[str, Optional[float]]:
+        """
+        Perform inference via application programming interface.
+
+        :param source_path: Path to the image file.
+        :type source_path: Path
+        :param config: Parsed extractor configuration.
+        :type config: PaddleOcrVlExtractorConfig
+        :param api_key: Application programming interface key for the provider.
+        :type api_key: str or None
+        :return: Tuple of extracted text and confidence score.
+        :rtype: tuple[str, float or None]
+        """
+        if config.backend.api_provider == ApiProvider.HUGGINGFACE:
+            return self._extract_via_huggingface_api(source_path, config, api_key)
+        else:
+            return "", None
+
+    def _extract_via_huggingface_api(
+        self, source_path: Path, config: PaddleOcrVlExtractorConfig, api_key: Optional[str]
+    ) -> Tuple[str, Optional[float]]:
+        """
+        Perform inference via HuggingFace Inference API.
+
+        :param source_path: Path to the image file.
+        :type source_path: Path
+        :param config: Parsed extractor configuration.
+        :type config: PaddleOcrVlExtractorConfig
+        :param api_key: HuggingFace application programming interface key.
+        :type api_key: str or None
+        :return: Tuple of extracted text and confidence score.
+        :rtype: tuple[str, float or None]
+        """
+        import base64
+
+        import requests
+
+        with open(source_path, "rb") as f:
+            image_data = base64.b64encode(f.read()).decode("utf-8")
+
+        headers = {"Authorization": f"Bearer {api_key}"}
+
+        model_id = config.backend.model_id or "PaddlePaddle/PaddleOCR-VL"
+        api_url = f"https://api-inference.huggingface.co/models/{model_id}"
+        response = requests.post(
+            api_url,
+            headers=headers,
+            json={"inputs": image_data},
+            timeout=60,
+        )
+        response.raise_for_status()
+
+        result = response.json()
+        return self._parse_api_response(result, config)
+
+    def _parse_api_response(
+        self, result: Any, config: PaddleOcrVlExtractorConfig
+    ) -> Tuple[str, Optional[float]]:
+        """
+        Parse application programming interface response.
+
+        :param result: Application programming interface response data.
+        :type result: Any
+        :param config: Parsed extractor configuration.
+        :type config: PaddleOcrVlExtractorConfig
+        :return: Tuple of extracted text and confidence score.
+        :rtype: tuple[str, float or None]
+        """
+        _ = config
+        if isinstance(result, str):
+            return result.strip(), None
+        if isinstance(result, dict):
+            text = result.get("generated_text", "")
+            confidence = result.get("confidence")
+            if isinstance(confidence, (int, float)):
+                return text.strip(), float(confidence)
+            return text.strip(), None
+        if isinstance(result, list) and result:
+            first = result[0]
+            if isinstance(first, dict):
+                text = first.get("generated_text", "")
+                confidence = first.get("confidence")
+                if isinstance(confidence, (int, float)):
+                    return text.strip(), float(confidence)
+                return text.strip(), None
+        return "", None

biblicus/extractors/rapidocr_text.py

@@ -109,6 +109,7 @@ class RapidOcrExtractor(TextExtractor):
             return ExtractedText(text="", producer_extractor_id=self.extractor_id)
 
         lines: list[str] = []
+        confidences: list[float] = []
         for entry in result:
             if not isinstance(entry, list) or len(entry) < 3:
                 continue
@@ -124,6 +125,12 @@ class RapidOcrExtractor(TextExtractor):
             cleaned = text_value.strip()
             if cleaned:
                 lines.append(cleaned)
+                confidences.append(confidence)
 
         text = parsed_config.joiner.join(lines).strip()
-        return ExtractedText(text=text, producer_extractor_id=self.extractor_id)
+        avg_confidence = sum(confidences) / len(confidences) if confidences else None
+        return ExtractedText(
+            text=text,
+            producer_extractor_id=self.extractor_id,
+            confidence=avg_confidence,
+        )

biblicus/extractors/select_override.py

@@ -0,0 +1,121 @@
+"""
+Simple override selection extractor that always uses the last extraction for matching types.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
+from .base import TextExtractor
+
+
+class SelectOverrideConfig(BaseModel):
+    """
+    Configuration for simple override selection.
+
+    :ivar media_type_patterns: List of media type patterns where override applies.
+    :vartype media_type_patterns: list[str]
+    :ivar fallback_to_first: If True, fall back to first extraction when no override match.
+    :vartype fallback_to_first: bool
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    media_type_patterns: List[str] = Field(default_factory=lambda: ["*/*"])
+    fallback_to_first: bool = Field(default=False)
+
+
+class SelectOverrideExtractor(TextExtractor):
+    """
+    Simple override selector that uses the last extraction for matching media types.
+
+    For items matching the configured patterns, always use the last extraction.
+    For non-matching items, use the first extraction (if fallback_to_first) or last.
+
+    :ivar extractor_id: Extractor identifier.
+    :vartype extractor_id: str
+    """
+
+    extractor_id = "select-override"
+
+    def validate_config(self, config: Dict[str, Any]) -> BaseModel:
+        """
+        Validate selection extractor configuration.
+
+        :param config: Configuration mapping.
+        :type config: dict[str, Any]
+        :return: Parsed configuration.
+        :rtype: SelectOverrideConfig
+        """
+        import json
+
+        # Parse JSON values from CLI string format
+        parsed_config = {}
+        for key, value in config.items():
+            if isinstance(value, str) and value.startswith("["):
+                try:
+                    parsed_config[key] = json.loads(value)
+                except json.JSONDecodeError:
+                    parsed_config[key] = value
+            else:
+                parsed_config[key] = value
+
+        return SelectOverrideConfig.model_validate(parsed_config)
+
+    def extract_text(
+        self,
+        *,
+        corpus,
+        item: CatalogItem,
+        config: BaseModel,
+        previous_extractions: List[ExtractionStepOutput],
+    ) -> Optional[ExtractedText]:
+        """
+        Select extracted text using simple override logic.
+
+        :param corpus: Corpus containing the item bytes.
+        :type corpus: Corpus
+        :param item: Catalog item being processed.
+        :type item: CatalogItem
+        :param config: Parsed configuration model.
+        :type config: SelectOverrideConfig
+        :param previous_extractions: Prior step outputs for this item within the pipeline.
+        :type previous_extractions: list[biblicus.models.ExtractionStepOutput]
+        :return: Selected extracted text payload or None when no prior outputs exist.
+        :rtype: ExtractedText or None
+        """
+        _ = corpus
+        parsed_config = (
+            config
+            if isinstance(config, SelectOverrideConfig)
+            else SelectOverrideConfig.model_validate(config)
+        )
+
+        extracted_candidates = [e for e in previous_extractions if e.text is not None]
+
+        if not extracted_candidates:
+            return None
+
+        matches_pattern = any(
+            fnmatch.fnmatch(item.media_type, pattern)
+            for pattern in parsed_config.media_type_patterns
+        )
+
+        if matches_pattern:
+            candidate = extracted_candidates[-1]
+        elif parsed_config.fallback_to_first:
+            candidate = extracted_candidates[0]
+        else:
+            candidate = extracted_candidates[-1]
+
+        producer = candidate.producer_extractor_id or candidate.extractor_id
+        return ExtractedText(
+            text=candidate.text or "",
+            producer_extractor_id=producer,
+            source_step_index=candidate.step_index,
+            confidence=candidate.confidence,
+        )

biblicus/extractors/select_smart_override.py

@@ -0,0 +1,187 @@
+"""
+Smart override selection extractor that intelligently chooses between extraction results.
+
+This extractor implements the smart override behavior where it compares the most recent
+extraction against previous ones and makes an intelligent choice based on content quality
+and confidence scores.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
+from .base import TextExtractor
+
+
+class SelectSmartOverrideConfig(BaseModel):
+    """
+    Configuration for smart override selection.
+
+    :ivar media_type_patterns: List of media type patterns to consider (e.g., image/*).
+    :vartype media_type_patterns: list[str]
+    :ivar min_confidence_threshold: Minimum confidence to consider an extraction good.
+    :vartype min_confidence_threshold: float
+    :ivar min_text_length: Minimum text length to consider an extraction meaningful.
+    :vartype min_text_length: int
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    media_type_patterns: List[str] = Field(default_factory=lambda: ["*/*"])
+    min_confidence_threshold: float = Field(default=0.7, ge=0.0, le=1.0)
+    min_text_length: int = Field(default=10, ge=0)
+
+
+class SelectSmartOverrideExtractor(TextExtractor):
+    """
+    Smart override selector that intelligently chooses between extraction results.
+
+    This extractor applies smart override logic for items matching the configured media
+    type patterns. The selection rules are:
+
+    1. If the item's media type doesn't match any configured patterns, use last extraction.
+    2. If the last extraction has meaningful content, use it.
+    3. If the last extraction is empty or low-confidence but a previous extraction has
+       good content with confidence, use the previous one.
+    4. Otherwise, use the last extraction.
+
+    Meaningful content is defined as text length >= min_text_length AND (confidence
+    >= min_confidence_threshold OR confidence is not available).
+
+    :ivar extractor_id: Extractor identifier.
+    :vartype extractor_id: str
+    """
+
+    extractor_id = "select-smart-override"
+
+    def validate_config(self, config: Dict[str, Any]) -> BaseModel:
+        """
+        Validate selection extractor configuration.
+
+        :param config: Configuration mapping.
+        :type config: dict[str, Any]
+        :return: Parsed configuration.
+        :rtype: SelectSmartOverrideConfig
+        """
+        import json
+
+        # Parse JSON values from CLI string format
+        parsed_config = {}
+        for key, value in config.items():
+            if isinstance(value, str) and value.startswith("["):
+                try:
+                    parsed_config[key] = json.loads(value)
+                except json.JSONDecodeError:
+                    parsed_config[key] = value
+            else:
+                parsed_config[key] = value
+
+        return SelectSmartOverrideConfig.model_validate(parsed_config)
+
+    def extract_text(
+        self,
+        *,
+        corpus,
+        item: CatalogItem,
+        config: BaseModel,
+        previous_extractions: List[ExtractionStepOutput],
+    ) -> Optional[ExtractedText]:
+        """
+        Select extracted text using smart override logic.
+
+        :param corpus: Corpus containing the item bytes.
+        :type corpus: Corpus
+        :param item: Catalog item being processed.
+        :type item: CatalogItem
+        :param config: Parsed configuration model.
+        :type config: SelectSmartOverrideConfig
+        :param previous_extractions: Prior step outputs for this item within the pipeline.
+        :type previous_extractions: list[biblicus.models.ExtractionStepOutput]
+        :return: Selected extracted text payload or None when no prior outputs exist.
+        :rtype: ExtractedText or None
+        """
+        _ = corpus
+        parsed_config = (
+            config
+            if isinstance(config, SelectSmartOverrideConfig)
+            else SelectSmartOverrideConfig.model_validate(config)
+        )
+
+        matches_pattern = any(
+            fnmatch.fnmatch(item.media_type, pattern)
+            for pattern in parsed_config.media_type_patterns
+        )
+
+        extracted_candidates = [e for e in previous_extractions if e.text is not None]
+
+        if not extracted_candidates:
+            return None
+
+        if not matches_pattern:
+            return self._extraction_to_result(extracted_candidates[-1])
+
+        last_extraction = extracted_candidates[-1]
+        previous_candidates = extracted_candidates[:-1]
+
+        last_is_meaningful = self._is_meaningful(last_extraction, parsed_config)
+
+        if last_is_meaningful:
+            return self._extraction_to_result(last_extraction)
+
+        best_candidate = None
+        best_confidence = -1.0
+        for prev in previous_candidates:
+            if self._is_meaningful(prev, parsed_config):
+                prev_confidence = prev.confidence if prev.confidence is not None else 0.0
+                if prev_confidence > best_confidence:
+                    best_candidate = prev
+                    best_confidence = prev_confidence
+
+        if best_candidate is not None:
+            return self._extraction_to_result(best_candidate)
+
+        return self._extraction_to_result(last_extraction)
+
+    def _is_meaningful(
+        self, extraction: ExtractionStepOutput, config: SelectSmartOverrideConfig
+    ) -> bool:
+        """
+        Check if an extraction has meaningful content.
+
+        :param extraction: Extraction step output to check.
+        :type extraction: ExtractionStepOutput
+        :param config: Parsed configuration.
+        :type config: SelectSmartOverrideConfig
+        :return: True if the extraction has meaningful content.
+        :rtype: bool
+        """
+        text = (extraction.text or "").strip()
+        if len(text) < config.min_text_length:
+            return False
+
+        confidence = extraction.confidence
+        if confidence is not None and confidence < config.min_confidence_threshold:
+            return False
+
+        return True
+
+    def _extraction_to_result(self, extraction: ExtractionStepOutput) -> ExtractedText:
+        """
+        Convert an ExtractionStepOutput to ExtractedText.
+
+        :param extraction: Extraction step output to convert.
+        :type extraction: ExtractionStepOutput
+        :return: Extracted text result.
+        :rtype: ExtractedText
+        """
+        producer = extraction.producer_extractor_id or extraction.extractor_id
+        return ExtractedText(
+            text=extraction.text or "",
+            producer_extractor_id=producer,
+            source_step_index=extraction.step_index,
+            confidence=extraction.confidence,
+        )