biblicus 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

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"

biblicus/knowledge_base.py

@@ -11,7 +11,6 @@ from typing import List, Optional, Sequence
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from .backends import get_backend
 from .context import (
     ContextPack,
     ContextPackPolicy,
@@ -20,17 +19,18 @@ from .context import (
     fit_context_pack_to_token_budget,
 )
 from .corpus import Corpus
-from .models import QueryBudget, RetrievalResult, RetrievalRun
+from .models import QueryBudget, RetrievalResult, RetrievalSnapshot
+from .retrievers import get_retriever
 
 
 class KnowledgeBaseDefaults(BaseModel):
     """
     Default configuration for a knowledge base workflow.
 
-    :ivar backend_id: Backend identifier to use for retrieval.
-    :vartype backend_id: str
-    :ivar recipe_name: Human-readable retrieval recipe name.
-    :vartype recipe_name: str
+    :ivar retriever_id: Retriever identifier to use for retrieval.
+    :vartype retriever_id: str
+    :ivar configuration_name: Human-readable retrieval configuration name.
+    :vartype configuration_name: str
     :ivar query_budget: Default query budget to apply to retrieval.
     :vartype query_budget: QueryBudget
     :ivar tags: Tags to apply when importing the folder.
@@ -39,8 +39,8 @@ class KnowledgeBaseDefaults(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    backend_id: str = Field(default="scan", min_length=1)
-    recipe_name: str = Field(default="Knowledge base", min_length=1)
+    retriever_id: str = Field(default="scan", min_length=1)
+    configuration_name: str = Field(default="Knowledge base", min_length=1)
     query_budget: QueryBudget = Field(
         default_factory=lambda: QueryBudget(
             max_total_items=5,
@@ -58,17 +58,17 @@ class KnowledgeBase:
 
     :ivar corpus: Corpus instance that stores the ingested items.
     :vartype corpus: Corpus
-    :ivar backend_id: Backend identifier used for retrieval.
-    :vartype backend_id: str
-    :ivar run: Retrieval run manifest associated with the knowledge base.
-    :vartype run: RetrievalRun
+    :ivar retriever_id: Retriever identifier used for retrieval.
+    :vartype retriever_id: str
+    :ivar snapshot: Retrieval snapshot manifest associated with the knowledge base.
+    :vartype snapshot: RetrievalSnapshot
     :ivar defaults: Default configuration used for this knowledge base.
     :vartype defaults: KnowledgeBaseDefaults
     """
 
     corpus: Corpus
-    backend_id: str
-    run: RetrievalRun
+    retriever_id: str
+    snapshot: RetrievalSnapshot
     defaults: KnowledgeBaseDefaults
     _temp_dir: Optional[TemporaryDirectory]
 
@@ -77,8 +77,8 @@ class KnowledgeBase:
         cls,
         folder: str | Path,
         *,
-        backend_id: Optional[str] = None,
-        recipe_name: Optional[str] = None,
+        retriever_id: Optional[str] = None,
+        configuration_name: Optional[str] = None,
         query_budget: Optional[QueryBudget] = None,
         tags: Optional[Sequence[str]] = None,
         corpus_root: Optional[str | Path] = None,
@@ -88,10 +88,10 @@ class KnowledgeBase:
 
         :param folder: Folder containing source files.
         :type folder: str or Path
-        :param backend_id: Optional backend identifier override.
-        :type backend_id: str or None
-        :param recipe_name: Optional recipe name override.
-        :type recipe_name: str or None
+        :param retriever_id: Optional retriever identifier override.
+        :type retriever_id: str or None
+        :param configuration_name: Optional configuration name override.
+        :type configuration_name: str or None
         :param query_budget: Optional query budget override.
         :type query_budget: QueryBudget or None
         :param tags: Optional tags to apply during import.
@@ -110,8 +110,8 @@ class KnowledgeBase:
             raise NotADirectoryError(f"Knowledge base folder is not a directory: {source_root}")
 
         defaults = KnowledgeBaseDefaults()
-        resolved_backend_id = backend_id or defaults.backend_id
-        resolved_recipe_name = recipe_name or defaults.recipe_name
+        resolved_retriever_id = retriever_id or defaults.retriever_id
+        resolved_configuration_name = configuration_name or defaults.configuration_name
         resolved_query_budget = query_budget or defaults.query_budget
         resolved_tags = list(tags) if tags is not None else defaults.tags
 
@@ -125,16 +125,18 @@ class KnowledgeBase:
         corpus = Corpus.init(corpus_root_path)
         corpus.import_tree(source_root, tags=resolved_tags)
 
-        backend = get_backend(resolved_backend_id)
-        run = backend.build_run(corpus, recipe_name=resolved_recipe_name, config={})
+        retriever = get_retriever(resolved_retriever_id)
+        snapshot = retriever.build_snapshot(
+            corpus, configuration_name=resolved_configuration_name, configuration={}
+        )
 
         return cls(
             corpus=corpus,
-            backend_id=resolved_backend_id,
-            run=run,
+            retriever_id=resolved_retriever_id,
+            snapshot=snapshot,
             defaults=KnowledgeBaseDefaults(
-                backend_id=resolved_backend_id,
-                recipe_name=resolved_recipe_name,
+                retriever_id=resolved_retriever_id,
+                configuration_name=resolved_configuration_name,
                 query_budget=resolved_query_budget,
                 tags=resolved_tags,
             ),
@@ -152,11 +154,11 @@ class KnowledgeBase:
         :return: Retrieval result containing evidence.
         :rtype: RetrievalResult
         """
-        backend = get_backend(self.backend_id)
+        retriever = get_retriever(self.retriever_id)
         resolved_budget = budget or self.defaults.query_budget
-        return backend.query(
+        return retriever.query(
             self.corpus,
-            run=self.run,
+            snapshot=self.snapshot,
             query_text=query_text,
             budget=resolved_budget,
         )