biblicus 0.10.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biblicus
-Version: 0.10.0
+Version: 0.11.0
 Summary: Command line interface and Python library for corpus ingestion, retrieval, and evaluation.
 License: MIT
 Requires-Python: >=3.9
@@ -493,6 +493,12 @@ Two backends are included.
 
 For detailed documentation including configuration options, performance characteristics, and usage examples, see the [Backend Reference][backend-reference].
 
+## Retrieval documentation
+
+For the retrieval pipeline overview and run artifacts, see `docs/RETRIEVAL.md`. For retrieval quality upgrades
+(tuned lexical baseline, reranking, hybrid retrieval), see `docs/RETRIEVAL_QUALITY.md`. For evaluation workflows
+and dataset formats, see `docs/RETRIEVAL_EVALUATION.md`.
+
 ## Extraction backends
 
 These extractors are built in. Optional ones require extra dependencies. See [text extraction documentation][text-extraction] for details.

{biblicus-0.10.0 → biblicus-0.11.0}/README.md

@@ -447,6 +447,12 @@ Two backends are included.
 
 For detailed documentation including configuration options, performance characteristics, and usage examples, see the [Backend Reference][backend-reference].
 
+## Retrieval documentation
+
+For the retrieval pipeline overview and run artifacts, see `docs/RETRIEVAL.md`. For retrieval quality upgrades
+(tuned lexical baseline, reranking, hybrid retrieval), see `docs/RETRIEVAL_QUALITY.md`. For evaluation workflows
+and dataset formats, see `docs/RETRIEVAL_EVALUATION.md`.
+
 ## Extraction backends
 
 These extractors are built in. Optional ones require extra dependencies. See [text extraction documentation][text-extraction] for details.

{biblicus-0.10.0 → biblicus-0.11.0}/docs/ARCHITECTURE.md

@@ -88,11 +88,11 @@ Evidence is the canonical output of retrieval. Required fields:
 ### Integration boundary
 
 - Biblicus can integrate with Tactus as a **Model Context Protocol toolset**, for example with tool names such as `knowledge_base_ingest`, `knowledge_base_query`, and `knowledge_base_stats`.
-- We will **not** add a knowledge base or retrieval augmented generation language primitive in version zero. Revisit only if we need semantics that tools cannot express cleanly, such as enforceable policy boundaries, runtime managed durability, caching hooks, or guaranteed instrumentation.
+- We do **not** add a knowledge base or retrieval augmented generation language primitive in version zero. Revisit only if we need semantics that tools cannot express cleanly, such as enforceable policy boundaries, runtime managed durability, caching hooks, or guaranteed instrumentation.
 
 ### Interface packaging
 
-- The knowledge base interface is a **small protocol and reference implementation**, including tool schemas and a reference Model Context Protocol server. We will not build a full managed service in version zero.
+- The knowledge base interface is a **small protocol and reference implementation**, including tool schemas and a reference Model Context Protocol server. We do not build a full managed service in version zero.
 
 ### Corpus identity and layout
 
@@ -143,7 +143,7 @@ The interface stays the same; topology is configuration.
 - When a backend produces persisted materializations, Biblicus treats them as **versioned build runs** identified by `run_id` (rather than overwriting in place by default).
 - Manifests exist even for just-in-time backends (materializations may be empty).
 - Full directed acyclic graph lineage is not included in version zero; revisit only if needed.
-- Future (optional): define **shared materialization formats** (canonical chunk and embedding stores) so multiple backends can reuse intermediates when it makes sense; keep it opt-in.
+- Optional: define **shared materialization formats** (canonical chunk and embedding stores) so multiple backends can reuse intermediates when it makes sense; keep it opt-in.
 
 ### Evaluation
 
@@ -156,7 +156,7 @@ The interface stays the same; topology is configuration.
 - The corpus catalog is **file-based** (committable, portable, backend-agnostic) so any backend/tool can consume it without requiring a database engine.
 - Canonical version zero format is a single JavaScript Object Notation file at `.biblicus/catalog.json`, written atomically (temporary file and rename) on updates.
 - The catalog includes `latest_run_id` and run manifests are stored at `.biblicus/runs/<run_id>.json`.
-- If this ever becomes a bottleneck at very large scales, we will **change the specification** (bump `schema_version`) rather than introduce multiple “supported” catalog storage modes.
+- If this becomes a bottleneck at very large scales, we **change the specification** (bump `schema_version`) rather than introduce multiple “supported” catalog storage modes.
 
 ## Near-term deliverables
 

{biblicus-0.10.0 → biblicus-0.11.0}/docs/CORPUS_DESIGN.md

@@ -216,7 +216,7 @@ Version zero locked this as policy. A prune workflow was not implemented yet.
 
 Goal: retain derived artifacts from multiple implementations side by side so a user can compare results and switch between implementations without losing work.
 
-This decision applies to extraction plugins and retrieval backends, and to any future plugin type that produces derived artifacts.
+This decision applies to extraction plugins and retrieval backends, and to any plugin type that produces derived artifacts.
 
 Option A: store artifacts under the corpus, partitioned by plugin type
 
@@ -369,7 +369,7 @@ Version zero implemented option A by writing structured log entries for hook exe
 
 ## Outcomes and remaining questions
 
-The hook protocol and hook logging policy above were implemented in version zero. This section records what was implemented, plus the questions that remain for future iterations.
+The hook protocol and hook logging policy above were implemented in version zero. This section records what was implemented and the open questions tracked for later iterations.
 
 ### Hook contexts implemented in version zero
 

{biblicus-0.10.0 → biblicus-0.11.0}/docs/DEMOS.md

@@ -6,7 +6,7 @@ For the ordered plan of what to build next, see `docs/ROADMAP.md`.
 
 ## Diagram of the current system and the next layers
 
-Blue boxes are implemented now. Purple boxes are planned next layers that we can build and compare.
+Blue boxes are implemented now. Purple boxes are layers not implemented yet that we can build and compare.
 
 ```mermaid
 %%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 18, "rankSpacing": 22}}}%%
@@ -233,7 +233,7 @@ python3 -m biblicus extract build --corpus corpora/demo \\
   --step select-text
 ```
 
-Copy the `run_id` from the JavaScript Object Notation output. You will use it as `EXTRACTION_RUN_ID` in the next command.
+Copy the `run_id` from the JavaScript Object Notation output. Use it as `EXTRACTION_RUN_ID` in the next command.
 
 ```
 python3 -m biblicus build --corpus corpora/demo --backend sqlite-full-text-search \\
@@ -251,7 +251,7 @@ python3 scripts/download_pdf_samples.py --corpus corpora/pdf_samples --force
 python3 -m biblicus extract build --corpus corpora/pdf_samples --step pdf-text
 ```
 
-Copy the `run_id` from the JavaScript Object Notation output. You will use it as `PDF_EXTRACTION_RUN_ID` in the next command.
+Copy the `run_id` from the JavaScript Object Notation output. Use it as `PDF_EXTRACTION_RUN_ID` in the next command.
 
 ```
 python3 -m biblicus build --corpus corpora/pdf_samples --backend sqlite-full-text-search --config extraction_run=pipeline:PDF_EXTRACTION_RUN_ID --config chunk_size=200 --config chunk_overlap=50 --config snippet_characters=120

biblicus-0.11.0/docs/RETRIEVAL.md

@@ -0,0 +1,47 @@
+# Retrieval
+
+Biblicus treats retrieval as a reproducible, explicit pipeline stage that transforms a corpus into structured evidence.
+Retrieval is separated from extraction and context shaping so each can be evaluated independently and swapped without
+rewriting ingestion.
+
+## Retrieval concepts
+
+- **Backend**: a pluggable retrieval implementation that can build and query runs.
+- **Run**: a recorded retrieval build for a corpus and extraction run.
+- **Evidence**: structured output containing identifiers, provenance, and scores.
+- **Stage**: explicit steps such as retrieve, rerank, and filter.
+
+## How retrieval runs work
+
+1) Ingest raw items into a corpus.
+2) Build an extraction run to produce text artifacts.
+3) Build a retrieval run with a backend, referencing the extraction run.
+4) Query the run to return evidence.
+
+Retrieval runs are stored under:
+
+```
+.biblicus/runs/retrieval/<backend_id>/<run_id>/
+```
+
+## Backends
+
+See `docs/backends/index.md` for backend selection and configuration.
+
+## Evaluation
+
+Retrieval runs are evaluated against datasets with explicit budgets. See `docs/RETRIEVAL_EVALUATION.md` for the
+dataset format and workflow, `docs/FEATURE_INDEX.md` for the behavior specifications, and `docs/CONTEXT_PACK.md` for
+how evidence feeds into context packs.
+
+## Why the separation matters
+
+Keeping extraction and retrieval distinct makes it possible to:
+
+- Reuse the same extracted artifacts across many retrieval backends.
+- Compare backends against the same corpus and dataset inputs.
+- Record and audit retrieval decisions without mixing in prompting or context formatting.
+
+## Retrieval quality
+
+For retrieval quality upgrades, see `docs/RETRIEVAL_QUALITY.md`.

biblicus-0.11.0/docs/RETRIEVAL_EVALUATION.md

@@ -0,0 +1,74 @@
+# Retrieval evaluation
+
+Biblicus evaluates retrieval runs against deterministic datasets so quality comparisons are repeatable across backends
+and corpora. Evaluations keep the evidence-first model intact by reporting per-query evidence alongside summary
+metrics.
+
+## Dataset format
+
+Retrieval datasets are stored as JavaScript Object Notation files with a strict schema:
+
+```json
+{
+  "schema_version": 1,
+  "name": "example-dataset",
+  "description": "Small hand-labeled dataset for smoke tests.",
+  "queries": [
+    {
+      "query_id": "q-001",
+      "query_text": "alpha",
+      "expected_item_id": "item-id-123",
+      "kind": "gold"
+    }
+  ]
+}
+```
+
+Each query includes either an `expected_item_id` or an `expected_source_uri`. The `kind` field records whether the
+query is hand-labeled (`gold`) or synthetic.
+
+## Running an evaluation
+
+Use the command-line interface to evaluate a retrieval run against a dataset:
+
+```bash
+biblicus eval --corpus corpora/example --run <run_id> --dataset datasets/retrieval.json \
+  --max-total-items 5 --max-total-characters 2000 --max-items-per-source 5
+```
+
+If `--run` is omitted, the latest retrieval run is used. Evaluations are deterministic for the same corpus, run, and
+budget.
+
+## Output
+
+The evaluation output includes:
+
+- Dataset metadata (name, description, query count).
+- Run metadata (backend ID, run ID, evaluation timestamp).
+- Metrics (hit rate, precision-at-k, mean reciprocal rank).
+- System diagnostics (latency percentiles and index size).
+
+The output is JavaScript Object Notation suitable for downstream reporting.
+
+## Python usage
+
+```python
+from pathlib import Path
+
+from biblicus.corpus import Corpus
+from biblicus.evaluation import evaluate_run, load_dataset
+from biblicus.models import QueryBudget
+
+corpus = Corpus.open("corpora/example")
+run = corpus.load_run("<run_id>")
+dataset = load_dataset(Path("datasets/retrieval.json"))
+budget = QueryBudget(max_total_items=5, max_total_characters=2000, max_items_per_source=5)
+result = evaluate_run(corpus=corpus, run=run, dataset=dataset, budget=budget)
+print(result.model_dump_json(indent=2))
+```
+
+## Design notes
+
+- Evaluation is reproducible by construction: the run manifest, dataset, and budget fully determine the results.
+- The evaluation workflow expects retrieval stages to remain explicit in the run artifacts.
+- Reports are portable, so comparisons across backends and corpora are straightforward.

biblicus-0.11.0/docs/RETRIEVAL_QUALITY.md

@@ -0,0 +1,42 @@
+# 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`.
+
+## Goals
+
+- Improve relevance without losing determinism or reproducibility.
+- Keep retrieval stages explicit and visible in run artifacts.
+- Preserve the evidence-first output model.
+
+## Available upgrades
+
+### 1) Tuned lexical baseline
+
+- BM25-style scoring with configurable parameters.
+- N-gram range controls.
+- Stop word strategy per backend.
+- Field weighting (for example: title, body, metadata).
+
+### 2) Reranking stage
+
+- Optional rerank step that re-scores top-N candidates.
+- Deterministic scoring keeps rerank behavior reproducible.
+
+### 3) Hybrid retrieval
+
+- Combine lexical and embedding signals.
+- Expose fusion weights in the recipe schema.
+- Emit stage-level scores and weights in evidence metadata.
+
+## Evaluation guidance
+
+- Measure accuracy-at-k and compare against the same datasets.
+- Run artifacts capture each stage and configuration for auditability.
+- Deterministic settings remain available as the default baseline.
+
+## Non-goals
+
+- Automated hyperparameter tuning.
+- Hidden fallback stages that obscure retrieval behavior.
+- UI-driven tuning in this phase.

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

@@ -31,6 +31,21 @@ 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:
+
+- 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.
+
 ## Next: context pack policy surfaces
 
 Goal: make context shaping policies easier to evaluate and swap.
@@ -67,7 +82,6 @@ Goal: provide lightweight analysis utilities that summarize corpus themes and gu
 
 Deliverables:
 
-- Basic data profiling reports (counts, media types, size distributions, tag coverage).
 - Hidden Markov modeling analysis for sequence-driven corpora.
 - A way to compare analysis outputs across corpora or corpus snapshots.
 

{biblicus-0.10.0 → biblicus-0.11.0}/docs/extractors/text-document/pass-through.md

@@ -120,12 +120,12 @@ title: My Document
 tags: [note, draft]
 ---
 
-This is the body content that will be extracted.
+This is the body content that is extracted.
 ```
 
 Output text:
 ```
-This is the body content that will be extracted.
+This is the body content that is extracted.
 ```
 
 ### Mixed Format Pipeline
@@ -185,7 +185,7 @@ Non-text items are silently skipped (returns `None`). This allows the extractor
 
 ### Encoding Errors
 
-UTF-8 decoding errors will cause per-item failures recorded in `errored_items` but won't halt the entire extraction run.
+UTF-8 decoding errors cause per-item failures recorded in `errored_items` but do not halt the entire extraction run.
 
 ### Missing Files
 

{biblicus-0.10.0 → biblicus-0.11.0}/docs/extractors/text-document/unstructured.md

@@ -78,7 +78,7 @@ class UnstructuredExtractorConfig(BaseModel):
 
 ### Configuration Options
 
-This extractor currently accepts no configuration. Future versions may expose Unstructured library options.
+This extractor currently accepts no configuration. Optional extensions may expose Unstructured library options.
 
 ## Usage
 

{biblicus-0.10.0 → biblicus-0.11.0}/docs/index.rst

@@ -15,6 +15,9 @@ Contents
    KNOWLEDGE_BASE
    BACKENDS
    backends/index
+   RETRIEVAL
+   RETRIEVAL_QUALITY
+   RETRIEVAL_EVALUATION
    CONTEXT_PACK
    ANALYSIS
    PROFILING

biblicus-0.11.0/features/retrieval_quality.feature

@@ -0,0 +1,253 @@
+Feature: Retrieval quality upgrades
+  Retrieval quality upgrades keep multi-stage retrieval explicit while improving relevance.
+
+  Scenario: Lexical tuning parameters are recorded in the retrieval recipe
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha bravo charlie"
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I build a "sqlite-full-text-search" retrieval run in corpus "corpus" with config:
+      | key                | value |
+      | chunk_size         | 200   |
+      | chunk_overlap      | 50    |
+      | snippet_characters | 120   |
+      | bm25_k1            | 1.2   |
+      | bm25_b             | 0.75  |
+      | ngram_min          | 1     |
+      | ngram_max          | 2     |
+      | stop_words         | english |
+      | field_weight_title | 2.0   |
+      | field_weight_body  | 1.0   |
+      | field_weight_tags  | 0.5   |
+    Then the latest run recipe config includes:
+      | key                | value |
+      | bm25_k1            | 1.2   |
+      | bm25_b             | 0.75  |
+      | ngram_min          | 1     |
+      | ngram_max          | 2     |
+      | stop_words         | english |
+      | field_weight_title | 2.0   |
+      | field_weight_body  | 1.0   |
+      | field_weight_tags  | 0.5   |
+
+  Scenario: Lexical tuning rejects invalid ngram ranges
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "sqlite-full-text-search" retrieval run in corpus "corpus" with config:
+      | key       | value |
+      | ngram_min | 2     |
+      | ngram_max | 1     |
+    Then the command fails with exit code 2
+    And standard error includes "ngram range"
+
+  Scenario: Stop words exclude common tokens from lexical retrieval
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "the zebra"
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I build a "sqlite-full-text-search" retrieval run in corpus "corpus" with config:
+      | key        | value |
+      | stop_words | english |
+    And I query with the latest run for "the" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the query evidence count is 0
+
+  Scenario: Reranking produces explicit stage metadata
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha bravo charlie"
+    And a text file "beta.md" exists with contents "alpha beta charlie"
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I ingest the file "beta.md" into corpus "corpus"
+    And I build a "sqlite-full-text-search" retrieval run in corpus "corpus" with config:
+      | key                 | value |
+      | rerank_enabled      | true  |
+      | rerank_model        | cross-encoder |
+      | rerank_top_k        | 2     |
+    And I query with the latest run for "alpha" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the query returns evidence with stage "rerank"
+    And the query evidence includes stage score "retrieve"
+    And the query evidence includes stage score "rerank"
+    And the query stats include reranked_candidates 2
+
+  Scenario: Hybrid retrieval records lexical and embedding scores
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha bravo charlie"
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I build a "hybrid" retrieval run in corpus "corpus" with config:
+      | key              | value |
+      | lexical_backend  | sqlite-full-text-search |
+      | embedding_backend| vector |
+      | lexical_weight   | 0.7   |
+      | embedding_weight | 0.3   |
+    And I query with the latest run for "alpha" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the query returns evidence with stage "hybrid"
+    And the query evidence includes stage score "lexical"
+    And the query evidence includes stage score "embedding"
+    And the query stats include fusion_weights "lexical=0.7,embedding=0.3"
+
+  Scenario: Hybrid retrieval rejects invalid weights
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "hybrid" retrieval run in corpus "corpus" with config:
+      | key              | value |
+      | lexical_weight   | 0.9   |
+      | embedding_weight | 0.9   |
+    Then the command fails with exit code 2
+    And standard error includes "weights must sum to 1"
+
+  Scenario: SQLite stop words reject invalid strings
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "sqlite-full-text-search" retrieval run in corpus "corpus" with config:
+      | key        | value   |
+      | stop_words | spanish |
+    Then the command fails with exit code 2
+    And standard error includes "stop_words"
+
+  Scenario: SQLite stop words accept explicit lists
+    When I validate sqlite full-text search stop words list:
+      | value |
+      | the   |
+      | and   |
+    Then the sqlite stop words include "the"
+
+  Scenario: SQLite stop words reject empty lists
+    When I attempt to validate sqlite full-text search stop words list:
+      | value |
+    Then a model validation error is raised
+    And the validation error mentions "stop_words list must not be empty"
+
+  Scenario: SQLite stop words reject empty entries
+    When I attempt to validate sqlite full-text search stop words list:
+      | value |
+      |       |
+    Then a model validation error is raised
+    And the validation error mentions "stop_words list must contain non-empty strings"
+
+  Scenario: Rerank requires a model identifier
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "sqlite-full-text-search" retrieval run in corpus "corpus" with config:
+      | key            | value |
+      | rerank_enabled | true  |
+    Then the command fails with exit code 2
+    And standard error includes "rerank_model"
+
+  Scenario: Vector retrieval returns evidence
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha bravo"
+    And a text file "plain.txt" exists with contents "alpha plain"
+    And a text file "delta.md" exists with contents "delta"
+    And a text file "punct.md" exists with contents "!!!"
+    And a binary file "data.bin" exists
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I ingest the file "plain.txt" into corpus "corpus"
+    And I ingest the file "delta.md" into corpus "corpus"
+    And I ingest the file "punct.md" into corpus "corpus"
+    And I ingest the file "data.bin" into corpus "corpus"
+    And I build a "vector" retrieval run in corpus "corpus"
+    And I query with the latest run for "alpha" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the query returns evidence with stage "vector"
+
+  Scenario: Vector retrieval handles longer queries
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha"
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I build a "vector" retrieval run in corpus "corpus"
+    And I query with the latest run for "alpha bravo charlie" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the query returns evidence with stage "vector"
+
+  Scenario: Vector retrieval ignores empty queries
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha"
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I build a "vector" retrieval run in corpus "corpus"
+    And I query with the latest run for "!!!" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the query evidence count is 0
+
+  Scenario: Vector retrieval uses extracted text
+    Given I initialized a corpus at "corpus"
+    And a text file "alpha.md" exists with contents "alpha bravo"
+    And a text file "whitespace.txt" exists with contents "   "
+    And a binary file "data.bin" exists
+    When I ingest the file "alpha.md" into corpus "corpus"
+    And I ingest the file "whitespace.txt" into corpus "corpus"
+    And I ingest the file "data.bin" into corpus "corpus"
+    And I build a "pass-through-text" extraction run in corpus "corpus"
+    And I build a "vector" retrieval run in corpus "corpus" using the latest extraction run and config:
+      | key                | value |
+      | snippet_characters | 120   |
+    And I query with the latest run for "alpha" and budget:
+      | key                  | value |
+      | max_total_items      | 5     |
+      | max_total_characters | 2000  |
+      | max_items_per_source | 5     |
+    Then the latest run stats include text_items 2
+
+  Scenario: Vector retrieval rejects missing extraction runs
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "vector" retrieval run in corpus "corpus" with extraction run "missing:run"
+    Then the command fails with exit code 2
+    And standard error includes "Missing extraction run"
+
+  Scenario: Vector snippet helpers handle missing spans
+    When I compute a vector match span for text "alpha" with tokens "beta"
+    Then the vector match span is None
+    And the vector snippet for text "alpha" with span "None" and max chars 5 equals "alpha"
+
+  Scenario: Vector match spans ignore empty tokens
+    When I compute a vector match span for text "alpha" with tokens "alpha,,beta"
+    Then the vector match span is "0..5"
+
+  Scenario: Vector match spans prefer earlier tokens
+    When I compute a vector match span for text "alpha beta" with tokens "beta,alpha"
+    Then the vector match span is "0..5"
+
+  Scenario: Vector match spans ignore later tokens
+    When I compute a vector match span for text "alpha beta" with tokens "alpha,beta"
+    Then the vector match span is "0..5"
+
+  Scenario: Vector snippet helpers handle empty text
+    When I compute a vector match span for text "<empty>" with tokens "alpha"
+    Then the vector match span is None
+    And the vector snippet for text "<empty>" with span "None" and max chars 5 equals "<empty>"
+
+  Scenario: Hybrid backend rejects nested lexical backends
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "hybrid" retrieval run in corpus "corpus" with config:
+      | key             | value |
+      | lexical_backend | hybrid |
+    Then the command fails with exit code 2
+    And standard error includes "lexical"
+
+  Scenario: Hybrid backend rejects nested embedding backends
+    Given I initialized a corpus at "corpus"
+    When I attempt to build a "hybrid" retrieval run in corpus "corpus" with config:
+      | key              | value |
+      | lexical_backend  | sqlite-full-text-search |
+      | embedding_backend| hybrid |
+    Then the command fails with exit code 2
+    And standard error includes "embedding"
+
+  Scenario: Hybrid query requires component runs
+    Given I initialized a corpus at "corpus"
+    When I attempt to query a hybrid run without component runs
+    Then a model validation error is raised
+    And the validation error mentions "Hybrid run missing lexical or embedding run identifiers"