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

biblicus/{recipes.py → configuration.py}

@@ -1,5 +1,5 @@
 """
-Recipe loading utilities for Biblicus.
+Configuration loading utilities for Biblicus.
 """
 
 from __future__ import annotations
@@ -103,34 +103,34 @@ def apply_dotted_overrides(
     return updated
 
 
-def load_recipe_view(
-    recipe_paths: Iterable[str],
+def load_configuration_view(
+    configuration_paths: Iterable[str],
     *,
-    recipe_label: str = "Recipe",
+    configuration_label: str = "Configuration",
     mapping_error_message: Optional[str] = None,
 ) -> Dict[str, object]:
     """
-    Load a composed recipe view from one or more YAML files.
+    Load a composed configuration view from one or more YAML files.
 
-    :param recipe_paths: Iterable of recipe file paths in precedence order.
-    :type recipe_paths: Iterable[str]
-    :param recipe_label: Label used in error messages (for example: "Recipe file").
-    :type recipe_label: str
+    :param configuration_paths: Iterable of configuration file paths in precedence order.
+    :type configuration_paths: Iterable[str]
+    :param configuration_label: Label used in error messages (for example: "Configuration file").
+    :type configuration_label: str
     :return: Composed configuration view.
     :rtype: dict[str, object]
-    :raises FileNotFoundError: If any recipe file is missing.
-    :raises ValueError: If any recipe file is not a mapping/object.
+    :raises FileNotFoundError: If any configuration file is missing.
+    :raises ValueError: If any configuration file is not a mapping/object.
     """
     from biblicus._vendor.dotyaml import load_yaml_view
 
-    paths: List[str] = [str(path) for path in recipe_paths]
+    paths: List[str] = [str(path) for path in configuration_paths]
     for raw in paths:
         candidate = Path(raw)
         if not candidate.is_file():
-            raise FileNotFoundError(f"{recipe_label} not found: {candidate}")
+            raise FileNotFoundError(f"{configuration_label} not found: {candidate}")
     try:
         view = load_yaml_view(paths)
     except ValueError as exc:
-        message = mapping_error_message or f"{recipe_label} must be a mapping/object"
+        message = mapping_error_message or f"{configuration_label} must be a mapping/object"
         raise ValueError(message) from exc
     return view

biblicus/constants.py

@@ -9,7 +9,7 @@ ANALYSIS_SCHEMA_VERSION = 1
 CORPUS_DIR_NAME = ".biblicus"
 DEFAULT_RAW_DIR = "raw"
 SIDECAR_SUFFIX = ".biblicus.yml"
-RUNS_DIR_NAME = "runs"
-EXTRACTION_RUNS_DIR_NAME = "extraction"
+SNAPSHOTS_DIR_NAME = "snapshots"
+EXTRACTION_SNAPSHOTS_DIR_NAME = "extraction"
 ANALYSIS_RUNS_DIR_NAME = "analysis"
 HOOK_LOGS_DIR_NAME = "hook_logs"

biblicus/context_engine/assembler.py

@@ -403,13 +403,15 @@ class ContextAssembler:
         maximum_items_per_source = None
         include_metadata = False
         metadata_fields = None
-        backend_id = None
+        retriever_id = None
         corpus_root = None
-        run_id = None
-        recipe_name = None
-        recipe_config = None
+        snapshot_id = None
+        configuration_name = None
+        configuration = None
         corpus_name = getattr(retriever_spec, "corpus", None)
         join_with = "\n\n"
+        pipeline_config = None
+        query_config = None
 
         if isinstance(config, dict):
             split = config.get("split", split)
@@ -424,13 +426,26 @@ class ContextAssembler:
             )
             include_metadata = config.get("include_metadata", include_metadata)
             metadata_fields = config.get("metadata_fields", metadata_fields)
-            backend_id = config.get("backend_id", backend_id)
-            run_id = config.get("run_id", run_id)
-            recipe_name = config.get("recipe_name", recipe_name)
-            recipe_config = config.get("recipe_config", config.get("recipe", recipe_config))
+            retriever_id = config.get("retriever_id", retriever_id)
+            snapshot_id = config.get("snapshot_id", snapshot_id)
+            configuration_name = config.get("configuration_name", configuration_name)
+            if isinstance(config.get("configuration"), dict):
+                configuration = config.get("configuration")
             corpus_name = config.get("corpus", corpus_name)
             join_with = config.get("join_with", join_with)
-
+            if isinstance(configuration, dict):
+                pipeline_config = configuration.get("pipeline")
+            if not isinstance(pipeline_config, dict) and isinstance(config.get("pipeline"), dict):
+                pipeline_config = config.get("pipeline")
+            if isinstance(pipeline_config, dict):
+                if isinstance(pipeline_config.get("query"), dict):
+                    query_config = pipeline_config.get("query") or {}
+                if configuration is None and isinstance(pipeline_config.get("index"), dict):
+                    configuration = pipeline_config.get("index") or {}
+            if configuration is None and isinstance(config.get("index"), dict):
+                configuration = config.get("index") or {}
+            if configuration is None and isinstance(pipeline_config, dict):
+                configuration = pipeline_config.get("index") or {}
         if corpus_name and corpus_name in self._corpus_registry:
             corpus_spec = self._corpus_registry[corpus_name]
             corpus_config = corpus_spec.config if hasattr(corpus_spec, "config") else {}
@@ -442,17 +457,32 @@ class ContextAssembler:
                 maximum_cache_total_characters = corpus_config.get(
                     "maximum_cache_total_characters", maximum_cache_total_characters
                 )
-                backend_id = corpus_config.get("backend_id", backend_id)
                 corpus_root = corpus_config.get(
                     "corpus_root",
                     corpus_config.get("root", corpus_root),
                 )
-                run_id = corpus_config.get("run_id", run_id)
-                recipe_name = corpus_config.get("recipe_name", recipe_name)
-                recipe_config = corpus_config.get(
-                    "recipe_config",
-                    corpus_config.get("recipe", recipe_config),
+        if query_config:
+            if "limit" in query_config:
+                limit = query_config.get("limit", limit)
+            if "offset" in query_config:
+                offset = query_config.get("offset", offset)
+            if "maximum_total_characters" in query_config:
+                maximum_total_characters = query_config.get(
+                    "maximum_total_characters", maximum_total_characters
+                )
+            if "maximum_items_per_source" in query_config:
+                maximum_items_per_source = query_config.get(
+                    "maximum_items_per_source",
+                    maximum_items_per_source,
                 )
+            if "max_items_per_source" in query_config and maximum_items_per_source is None:
+                maximum_items_per_source = query_config.get("max_items_per_source")
+            if "include_metadata" in query_config:
+                include_metadata = query_config.get("include_metadata", include_metadata)
+            if "metadata_fields" in query_config:
+                metadata_fields = query_config.get("metadata_fields", metadata_fields)
+            if "join_with" in query_config:
+                join_with = query_config.get("join_with", join_with)
 
         allocated_tokens = self._allocate_pack_budget(pack_budget, policy, weight)
         if allocated_tokens is not None:
@@ -486,11 +516,11 @@ class ContextAssembler:
                 "maximum_items_per_source": maximum_items_per_source,
                 "include_metadata": include_metadata,
                 "metadata_fields": metadata_fields,
-                "backend_id": backend_id,
+                "retriever_id": retriever_id,
                 "corpus_root": corpus_root,
-                "run_id": run_id,
-                "recipe_name": recipe_name,
-                "recipe_config": recipe_config,
+                "snapshot_id": snapshot_id,
+                "configuration_name": configuration_name,
+                "configuration": configuration,
             },
         )
         context_pack = self._retrieve_with_expansion(

biblicus/context_engine/retrieval.py

@@ -6,7 +6,6 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
-from biblicus.backends import get_backend
 from biblicus.context import (
     ContextPack,
     ContextPackPolicy,
@@ -15,67 +14,72 @@ from biblicus.context import (
     fit_context_pack_to_token_budget,
 )
 from biblicus.corpus import Corpus
-from biblicus.models import QueryBudget, RetrievalRun
+from biblicus.models import QueryBudget, RetrievalSnapshot
+from biblicus.retrievers import get_retriever
 
 from .models import ContextRetrieverRequest
 
 
-def _resolve_run(
+def _resolve_snapshot(
     corpus: Corpus,
     *,
-    backend_id: str,
-    run_id: Optional[str],
-    recipe_name: Optional[str],
-    recipe_config: Optional[dict[str, Any]],
-) -> RetrievalRun:
-    if run_id:
-        return corpus.load_run(run_id)
+    retriever_id: str,
+    snapshot_id: Optional[str],
+    configuration_name: Optional[str],
+    configuration: Optional[dict[str, Any]],
+) -> RetrievalSnapshot:
+    if snapshot_id:
+        return corpus.load_snapshot(snapshot_id)
 
-    latest_run_id = corpus.latest_run_id
-    if latest_run_id:
-        candidate = corpus.load_run(latest_run_id)
-        if candidate.recipe.backend_id == backend_id:
+    latest_snapshot_id = corpus.latest_snapshot_id
+    if latest_snapshot_id:
+        candidate = corpus.load_snapshot(latest_snapshot_id)
+        if candidate.configuration.retriever_id == retriever_id:
             return candidate
 
-    if recipe_config is None:
+    if configuration is None:
         raise ValueError(
-            "No retrieval run available for the requested backend. "
-            "Provide run_id or recipe_config to build one."
+            "No retrieval snapshot available for the requested retriever. "
+            "Provide snapshot_id or configuration to build one."
         )
 
-    backend = get_backend(backend_id)
-    resolved_name = recipe_name or f"Context pack ({backend_id})"
-    return backend.build_run(corpus, recipe_name=resolved_name, config=recipe_config)
+    retriever = get_retriever(retriever_id)
+    resolved_name = configuration_name or f"Context pack ({retriever_id})"
+    return retriever.build_snapshot(
+        corpus,
+        configuration_name=resolved_name,
+        configuration=configuration,
+    )
 
 
 def retrieve_context_pack(
     *,
     request: ContextRetrieverRequest,
     corpus: Corpus,
-    backend_id: str,
-    run_id: Optional[str] = None,
-    recipe_name: Optional[str] = None,
-    recipe_config: Optional[dict[str, Any]] = None,
+    retriever_id: str,
+    snapshot_id: Optional[str] = None,
+    configuration_name: Optional[str] = None,
+    configuration: Optional[dict[str, Any]] = None,
     join_with: str = "\n\n",
     max_items_per_source: Optional[int] = None,
     include_metadata: bool = False,
     metadata_fields: Optional[list[str]] = None,
 ) -> ContextPack:
     """
-    Retrieve a context pack using a Biblicus backend.
+    Retrieve a context pack using a Biblicus retriever.
 
     :param request: Context retrieval request.
     :type request: biblicus.context_engine.ContextRetrieverRequest
     :param corpus: Corpus instance to query.
     :type corpus: biblicus.corpus.Corpus
-    :param backend_id: Retrieval backend identifier.
-    :type backend_id: str
-    :param run_id: Optional retrieval run identifier.
-    :type run_id: str or None
-    :param recipe_name: Optional recipe name for run builds.
-    :type recipe_name: str or None
-    :param recipe_config: Optional backend recipe configuration.
-    :type recipe_config: dict[str, Any] or None
+    :param retriever_id: Retrieval retriever identifier.
+    :type retriever_id: str
+    :param snapshot_id: Optional retrieval snapshot identifier.
+    :type snapshot_id: str or None
+    :param configuration_name: Optional configuration name for snapshot builds.
+    :type configuration_name: str or None
+    :param configuration: Optional retriever configuration.
+    :type configuration: dict[str, Any] or None
     :param join_with: Separator between context pack blocks.
     :type join_with: str
     :param max_items_per_source: Optional cap per source.
@@ -86,14 +90,14 @@ def retrieve_context_pack(
     :type metadata_fields: list[str] or None
     :return: Context pack derived from retrieval results.
     :rtype: biblicus.context.ContextPack
-    :raises ValueError: If no compatible retrieval run is available.
+    :raises ValueError: If no compatible retrieval snapshot is available.
     """
-    run = _resolve_run(
+    snapshot = _resolve_snapshot(
         corpus,
-        backend_id=backend_id,
-        run_id=run_id,
-        recipe_name=recipe_name,
-        recipe_config=recipe_config,
+        retriever_id=retriever_id,
+        snapshot_id=snapshot_id,
+        configuration_name=configuration_name,
+        configuration=configuration,
     )
 
     maximum_total_characters = request.maximum_total_characters
@@ -106,10 +110,10 @@ def retrieve_context_pack(
         maximum_total_characters=maximum_total_characters,
         max_items_per_source=max_items_per_source,
     )
-    backend = get_backend(backend_id)
-    result = backend.query(
+    retriever = get_retriever(retriever_id)
+    result = retriever.query(
         corpus,
-        run=run,
+        snapshot=snapshot,
         query_text=request.query,
         budget=budget,
     )