biblicus 0.16.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.py

@@ -25,6 +25,8 @@ class ContextPackPolicy(BaseModel):
     :vartype ordering: str
     :ivar include_metadata: Whether to include evidence metadata lines in each block.
     :vartype include_metadata: bool
+    :ivar metadata_fields: Optional evidence metadata fields to include.
+    :vartype metadata_fields: list[str] or None
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -32,6 +34,7 @@ class ContextPackPolicy(BaseModel):
     join_with: str = Field(default="\n\n")
     ordering: str = Field(default="rank", min_length=1)
     include_metadata: bool = Field(default=False)
+    metadata_fields: Optional[List[str]] = None
 
 
 class ContextPack(BaseModel):
@@ -132,7 +135,9 @@ def build_context_pack(result: RetrievalResult, *, policy: ContextPackPolicy) ->
         trimmed_text = evidence.text.strip()
         if not trimmed_text:
             continue
-        metadata = _metadata_for_evidence(evidence) if policy.include_metadata else None
+        metadata = (
+            _metadata_for_evidence(evidence, policy=policy) if policy.include_metadata else None
+        )
         block_text = _format_block_text(trimmed_text, metadata=metadata)
         selected_blocks.append(
             ContextPackBlock(
@@ -276,7 +281,11 @@ def _order_evidence(
     raise ValueError(f"Unknown context pack ordering: {policy.ordering}")
 
 
-def _metadata_for_evidence(evidence: Evidence) -> Dict[str, object]:
+def _metadata_for_evidence(
+    evidence: Evidence,
+    *,
+    policy: ContextPackPolicy,
+) -> Dict[str, object]:
     """
     Build metadata for a context pack block.
 
@@ -285,12 +294,19 @@ def _metadata_for_evidence(evidence: Evidence) -> Dict[str, object]:
     :return: Metadata mapping.
     :rtype: dict[str, object]
     """
-    return {
+    metadata = {
         "item_id": evidence.item_id,
         "source_uri": evidence.source_uri or "none",
         "score": evidence.score,
         "stage": evidence.stage,
     }
+    extra = evidence.metadata or {}
+    if policy.metadata_fields is not None:
+        extra = {key: extra.get(key) for key in policy.metadata_fields if key in extra}
+    for key, value in extra.items():
+        if key not in metadata:
+            metadata[key] = value
+    return metadata
 
 
 def _format_block_text(text: str, *, metadata: Optional[Dict[str, object]]) -> str:
@@ -306,12 +322,11 @@ def _format_block_text(text: str, *, metadata: Optional[Dict[str, object]]) -> s
     """
     if not metadata:
         return text
-    metadata_lines = "\n".join(
-        [
-            f"item_id: {metadata['item_id']}",
-            f"source_uri: {metadata['source_uri']}",
-            f"score: {metadata['score']}",
-            f"stage: {metadata['stage']}",
-        ]
-    )
-    return f"{metadata_lines}\n{text}"
+    ordered_keys = ["item_id", "source_uri", "score", "stage"]
+    metadata_lines = [f"{key}: {metadata[key]}" for key in ordered_keys if key in metadata]
+    for key in sorted(metadata.keys()):
+        if key in ordered_keys:
+            continue
+        metadata_lines.append(f"{key}: {metadata[key]}")
+    metadata_text = "\n".join(metadata_lines)
+    return f"{metadata_text}\n{text}"

biblicus/context_engine/__init__.py

@@ -0,0 +1,53 @@
+"""
+Public interface for the Biblicus Context Engine.
+"""
+
+from .assembler import ContextAssembler, ContextAssemblyResult
+from .compaction import BaseCompactor, CompactionRequest, SummaryCompactor, TruncateCompactor
+from .models import (
+    AssistantMessageSpec,
+    CompactorDeclaration,
+    ContextBudgetSpec,
+    ContextDeclaration,
+    ContextExpansionSpec,
+    ContextInsertSpec,
+    ContextMessageSpec,
+    ContextPackBudgetSpec,
+    ContextPackSpec,
+    ContextPolicySpec,
+    ContextRetrieverRequest,
+    ContextTemplateSpec,
+    CorpusDeclaration,
+    HistoryInsertSpec,
+    RetrieverDeclaration,
+    SystemMessageSpec,
+    UserMessageSpec,
+)
+from .retrieval import retrieve_context_pack
+
+__all__ = [
+    "ContextAssembler",
+    "ContextAssemblyResult",
+    "BaseCompactor",
+    "CompactionRequest",
+    "SummaryCompactor",
+    "TruncateCompactor",
+    "ContextBudgetSpec",
+    "ContextDeclaration",
+    "ContextExpansionSpec",
+    "ContextInsertSpec",
+    "ContextMessageSpec",
+    "ContextPackBudgetSpec",
+    "ContextPackSpec",
+    "ContextPolicySpec",
+    "ContextRetrieverRequest",
+    "ContextTemplateSpec",
+    "CorpusDeclaration",
+    "RetrieverDeclaration",
+    "CompactorDeclaration",
+    "HistoryInsertSpec",
+    "SystemMessageSpec",
+    "UserMessageSpec",
+    "AssistantMessageSpec",
+    "retrieve_context_pack",
+]