biblicus 0.16.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

biblicus/extractors/deepgram_stt.py

@@ -11,7 +11,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from ..user_config import resolve_deepgram_api_key
 from .base import TextExtractor
@@ -66,19 +66,19 @@ class DeepgramSpeechToTextExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed configuration model.
         :rtype: DeepgramSpeechToTextExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency or required environment is missing.
+        :raises ExtractionSnapshotFatalError: If the optional dependency or required environment is missing.
         """
         try:
             from deepgram import DeepgramClient  # noqa: F401
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "Deepgram speech to text extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[deepgram]".'
             ) from import_error
 
         api_key = resolve_deepgram_api_key()
         if api_key is None:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "Deepgram speech to text extractor requires a Deepgram API key. "
                 "Set DEEPGRAM_API_KEY or configure it in ~/.biblicus/config.yml or ./.biblicus/config.yml under "
                 "deepgram.api_key."
@@ -107,7 +107,7 @@ class DeepgramSpeechToTextExtractor(TextExtractor):
         :type previous_extractions: list[biblicus.models.ExtractionStepOutput]
         :return: Extracted text payload, or None when the item is not audio.
         :rtype: ExtractedText or None
-        :raises ExtractionRunFatalError: If the optional dependency or required configuration is missing.
+        :raises ExtractionSnapshotFatalError: If the optional dependency or required configuration is missing.
         """
         _ = previous_extractions
         if not item.media_type.startswith("audio/"):
@@ -121,7 +121,7 @@ class DeepgramSpeechToTextExtractor(TextExtractor):
 
         api_key = resolve_deepgram_api_key()
         if api_key is None:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "Deepgram speech to text extractor requires a Deepgram API key. "
                 "Set DEEPGRAM_API_KEY or configure it in ~/.biblicus/config.yml or ./.biblicus/config.yml under "
                 "deepgram.api_key."
@@ -130,7 +130,7 @@ class DeepgramSpeechToTextExtractor(TextExtractor):
         try:
             from deepgram import DeepgramClient
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "Deepgram speech to text extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[deepgram]".'
             ) from import_error

biblicus/extractors/docling_granite_text.py

@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
 
@@ -40,14 +40,14 @@ class DoclingGraniteExtractorConfig(BaseModel):
 
     :ivar output_format: Output format for extracted content (markdown, text, or html).
     :vartype output_format: str
-    :ivar backend: Inference backend (mlx or transformers).
-    :vartype backend: str
+    :ivar retriever: Inference retriever (mlx or transformers).
+    :vartype retriever: str
     """
 
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
     output_format: str = Field(default="markdown", pattern="^(markdown|text|html)$")
-    backend: str = Field(default="mlx", pattern="^(mlx|transformers)$")
+    retriever: str = Field(default="mlx", pattern="^(mlx|transformers)$", alias="backend")
 
 
 class DoclingGraniteExtractor(TextExtractor):
@@ -71,7 +71,7 @@ class DoclingGraniteExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed config.
         :rtype: DoclingGraniteExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency is not installed.
+        :raises ExtractionSnapshotFatalError: If the optional dependency is not installed.
         """
         parsed = DoclingGraniteExtractorConfig.model_validate(config)
 
@@ -82,19 +82,19 @@ class DoclingGraniteExtractor(TextExtractor):
                 vlm_model_specs,
             )
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "DoclingGranite extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[docling]".'
             ) from import_error
 
-        if parsed.backend == "mlx":
+        if parsed.retriever == "mlx":
             try:
                 from docling.pipeline_options import vlm_model_specs
 
                 _ = vlm_model_specs.GRANITE_DOCLING_MLX
             except (ImportError, AttributeError) as exc:
-                raise ExtractionRunFatalError(
-                    "DoclingGranite extractor with MLX backend requires MLX support. "
+                raise ExtractionSnapshotFatalError(
+                    "DoclingGranite extractor with MLX retriever requires MLX support. "
                     'Install it with pip install "biblicus[docling-mlx]".'
                 ) from exc
 
@@ -167,7 +167,7 @@ class DoclingGraniteExtractor(TextExtractor):
         from docling.format_options import InputFormat, PdfFormatOption
         from docling.pipeline_options import VlmPipelineOptions, vlm_model_specs
 
-        if config.backend == "mlx":
+        if config.retriever == "mlx":
             vlm_options = vlm_model_specs.GRANITE_DOCLING_MLX
         else:
             vlm_options = vlm_model_specs.GRANITE_DOCLING_TRANSFORMERS

biblicus/extractors/docling_smol_text.py

@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
 
@@ -40,14 +40,14 @@ class DoclingSmolExtractorConfig(BaseModel):
 
     :ivar output_format: Output format for extracted content (markdown, text, or html).
     :vartype output_format: str
-    :ivar backend: Inference backend (mlx or transformers).
-    :vartype backend: str
+    :ivar retriever: Inference retriever (mlx or transformers).
+    :vartype retriever: str
     """
 
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
     output_format: str = Field(default="markdown", pattern="^(markdown|text|html)$")
-    backend: str = Field(default="mlx", pattern="^(mlx|transformers)$")
+    retriever: str = Field(default="mlx", pattern="^(mlx|transformers)$", alias="backend")
 
 
 class DoclingSmolExtractor(TextExtractor):
@@ -71,7 +71,7 @@ class DoclingSmolExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed config.
         :rtype: DoclingSmolExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency is not installed.
+        :raises ExtractionSnapshotFatalError: If the optional dependency is not installed.
         """
         parsed = DoclingSmolExtractorConfig.model_validate(config)
 
@@ -82,19 +82,19 @@ class DoclingSmolExtractor(TextExtractor):
                 vlm_model_specs,
             )
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "DoclingSmol extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[docling]".'
             ) from import_error
 
-        if parsed.backend == "mlx":
+        if parsed.retriever == "mlx":
             try:
                 from docling.pipeline_options import vlm_model_specs
 
                 _ = vlm_model_specs.SMOLDOCLING_MLX
             except (ImportError, AttributeError) as exc:
-                raise ExtractionRunFatalError(
-                    "DoclingSmol extractor with MLX backend requires MLX support. "
+                raise ExtractionSnapshotFatalError(
+                    "DoclingSmol extractor with MLX retriever requires MLX support. "
                     'Install it with pip install "biblicus[docling-mlx]".'
                 ) from exc
 
@@ -167,7 +167,7 @@ class DoclingSmolExtractor(TextExtractor):
         from docling.format_options import InputFormat, PdfFormatOption
         from docling.pipeline_options import VlmPipelineOptions, vlm_model_specs
 
-        if config.backend == "mlx":
+        if config.retriever == "mlx":
             vlm_options = vlm_model_specs.SMOLDOCLING_MLX
         else:
             vlm_options = vlm_model_specs.SMOLDOCLING_TRANSFORMERS

biblicus/extractors/markitdown_text.py

@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
 
@@ -52,18 +52,18 @@ class MarkItDownExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed config.
         :rtype: MarkItDownExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency is not installed.
+        :raises ExtractionSnapshotFatalError: If the optional dependency is not installed.
         """
         try:
             import markitdown
             from markitdown import MarkItDown  # noqa: F401
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "MarkItDown extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[markitdown]".'
             ) from import_error
         if sys.version_info < (3, 10) and not getattr(markitdown, "__biblicus_fake__", False):
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "MarkItDown requires Python 3.10 or higher. "
                 "Upgrade your interpreter or use a compatible extractor."
             )

biblicus/extractors/openai_stt.py

@@ -11,7 +11,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from ..user_config import resolve_openai_api_key
 from .base import TextExtractor
@@ -74,19 +74,19 @@ class OpenAiSpeechToTextExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed configuration model.
         :rtype: OpenAiSpeechToTextExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency or required environment is missing.
+        :raises ExtractionSnapshotFatalError: If the optional dependency or required environment is missing.
         """
         try:
             from openai import OpenAI  # noqa: F401
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "OpenAI speech to text extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[openai]".'
             ) from import_error
 
         api_key = resolve_openai_api_key()
         if api_key is None:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "OpenAI speech to text extractor requires an OpenAI API key. "
                 "Set OPENAI_API_KEY or configure it in ~/.biblicus/config.yml or ./.biblicus/config.yml under "
                 "openai.api_key."
@@ -115,7 +115,7 @@ class OpenAiSpeechToTextExtractor(TextExtractor):
         :type previous_extractions: list[biblicus.models.ExtractionStepOutput]
         :return: Extracted text payload, or None when the item is not audio.
         :rtype: ExtractedText or None
-        :raises ExtractionRunFatalError: If the optional dependency or required configuration is missing.
+        :raises ExtractionSnapshotFatalError: If the optional dependency or required configuration is missing.
         """
         _ = previous_extractions
         if not item.media_type.startswith("audio/"):
@@ -129,7 +129,7 @@ class OpenAiSpeechToTextExtractor(TextExtractor):
 
         api_key = resolve_openai_api_key()
         if api_key is None:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "OpenAI speech to text extractor requires an OpenAI API key. "
                 "Set OPENAI_API_KEY or configure it in ~/.biblicus/config.yml or ./.biblicus/config.yml under "
                 "openai.api_key."
@@ -138,7 +138,7 @@ class OpenAiSpeechToTextExtractor(TextExtractor):
         try:
             from openai import OpenAI
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "OpenAI speech to text extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[openai]".'
             ) from import_error

biblicus/extractors/paddleocr_vl_text.py

@@ -16,7 +16,7 @@ from typing import Any, ClassVar, Dict, List, Optional, Tuple
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..inference import ApiProvider, InferenceBackendConfig, InferenceBackendMode, resolve_api_key
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
@@ -26,8 +26,8 @@ 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 retriever: Inference retriever configuration for local or application programming interface execution.
+    :vartype retriever: InferenceBackendConfig
     :ivar min_confidence: Minimum confidence threshold for including text.
     :vartype min_confidence: float
     :ivar joiner: String used to join recognized text lines.
@@ -38,9 +38,11 @@ class PaddleOcrVlExtractorConfig(BaseModel):
     :vartype lang: str
     """
 
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
-    backend: InferenceBackendConfig = Field(default_factory=InferenceBackendConfig)
+    retriever: InferenceBackendConfig = Field(
+        default_factory=InferenceBackendConfig, alias="backend"
+    )
     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)
@@ -70,7 +72,7 @@ class PaddleOcrVlExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed configuration model.
         :rtype: PaddleOcrVlExtractorConfig
-        :raises ExtractionRunFatalError: If required dependencies are missing.
+        :raises ExtractionSnapshotFatalError: If required dependencies are missing.
         """
         import json
 
@@ -86,26 +88,26 @@ class PaddleOcrVlExtractor(TextExtractor):
 
         parsed = PaddleOcrVlExtractorConfig.model_validate(parsed_config)
 
-        if parsed.backend.mode == InferenceBackendMode.LOCAL:
+        if parsed.retriever.mode == InferenceBackendMode.LOCAL:
             try:
                 from paddleocr import PaddleOCR  # noqa: F401
             except ImportError as import_error:
-                raise ExtractionRunFatalError(
+                raise ExtractionSnapshotFatalError(
                     "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,
+                parsed.retriever.api_provider,
+                config_override=parsed.retriever.api_key,
             )
             if api_key is None:
-                provider_name = parsed.backend.api_provider.value.upper()
-                raise ExtractionRunFatalError(
+                provider_name = parsed.retriever.api_provider.value.upper()
+                raise ExtractionSnapshotFatalError(
                     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."
+                    f"{parsed.retriever.api_provider.value} in user config."
                 )
 
         return parsed
@@ -145,12 +147,12 @@ class PaddleOcrVlExtractor(TextExtractor):
 
         source_path = corpus.root / item.relpath
 
-        if parsed_config.backend.mode == InferenceBackendMode.LOCAL:
+        if parsed_config.retriever.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,
+                parsed_config.retriever.api_provider,
+                config_override=parsed_config.retriever.api_key,
             )
             text, confidence = self._extract_via_api(source_path, parsed_config, api_key)
 
@@ -228,7 +230,7 @@ class PaddleOcrVlExtractor(TextExtractor):
         :return: Tuple of extracted text and confidence score.
         :rtype: tuple[str, float or None]
         """
-        if config.backend.api_provider == ApiProvider.HUGGINGFACE:
+        if config.retriever.api_provider == ApiProvider.HUGGINGFACE:
             return self._extract_via_huggingface_api(source_path, config, api_key)
         else:
             return "", None
@@ -257,7 +259,7 @@ class PaddleOcrVlExtractor(TextExtractor):
 
         headers = {"Authorization": f"Bearer {api_key}"}
 
-        model_id = config.backend.model_id or "PaddlePaddle/PaddleOCR-VL"
+        model_id = config.retriever.model_id or "PaddlePaddle/PaddleOCR-VL"
         api_url = f"https://api-inference.huggingface.co/models/{model_id}"
         response = requests.post(
             api_url,

biblicus/extractors/pipeline.py

@@ -9,7 +9,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
 
@@ -20,14 +20,14 @@ class PipelineStepSpec(BaseModel):
 
     :ivar extractor_id: Extractor plugin identifier.
     :vartype extractor_id: str
-    :ivar config: Extractor configuration mapping.
-    :vartype config: dict[str, Any]
+    :ivar configuration: Extractor configuration mapping.
+    :vartype configuration: dict[str, Any]
     """
 
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
     extractor_id: str = Field(min_length=1)
-    config: Dict[str, Any] = Field(default_factory=dict)
+    configuration: Dict[str, Any] = Field(default_factory=dict, alias="config")
 
 
 class PipelineExtractorConfig(BaseModel):
@@ -92,7 +92,7 @@ class PipelineExtractor(TextExtractor):
         :type config: PipelineExtractorConfig
         :param previous_extractions: Prior step outputs for this item within the pipeline.
         :type previous_extractions: list[biblicus.models.ExtractionStepOutput]
-        :raises ExtractionRunFatalError: Always, because the pipeline is executed by the runner.
+        :raises ExtractionSnapshotFatalError: Always, because the pipeline is executed by the runner.
         :return: None.
         :rtype: None
         """
@@ -100,6 +100,6 @@ class PipelineExtractor(TextExtractor):
         _ = item
         _ = config
         _ = previous_extractions
-        raise ExtractionRunFatalError(
-            "Pipeline extractor must be executed by the extraction runner."
+        raise ExtractionSnapshotFatalError(
+            "Pipeline extractor must be executed by the extraction snapshotner."
         )

biblicus/extractors/rapidocr_text.py

@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
 
@@ -54,12 +54,12 @@ class RapidOcrExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed configuration model.
         :rtype: RapidOcrExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency is missing.
+        :raises ExtractionSnapshotFatalError: If the optional dependency is missing.
         """
         try:
             from rapidocr_onnxruntime import RapidOCR  # noqa: F401
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "RapidOCR extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[ocr]".'
             ) from import_error

biblicus/extractors/unstructured_text.py

@@ -11,7 +11,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict
 
 from ..corpus import Corpus
-from ..errors import ExtractionRunFatalError
+from ..errors import ExtractionSnapshotFatalError
 from ..models import CatalogItem, ExtractedText, ExtractionStepOutput
 from .base import TextExtractor
 
@@ -48,12 +48,12 @@ class UnstructuredExtractor(TextExtractor):
         :type config: dict[str, Any]
         :return: Parsed config.
         :rtype: UnstructuredExtractorConfig
-        :raises ExtractionRunFatalError: If the optional dependency is not installed.
+        :raises ExtractionSnapshotFatalError: If the optional dependency is not installed.
         """
         try:
             from unstructured.partition.auto import partition  # noqa: F401
         except ImportError as import_error:
-            raise ExtractionRunFatalError(
+            raise ExtractionSnapshotFatalError(
                 "Unstructured extractor requires an optional dependency. "
                 'Install it with pip install "biblicus[unstructured]".'
             ) from import_error

biblicus/hooks.py

@@ -18,8 +18,8 @@ class HookPoint(str, Enum):
     :cvar after_ingest: Called after an item is ingested and indexed.
     :cvar before_reindex: Called before a catalog rebuild starts.
     :cvar after_reindex: Called after a catalog rebuild completes.
-    :cvar before_build_run: Called before a backend run build starts.
-    :cvar after_build_run: Called after a backend run build completes.
+    :cvar before_build_snapshot: Called before a retriever snapshot build starts.
+    :cvar after_build_snapshot: Called after a retriever snapshot build completes.
     :cvar before_query: Called before a query is executed.
     :cvar after_query: Called after a query completes.
     :cvar before_evaluate_run: Called before an evaluation starts.
@@ -30,8 +30,8 @@ class HookPoint(str, Enum):
     after_ingest = "after_ingest"
     before_reindex = "before_reindex"
     after_reindex = "after_reindex"
-    before_build_run = "before_build_run"
-    after_build_run = "after_build_run"
+    before_build_snapshot = "before_build_snapshot"
+    after_build_snapshot = "after_build_snapshot"
     before_query = "before_query"
     after_query = "after_query"
     before_evaluate_run = "before_evaluate_run"