biblicus 0.11.0__tar.gz → 0.12.0__tar.gz

{biblicus-0.11.0/src/biblicus.egg-info → biblicus-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biblicus
-Version: 0.11.0
+Version: 0.12.0
 Summary: Command line interface and Python library for corpus ingestion, retrieval, and evaluation.
 License: MIT
 Requires-Python: >=3.9

{biblicus-0.11.0 → biblicus-0.12.0}/docs/CONTEXT_PACK.md

@@ -23,13 +23,49 @@ context_pack = build_context_pack(result, policy=policy)
 print(context_pack.text)
 ```
 
+## Policy surfaces
+
+Context pack policies make ordering and formatting explicit.
+
+### Ordering
+
+Use `ordering` to control how evidence blocks are arranged before joining:
+
+- `rank`: use the evidence rank as provided by retrieval.
+- `score`: sort by score (descending) and then item identifier.
+- `source`: group by source uniform resource identifier, then sort by score.
+
+### Metadata inclusion
+
+Set `include_metadata=True` to prepend metadata to each block. Metadata includes:
+
+- `item_id`
+- `source_uri`
+- `score`
+- `stage`
+
+### Character budgets
+
+Character budgets drop trailing blocks until the context pack fits the specified limit. This keeps context shaping
+deterministic without relying on a tokenizer.
+
+In Python:
+
+```python
+from biblicus.context import CharacterBudget, ContextPackPolicy, fit_context_pack_to_character_budget
+
+policy = ContextPackPolicy(join_with="\n\n", ordering="score", include_metadata=True)
+fitted = fit_context_pack_to_character_budget(context_pack, policy=policy, character_budget=CharacterBudget(max_characters=500))
+print(fitted.text)
+```
+
 ## Command-line interface
 
 The command-line interface can build a context pack from a retrieval result by reading JavaScript Object Notation from standard input.
 
 ```bash
 biblicus query --corpus corpora/example --query "primary button style preference" \\
-  | biblicus context-pack build
+  | biblicus context-pack build --ordering score --include-metadata --max-characters 500
 ```
 
 ## What context pack building does

{biblicus-0.11.0 → biblicus-0.12.0}/docs/FEATURE_INDEX.md

@@ -204,6 +204,7 @@ Documentation:
 Behavior specifications:
 
 - `features/context_pack.feature`
+- `features/context_pack_policies.feature`
 - `features/token_budget.feature`
 
 Primary implementation:

{biblicus-0.11.0 → biblicus-0.12.0}/docs/RETRIEVAL_QUALITY.md

@@ -1,7 +1,7 @@
 # Retrieval quality upgrades
 
 This document describes the retrieval quality upgrades available in Biblicus. It is a reference for how retrieval
-quality is expressed in runs and should be read alongside `docs/ROADMAP.md`.
+quality is expressed in runs and how to interpret the signals in artifacts and evidence.
 
 ## Goals
 

{biblicus-0.11.0 → biblicus-0.12.0}/docs/ROADMAP.md

@@ -17,49 +17,27 @@ If you are looking for what already exists, start with:
 - Raw corpus items remain readable, portable files.
 - Derived artifacts are stored under the corpus and can coexist for multiple implementations.
 
-## Next: retrieval evaluation and datasets
+## Completed foundations
 
-Goal: make evaluation results easier to interpret and compare.
+These are the capability slices that already exist and have end-to-end behavior specifications.
 
-Deliverables:
-
-- A dataset authoring workflow that supports small hand-labeled sets and larger synthetic sets.
-- A report that includes per-query diagnostics and a clear summary.
-
-Acceptance checks:
-
-- Dataset formats are versioned when they change.
-- Reports remain deterministic for the same inputs.
-
-## Next: retrieval quality upgrades
-
-Goal: make retrieval relevance stronger while keeping deterministic baselines and clear evaluation.
-
-Deliverables:
-
-- A tuned lexical baseline (for example: BM25 configuration, n-grams, field weighting, stop word controls).
-- A reranking stage that can refine top-N results with either a cross-encoder or an LLM re-ranker.
-- A hybrid retrieval mode that combines lexical signals with embeddings and exposes weights explicitly.
-
-Acceptance checks:
+### Retrieval evaluation and datasets
 
-- Accuracy-at-k improves on the same evaluation datasets without regressions in determinism.
-- Retrieval stages are explicitly recorded (retrieve, rerank, filter) in the output artifacts.
+- Dataset authoring workflow for small hand-labeled sets and larger synthetic sets.
+- Evaluation reports with per-query diagnostics and summary metrics.
+- Versioned dataset formats and deterministic reports for stable inputs.
 
-## Next: context pack policy surfaces
+### Retrieval quality upgrades
 
-Goal: make context shaping policies easier to evaluate and swap.
+- Tuned lexical baseline with BM25, n-gram range controls, and stop word policies.
+- Reranking stage for top-N candidates with explicit stage metadata.
+- Hybrid retrieval with explicit fusion weights and stage-level scores.
 
-Deliverables:
-
-- A clear set of context pack policy variants (formatting, ordering, metadata inclusion).
-- Token budget strategies that can use a real tokenizer.
-- Documentation that explains where context shaping fits in the pipeline.
-
-Acceptance checks:
+### Context pack policy surfaces
 
-- Behavior specifications cover policy selection and budgeting behaviors.
-- Example outputs show how context packs differ across policies.
+- Policy variants for formatting, ordering, and metadata inclusion.
+- Token and character budget strategies with explicit selectors.
+- Documentation and examples that show how policy choices change outputs.
 
 ## Next: extraction evaluation harness
 
@@ -82,6 +60,7 @@ Goal: provide lightweight analysis utilities that summarize corpus themes and gu
 
 Deliverables:
 
+- Basic corpus profiling with deterministic metrics for raw items and extracted text.
 - Hidden Markov modeling analysis for sequence-driven corpora.
 - A way to compare analysis outputs across corpora or corpus snapshots.
 

{biblicus-0.11.0 → biblicus-0.12.0}/features/context_pack_cli.feature

@@ -23,6 +23,31 @@ Feature: Context pack command-line interface
       one two three
       """
 
+  Scenario: Context pack build can include metadata
+    Given a retrieval result exists with sourced evidence:
+      | source_uri | score | text  |
+      | source-a   | 10.0  | alpha |
+    When I run "context-pack build" joining with "\n\n" ordering "score" and including metadata
+    Then the context pack build output text equals:
+      """
+      item_id: item-1
+      source_uri: source-a
+      score: 10.0
+      stage: scan
+      alpha
+      """
+
+  Scenario: Context pack build can fit to a character budget
+    Given a retrieval result exists with evidence text:
+      | text |
+      | alpha |
+      | beta |
+    When I run "context-pack build" joining with "\n\n" and character budget 6
+    Then the context pack build output text equals:
+      """
+      alpha
+      """
+
   Scenario: Context pack build fails without retrieval result on standard input
     When I run "context-pack build" with empty standard input
     Then the command fails with exit code 2

biblicus-0.12.0/features/context_pack_policies.feature

@@ -0,0 +1,92 @@
+Feature: Context pack policies
+  Context pack policies control evidence ordering, metadata inclusion, and budgets.
+
+  Scenario: Score ordering sorts evidence by score
+    Given a retrieval result exists with scored evidence:
+      | score | text  |
+      | 1.0   | beta  |
+      | 5.0   | alpha |
+    When I build a context pack from that retrieval result with policy:
+      | key              | value |
+      | join_with        | \n\n |
+      | ordering         | score |
+      | include_metadata | false |
+    Then the context pack text equals:
+      """
+      alpha
+
+      beta
+      """
+
+  Scenario: Source ordering groups evidence by source
+    Given a retrieval result exists with sourced evidence:
+      | source_uri | score | text  |
+      | source-b   | 1.0   | beta  |
+      | source-a   | 2.0   | alpha |
+      | source-a   | 1.0   | delta |
+    When I build a context pack from that retrieval result with policy:
+      | key              | value |
+      | join_with        | \n\n |
+      | ordering         | source |
+      | include_metadata | false |
+    Then the context pack text equals:
+      """
+      alpha
+
+      delta
+
+      beta
+      """
+
+  Scenario: Metadata inclusion prepends block metadata
+    Given a retrieval result exists with sourced evidence:
+      | source_uri | score | text  |
+      | source-a   | 10.0  | alpha |
+    When I build a context pack from that retrieval result with policy:
+      | key              | value |
+      | join_with        | \n\n |
+      | ordering         | rank |
+      | include_metadata | true |
+    Then the context pack text equals:
+      """
+      item_id: item-1
+      source_uri: source-a
+      score: 10.0
+      stage: scan
+      alpha
+      """
+
+  Scenario: Character budgets drop trailing blocks
+    Given a retrieval result exists with evidence text:
+      | text |
+      | alpha |
+      | beta |
+    When I build a context pack from that retrieval result with policy:
+      | key              | value |
+      | join_with        | \n\n |
+      | ordering         | rank |
+      | include_metadata | false |
+    And I fit the context pack to a character budget of 6 characters
+    Then the context pack text equals:
+      """
+      alpha
+      """
+
+  Scenario: Character budgets can produce empty context packs
+    Given a retrieval result exists with evidence text:
+      | text |
+      | alpha |
+    When I build a context pack from that retrieval result with policy:
+      | key              | value |
+      | join_with        | \n\n |
+      | ordering         | rank |
+      | include_metadata | false |
+    And I fit the context pack to a character budget of 1 characters
+    Then the context pack text is empty
+
+  Scenario: Unknown ordering raises a policy error
+    Given a retrieval result exists with evidence text:
+      | text |
+      | alpha |
+    When I attempt to build a context pack with invalid ordering "mystery"
+    Then the context pack ordering error mentions "Unknown context pack ordering"

{biblicus-0.11.0 → biblicus-0.12.0}/features/steps/cli_steps.py

@@ -97,6 +97,57 @@ def step_context_pack_build_with_token_budget_from_standard_input(
     context.context_pack_build_output = json.loads(result.stdout)
 
 
+@when(
+    'I run "context-pack build" joining with "{join_with}" ordering "{ordering}" and including metadata'
+)
+def step_context_pack_build_with_metadata_from_standard_input(
+    context, join_with: str, ordering: str
+) -> None:
+    decoded_join_with = bytes(join_with, "utf-8").decode("unicode_escape")
+    retrieval_result_json = context.retrieval_result.model_dump_json(indent=2)
+    result = run_biblicus(
+        context,
+        [
+            "context-pack",
+            "build",
+            "--join-with",
+            decoded_join_with,
+            "--ordering",
+            ordering,
+            "--include-metadata",
+        ],
+        input_text=retrieval_result_json,
+    )
+    context.last_result = result
+    assert result.returncode == 0, result.stderr
+    context.context_pack_build_output = json.loads(result.stdout)
+
+
+@when(
+    'I run "context-pack build" joining with "{join_with}" and character budget {max_characters:d}'
+)
+def step_context_pack_build_with_character_budget_from_standard_input(
+    context, join_with: str, max_characters: int
+) -> None:
+    decoded_join_with = bytes(join_with, "utf-8").decode("unicode_escape")
+    retrieval_result_json = context.retrieval_result.model_dump_json(indent=2)
+    result = run_biblicus(
+        context,
+        [
+            "context-pack",
+            "build",
+            "--join-with",
+            decoded_join_with,
+            "--max-characters",
+            str(max_characters),
+        ],
+        input_text=retrieval_result_json,
+    )
+    context.last_result = result
+    assert result.returncode == 0, result.stderr
+    context.context_pack_build_output = json.loads(result.stdout)
+
+
 @when('I run "context-pack build" with empty standard input')
 def step_context_pack_build_with_empty_standard_input(context) -> None:
     result = run_biblicus(context, ["context-pack", "build", "--join-with", "\n\n"], input_text="")

{biblicus-0.11.0 → biblicus-0.12.0}/features/steps/context_pack_steps.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 from behave import given, then, when
 
 from biblicus.context import (
+    CharacterBudget,
     ContextPackPolicy,
     TokenBudget,
     build_context_pack,
+    fit_context_pack_to_character_budget,
     fit_context_pack_to_token_budget,
 )
 from biblicus.models import Evidence, QueryBudget, RetrievalResult
@@ -80,6 +82,41 @@ def given_retrieval_result_exists_with_scored_evidence(context) -> None:
     )
 
 
+@given("a retrieval result exists with sourced evidence:")
+def given_retrieval_result_exists_with_sourced_evidence(context) -> None:
+    evidence_items = []
+    for rank_value, row in enumerate(context.table, start=1):
+        score_value = float(row["score"])
+        source_uri_value = row["source_uri"]
+        text_value = row["text"]
+        content_ref_value = None if str(text_value).strip() else "content-ref"
+        evidence_items.append(
+            Evidence(
+                item_id=f"item-{rank_value}",
+                source_uri=source_uri_value,
+                media_type="text/plain",
+                score=score_value,
+                rank=rank_value,
+                text=text_value,
+                content_ref=content_ref_value,
+                stage="scan",
+                recipe_id="recipe",
+                run_id="run",
+            )
+        )
+
+    context.retrieval_result = RetrievalResult(
+        query_text="query",
+        budget=QueryBudget(max_total_items=10),
+        run_id="run",
+        recipe_id="recipe",
+        backend_id="scan",
+        generated_at=utc_now_iso(),
+        evidence=evidence_items,
+        stats={},
+    )
+
+
 @given("the second evidence item has no text payload")
 def given_second_evidence_item_has_no_text_payload(context) -> None:
     context.retrieval_result.evidence[1] = context.retrieval_result.evidence[1].model_copy(
@@ -96,6 +133,31 @@ def when_build_context_pack_from_retrieval_result(context, join_with: str) -> No
     )
 
 
+@when("I build a context pack from that retrieval result with policy:")
+def when_build_context_pack_from_retrieval_result_with_policy(context) -> None:
+    settings = {}
+    for row in context.table:
+        if "key" in row.headings and "value" in row.headings:
+            key = row["key"]
+            value = row["value"]
+        else:
+            key = row[0]
+            value = row[1]
+        settings[str(key).strip()] = str(value).strip()
+    join_with_raw = settings.get("join_with", "\\n\\n")
+    ordering = settings.get("ordering", "rank")
+    include_metadata = settings.get("include_metadata", "false").lower() == "true"
+    decoded_join_with = bytes(join_with_raw, "utf-8").decode("unicode_escape")
+    context.context_pack_policy = ContextPackPolicy(
+        join_with=decoded_join_with,
+        ordering=ordering,
+        include_metadata=include_metadata,
+    )
+    context.context_pack = build_context_pack(
+        context.retrieval_result, policy=context.context_pack_policy
+    )
+
+
 @then("the context pack text equals:")
 def then_context_pack_text_equals(context) -> None:
     assert context.context_pack.text == context.text
@@ -110,6 +172,32 @@ def when_fit_context_pack_to_token_budget(context, max_tokens: int) -> None:
     )
 
 
+@when("I fit the context pack to a character budget of {max_characters:d} characters")
+def when_fit_context_pack_to_character_budget(context, max_characters: int) -> None:
+    context.context_pack = fit_context_pack_to_character_budget(
+        context.context_pack,
+        policy=context.context_pack_policy,
+        character_budget=CharacterBudget(max_characters=max_characters),
+    )
+
+
+@when('I attempt to build a context pack with invalid ordering "{ordering}"')
+def when_attempt_build_context_pack_with_invalid_ordering(context, ordering: str) -> None:
+    policy = ContextPackPolicy(join_with="\n\n").model_copy(update={"ordering": ordering})
+    try:
+        _ = build_context_pack(context.retrieval_result, policy=policy)
+        context.ordering_error = None
+    except ValueError as exc:
+        context.ordering_error = exc
+
+
+@then('the context pack ordering error mentions "{message}"')
+def then_context_pack_ordering_error_mentions(context, message: str) -> None:
+    error = getattr(context, "ordering_error", None)
+    assert error is not None
+    assert message in str(error)
+
+
 @then("the context pack text is empty")
 def then_context_pack_text_is_empty(context) -> None:
     assert context.context_pack.text == ""

{biblicus-0.11.0 → biblicus-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "biblicus"
-version = "0.11.0"
+version = "0.12.0"
 description = "Command line interface and Python library for corpus ingestion, retrieval, and evaluation."
 readme = "README.md"
 requires-python = ">=3.9"

{biblicus-0.11.0 → biblicus-0.12.0}/src/biblicus/__init__.py

@@ -27,4 +27,4 @@ __all__ = [
     "RetrievalRun",
 ]
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"

{biblicus-0.11.0 → biblicus-0.12.0}/src/biblicus/cli.py

@@ -15,9 +15,11 @@ from pydantic import ValidationError
 from .analysis import get_analysis_backend
 from .backends import get_backend
 from .context import (
+    CharacterBudget,
     ContextPackPolicy,
     TokenBudget,
     build_context_pack,
+    fit_context_pack_to_character_budget,
     fit_context_pack_to_token_budget,
 )
 from .corpus import Corpus
@@ -568,7 +570,11 @@ def cmd_context_pack_build(arguments: argparse.Namespace) -> int:
         )
     retrieval_result = RetrievalResult.model_validate_json(input_text)
     join_with = bytes(arguments.join_with, "utf-8").decode("unicode_escape")
-    policy = ContextPackPolicy(join_with=join_with)
+    policy = ContextPackPolicy(
+        join_with=join_with,
+        ordering=arguments.ordering,
+        include_metadata=arguments.include_metadata,
+    )
     context_pack = build_context_pack(retrieval_result, policy=policy)
     if arguments.max_tokens is not None:
         context_pack = fit_context_pack_to_token_budget(
@@ -576,6 +582,12 @@ def cmd_context_pack_build(arguments: argparse.Namespace) -> int:
             policy=policy,
             token_budget=TokenBudget(max_tokens=int(arguments.max_tokens)),
         )
+    if arguments.max_characters is not None:
+        context_pack = fit_context_pack_to_character_budget(
+            context_pack,
+            policy=policy,
+            character_budget=CharacterBudget(max_characters=int(arguments.max_characters)),
+        )
     print(
         json.dumps(
             {
@@ -921,12 +933,29 @@ def build_parser() -> argparse.ArgumentParser:
         default="\\n\\n",
         help="Separator between evidence blocks (escape sequences supported, default is two newlines).",
     )
+    p_context_pack_build.add_argument(
+        "--ordering",
+        choices=["rank", "score", "source"],
+        default="rank",
+        help="Evidence ordering policy (rank, score, source).",
+    )
+    p_context_pack_build.add_argument(
+        "--include-metadata",
+        action="store_true",
+        help="Include evidence metadata in each context pack block.",
+    )
     p_context_pack_build.add_argument(
         "--max-tokens",
         default=None,
         type=int,
         help="Optional token budget for the final context pack using the naive-whitespace tokenizer.",
     )
+    p_context_pack_build.add_argument(
+        "--max-characters",
+        default=None,
+        type=int,
+        help="Optional character budget for the final context pack.",
+    )
     p_context_pack_build.set_defaults(func=cmd_context_pack_build)
 
     p_eval = sub.add_parser("eval", help="Evaluate a run against a dataset.")