rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/parsing.py

@@ -0,0 +1,286 @@
+"""Parsing capability (FR-C.1): source documents -> a clean structured representation, parsed once.
+
+Docling's `DocumentConverter` turns a PDF, Office file, or scan into a `DoclingDocument` (reading
+order, headings, sections, tables, OCR). Parsing is content-hash gated so a document is parsed once
+and reused by chunking, embedding, and extraction: the structured representation is cached as JSON
+(`DoclingDocument.save_as_json` / `load_from_json`) keyed by the source's content hash, so re-parsing
+unchanged content is a cache hit and changed content re-parses.
+
+The `DocumentConverter` sits behind a small `Parser` seam so the capability's cache/gate logic is
+tested hermetically with a stub, and the real (model-loading) parse is exercised opt-in (`-m parse`).
+Grounded against `docling.document_converter.DocumentConverter.convert` and
+`docling_core.types.doc.document.DoclingDocument` (framework graph).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from docling_core.types.doc.document import DoclingDocument
+from pydantic import BaseModel, field_validator
+
+from rag_wright.contracts.identifiers import canonical_source_doc_id
+
+# Reused from the ChunkId scheme (T1): the delimiter-safe charset for a source_doc_id, so the id is
+# citation/provenance-safe and consistent with `chunk_id`.
+_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+@runtime_checkable
+class Parser(Protocol):
+    """The document-conversion seam: turn a source path into a `DoclingDocument`."""
+
+    def convert(self, source: Path) -> DoclingDocument: ...
+
+
+class ParsedDocument(BaseModel):
+    """The parsing capability's contract: a handle to the cached structured representation.
+
+    The full `DoclingDocument` lives in the parse manifest at `manifest_path` (loaded via
+    `load_document`); this record carries the identity and the content hash the pipeline gates on.
+    """
+
+    model_config = {"frozen": True}
+
+    source_doc_id: str
+    content_hash: str  # sha256 hex of the source bytes
+    manifest_path: str
+
+    @field_validator("source_doc_id")
+    @classmethod
+    def _safe_source_doc_id(cls, v: str) -> str:
+        if not v or _SAFE.search(v):
+            raise ValueError("source_doc_id must be non-empty and use only [A-Za-z0-9._-]")
+        return v
+
+
+class DoclingParser:
+    """The real parser: Docling's `DocumentConverter`. Constructed lazily so importing the capability
+    (and the hermetic tests) does not load Docling's models."""
+
+    def __init__(self) -> None:
+        from docling.document_converter import DocumentConverter
+
+        self._converter = DocumentConverter()
+
+    def convert(self, source: Path) -> DoclingDocument:
+        return self._converter.convert(source).document
+
+    def parse_range(self, source: Path, page_range: tuple[int, int]) -> DoclingDocument:
+        """PARSE-3: parse only pages `page_range` (1-based, inclusive) -- lets the tiered path fast-parse the
+        born-digital pages and VLM only the degraded ones, then concatenate, instead of VLM-ing the whole doc."""
+        return self._converter.convert(source, page_range=page_range).document
+
+
+class TieredOCRReport(BaseModel):
+    """0009-WIRE: which pages the tiered parser escalated to the VLM, and which remained unreadable even after
+    the VLM (genuine info loss -> the caller should flag PARTIAL / needs-rescan)."""
+
+    escalated_pages: list[int] = []
+    unreadable_pages: list[int] = []
+
+
+class TieredOCRParser:
+    """0009-WIRE: fast OCR -> scan-quality gate -> VLM escalation for degraded pages -> PARTIAL for what the VLM
+    still cannot read. A `Parser`, so it drops into `parse(..., parser=TieredOCRParser())` unchanged.
+
+    Benchmark (docs/eval/ocr_benchmark.md): fast OCR is perfect on readable scans and worthless on a heavily
+    degraded one (char_sim ~0.01); a VLM reads the degraded-but-readable scan (Gemma-4 0.991). So: run the cheap
+    fast parse, and ONLY when a page's OCR is untrustworthy re-parse via the VLM (whole-document escalation --
+    the VLM reads good pages fine too, so this is safe and keeps the common readable case at zero VLM cost).
+    `fast` and `vlm` are `Parser`s (injectable); the last run's `report` is exposed for PARTIAL reporting."""
+
+    def __init__(self, *, fast: Parser | None = None, vlm: Parser | None = None) -> None:
+        self._fast = fast
+        self._vlm = vlm
+        self.report = TieredOCRReport()
+
+    def convert(self, source: Path) -> DoclingDocument:
+        from rag_wright.capabilities.scan_quality import ScanQuality, assess_document
+
+        fast = self._fast or DoclingParser()
+        fast_doc = fast.convert(source)
+        # 0009-GATE-CAL: fold in IMAGE metrics (blur/faintness) -- the strong signal a text-only gate misses when
+        # the fast OCR is garbled-but-common-word. The VLM re-check below is text-only (the image stays blurry).
+        assessed = assess_document(fast_doc, page_images=_render_gray_pages(source))
+        degraded = sorted(pg for pg, a in assessed.items() if a.quality is not ScanQuality.READABLE)
+        # PARSE-1: a page with a usable NATIVE text layer (born-digital) is authoritative -- the OCR word-hit gate
+        # false-positives on legitimately sparse born-digital pages (a signature/joinder page: names, titles,
+        # page numbers), which triggered an unnecessary whole-document VLM escalation (~minutes on OpenRouter) on
+        # real contracts. So never OCR-escalate a page whose text layer we can read directly; only genuinely
+        # image-only pages (no text layer) stay in the escalation set.
+        born_digital = _text_layer_pages(source)
+        degraded = [pg for pg in degraded if pg not in born_digital]
+        if not degraded:  # readable scan OR every "degraded" page was actually born-digital -> no VLM cost
+            self.report = TieredOCRReport()
+            return fast_doc
+
+        vlm = self._vlm if self._vlm is not None else (_default_vlm_parser() if _vlm_available() else None)
+        if vlm is None:  # GRACEFUL DEGRADE: no VLM configured -> cannot escalate; flag PARTIAL, keep the fast doc
+            self.report = TieredOCRReport(escalated_pages=[], unreadable_pages=degraded)
+            _log_unreadable(source, degraded, "no VLM configured (set OPENROUTER_API_KEY)")
+            return fast_doc
+        try:
+            # PARSE-3: escalate ONLY the degraded pages to the VLM (per-page), then concatenate with the
+            # fast-parsed good pages -- never the whole document. A large born-digital doc with one genuine
+            # image-only page used to VLM all 60+ pages (~30 min) and blow the 600s parse deadline.
+            vlm_doc = _escalate_degraded_pages(source, fast, vlm, degraded)
+        except Exception as exc:  # noqa: BLE001 - a VLM failure must not sink the parse; flag PARTIAL, keep fast doc
+            self.report = TieredOCRReport(escalated_pages=degraded, unreadable_pages=degraded)
+            _log_unreadable(source, degraded, f"VLM escalation failed: {exc!r}")
+            return fast_doc
+
+        vlm_assessed = assess_document(vlm_doc)
+        unreadable = sorted(pg for pg in degraded
+                            if vlm_assessed.get(pg) is None or vlm_assessed[pg].quality is not ScanQuality.READABLE)
+        self.report = TieredOCRReport(escalated_pages=degraded, unreadable_pages=unreadable)
+        if unreadable:  # even the VLM could not read these -> surface, never silently ingest gibberish
+            _log_unreadable(source, unreadable, "unreadable even after VLM escalation")
+        return vlm_doc
+
+
+def _default_vlm_parser() -> Parser:
+    from rag_wright.capabilities.vlm_ocr import VlmOCRParser
+
+    return VlmOCRParser()
+
+
+def _page_count(source: Path) -> int:
+    """Total page count of a PDF (pypdfium2, no parse). 0 for a non-PDF or any read error -> the caller falls
+    back to whole-document escalation."""
+    try:
+        import pypdfium2 as pdfium
+
+        return len(pdfium.PdfDocument(str(source)))
+    except Exception:  # noqa: BLE001 - best-effort; unknown page count -> whole-doc fallback
+        return 0
+
+
+def _escalation_runs(n_pages: int, degraded: set[int]) -> list[tuple[int, int, bool]]:
+    """PARSE-3: partition pages 1..n_pages into CONTIGUOUS runs, each tagged `is_vlm` (a degraded page -> VLM,
+    else fast). So a 63-page doc with page 31 degraded yields [(1,30,False),(31,31,True),(32,63,False)] -- the VLM
+    touches only page 31. Returns `[(start, end, is_vlm)]`, 1-based inclusive, covering every page in order."""
+    runs: list[tuple[int, int, bool]] = []
+    start = 1
+    while start <= n_pages:
+        is_vlm = start in degraded
+        end = start
+        while end + 1 <= n_pages and ((end + 1) in degraded) == is_vlm:
+            end += 1
+        runs.append((start, end, is_vlm))
+        start = end + 1
+    return runs
+
+
+def _escalate_degraded_pages(source: Path, fast: Parser, vlm: Parser, degraded: list[int]) -> DoclingDocument:
+    """PARSE-3: build the escalated document by parsing each contiguous page-run with the right parser (fast for
+    born-digital pages, VLM for the degraded ones) and concatenating -- so VLM cost scales with the number of
+    DEGRADED pages, not the document length. Falls back to a whole-document VLM parse when the page count is
+    unknown or a parser has no `parse_range` (e.g. a non-PDF, or an injected stub) -- preserving the prior
+    behavior for those cases."""
+    n_pages = _page_count(source)
+    if not n_pages or not hasattr(fast, "parse_range") or not hasattr(vlm, "parse_range"):
+        return vlm.convert(source)  # fallback: whole-document VLM (unknown page count / no page-range support)
+    runs = _escalation_runs(n_pages, set(degraded))
+    subdocs = [
+        (vlm if is_vlm else fast).parse_range(source, (start, end)) for start, end, is_vlm in runs
+    ]
+    return subdocs[0] if len(subdocs) == 1 else DoclingDocument.concatenate(subdocs)
+
+
+_MIN_TEXT_LAYER_CHARS = 30  # a PDF page with >= this many directly-extractable chars has a real, authoritative
+#                             text layer (born-digital). Set LOW on purpose (PARSE-2, doc3): a true image-only scan
+#                             page extracts ~0 chars, but a SPARSE born-digital page -- a schedule, an exhibit
+#                             divider, a signature page (doc3 pages 52-58 = 91-179 chars) -- extracts only tens.
+#                             The old 200 threshold mislabeled those sparse-but-real pages as scans, so a single one
+#                             flagged by the OCR gate triggered a WHOLE-DOCUMENT VLM escalation that, on a 63-page
+#                             doc, blew the 600s parse deadline. A real text layer of any size is authoritative.
+
+
+def _text_layer_pages(source: Path, *, min_chars: int = _MIN_TEXT_LAYER_CHARS) -> set[int]:
+    """PARSE-1: the 1-based page numbers of `source` that carry a usable NATIVE text layer (born-digital) -- read
+    DIRECTLY from the PDF (pypdfium2, no OCR). A page here is authoritative and must never be OCR-quality-assessed
+    or VLM-escalated. Best-effort: a non-PDF or any read error -> empty set (no override -> the tiered OCR path is
+    unchanged), so a scan / text / office source is never affected."""
+    try:
+        import pypdfium2 as pdfium
+
+        pdf = pdfium.PdfDocument(str(source))
+        pages: set[int] = set()
+        for i in range(len(pdf)):
+            text = pdf[i].get_textpage().get_text_range()
+            if len(text.strip()) >= min_chars:
+                pages.add(i + 1)
+        return pages
+    except Exception:  # noqa: BLE001 - the text-layer probe is an optional authority signal; never fail the parse
+        return set()
+
+
+def _render_gray_pages(source: Path, dpi: int = 200) -> dict:
+    """Render each PDF page to a grayscale image {page_no(1-based): ndarray} for the scan-quality gate's image
+    metrics. 200 DPI to match the validated Laplacian/dark_frac thresholds. Best-effort: a non-PDF or any render
+    error -> {} (the gate falls back to text-only), so a text/office source never breaks the parse."""
+    try:
+        import numpy as np
+        import pypdfium2 as pdfium
+
+        pdf = pdfium.PdfDocument(str(source))
+        return {i + 1: np.asarray(pdf[i].render(scale=dpi / 72.0).to_pil().convert("L")) for i in range(len(pdf))}
+    except Exception:  # noqa: BLE001 - image metrics are an optional gate signal; never fail the parse over them
+        return {}
+
+
+def _vlm_available() -> bool:
+    """The escalation VLM is usable only if an OpenRouter key is configured. Absent -> graceful degrade."""
+    import os
+
+    return bool(os.environ.get("OPENROUTER_API_KEY"))
+
+
+def _log_unreadable(source: Path, pages: list[int], why: str) -> None:
+    """Surface unreadable/degraded pages (never silently ingest gibberish -- 0006-C / ENG-1 applied to OCR)."""
+    logging.getLogger(__name__).warning(
+        "[ocr] %s: pages %s could not be read (%s) -- flagged PARTIAL / needs-rescan", getattr(source, "name", source),
+        pages, why)
+
+
+def _source_doc_id(source: Path) -> str:
+    """A delimiter-safe id from the file stem via the ONE canonical slug (HYG-1)."""
+    return canonical_source_doc_id(source.stem)
+
+
+def _content_hash(source: Path) -> str:
+    return hashlib.sha256(source.read_bytes()).hexdigest()
+
+
+def parse(source: Path, *, cache_dir: Path, parser: Parser) -> ParsedDocument:
+    """Parse `source` into the cached structured representation, parsed once (content-hash gated).
+
+    If a manifest for this content hash already exists, it is reused (no re-parse); otherwise the
+    source is converted and the `DoclingDocument` is cached as JSON.
+    """
+    source_doc_id = _source_doc_id(source)
+    content_hash = _content_hash(source)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    manifest_path = cache_dir / f"{source_doc_id}.{content_hash[:16]}.json"
+
+    if not manifest_path.exists():  # the content-hash gate: parse once
+        document = parser.convert(source)
+        document.save_as_json(manifest_path)
+
+    return ParsedDocument(
+        source_doc_id=source_doc_id,
+        content_hash=content_hash,
+        manifest_path=str(manifest_path),
+    )
+
+
+def load_document(parsed: ParsedDocument) -> DoclingDocument:
+    """Load the full structured representation from the parse manifest."""
+    return DoclingDocument.load_from_json(parsed.manifest_path)
+
+

rag_wright/capabilities/property_boosted_retrieval.py

@@ -0,0 +1,125 @@
+"""SPAN-CLAUSE-RERANK (b) (FR-Q, ADR-0033): property-boosted typed retrieval over the CUAD-full KG.
+
+The KG-5 V4 adopted shape, bound to CUAD-full via the operative-span `edge.span_id` join (SPAN-CLAUSE-RERANK):
+  BGE base pool (`store.span_hybrid_search`, function-filtered, bounded) -> join each span to its clause's
+  typed (dimension, value) props (`store.span_properties`, the edge.span_id join) -> `typed_constraint_match_rank`
+  (STABLE sort: constraint-match count primary, so the BGE pool order is the tiebreak) -> top-k cited spans.
+
+The routed `functions` and typed `constraints` come from the query front-door (the MS1-6 A100 path: LegalBERT +
+granite routing, granite constraint-extraction); they are passed in so this capability is a pure store+embedder
+composition, hermetically testable with fakes. `store` / `embedder` are the seams (local or the A100 adapters).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.retrieval_core import typed_constraint_match_rank
+
+
+class RankedSpan(BaseModel):
+    """One property-boosted, cited retrieval result (FR-Q.6): the span citation + text, its function, the
+    constraint-match score, the query constraints it satisfied, and its 1-based rank. A PURE retrieval contract --
+    relevance is a separate judgement (issue 0023): the `typed_property_retrieval` subgraph composes a RankedSpan
+    with a `RelevanceVerdict` into a `JudgedSpan`, rather than growing a verdict field here."""
+
+    span_id: str
+    text: str
+    function: str
+    match_score: float
+    matched: list[tuple[str, str]]
+    rank: int
+
+
+def _select_with_dense_floor(reranked_ids: list[str], dense_floor: list[str], k: int) -> list[str]:
+    """Take the first `k` reranked ids (fusion/constraint order), but RESERVE slots so every dense-floor span
+    survives into the returned `k` (issue 0041): a non-floor span is skipped when the remaining slots are needed
+    for floor spans not yet included, so a strong dense match the RRF fusion buried is never dropped. A floor span
+    keeps its reranked position where a slot is free; constraint-matching spans (high in the reranked order) are
+    reached before slots run low, so the floor only displaces the weak, non-matching tail."""
+    floor = list(dict.fromkeys(dense_floor))  # dedup, keep dense order
+    result: list[str] = []
+    for sid in reranked_ids:
+        if len(result) >= k:
+            break
+        if sid in result:
+            continue
+        pending = [g for g in floor if g not in result and g != sid]
+        if sid in floor or (k - len(result)) > len(pending):
+            result.append(sid)
+        # else: skip this non-floor span, reserving the slot for a still-pending floor span
+    for g in floor:  # safety net: any floor span the reranked pass didn't reach (should not happen)
+        if len(result) >= k:
+            break
+        if g not in result:
+            result.append(g)
+    return result[:k]
+
+
+def property_boosted_retrieval(
+    query: str,
+    *,
+    store: Any,
+    embedder: Any,
+    functions: Iterable[str],
+    constraints: Iterable[tuple[str, str]],
+    k: int = 8,
+    pool_k: int = 30,
+    documents: list[str] | None = None,
+    dense_floor_n: int = 3,
+    match_count_fn: Any,
+) -> list[RankedSpan]:
+    """Retrieve the top-`k` cited spans for `query`, property-boosted by the typed constraints. Pool =
+    `span_hybrid_search` (BGE RRF) over each routed function (deduped, BGE order preserved); rerank =
+    constraint-match primary + BGE tiebreak via the stable `typed_constraint_match_rank`.
+
+    Issue 0031: `documents` scopes the pool to a workspace's source documents IN THE STORE (`contract_id IN
+    [...]`), so out-of-scope spans are never pooled or reranked. `None` = whole index; `[]` = no results.
+
+    Issue 0041: DENSE FLOOR. RRF equal-weights the dense and sparse legs, so a short query on a ubiquitous token
+    ('...terms?') lets the sparse leg crowd the strong dense match out of the pool entirely -> the answer span is
+    never returned and the product abstains. The top-`dense_floor_n` PURE-DENSE spans are unioned into the pool
+    and GUARANTEED into the returned `k` (`_select_with_dense_floor`): fusion still decides order, dense guarantees
+    membership. Kept small (default 3) so it recovers the buried dense match without displacing the working
+    queries' RRF/constraint results (it only fills non-matching tail slots). `dense_floor_n=0` disables it."""
+    constraints = set(constraints)
+    dense, sparse = embedder.encode_dense(query), embedder.encode_sparse(query)
+    ordered: list[str] = []
+    function_of: dict[str, str] = {}
+    seen: set[str] = set()
+    for f in (list(functions) or [None]):  # None -> no function filter (whole-index pool)
+        for h in store.span_hybrid_search(dense, sparse, k=pool_k, function=f, documents=documents):
+            sid = h["span_id"]
+            if sid not in seen:
+                seen.add(sid)
+                ordered.append(sid)
+                function_of[sid] = h.get("function", "") or (f or "")
+    dense_floor: list[str] = []  # issue 0041: the top-N pure-dense spans, guaranteed into the returned k
+    if dense_floor_n:
+        for h in store.span_dense_search(dense, k=dense_floor_n, documents=documents):
+            sid = h["span_id"]
+            dense_floor.append(sid)
+            if sid not in seen:  # pool it (for props + rerank) if the RRF leg missed it
+                seen.add(sid)
+                ordered.append(sid)
+                function_of[sid] = h.get("function", "")
+    if not ordered:
+        return []
+    from rag_wright.capabilities.contract_kg_store import ContractKGStore  # EP-REF-1a-ii: typed reads via the domain store
+    props = ContractKGStore(store).span_properties(ordered)
+    ranked = typed_constraint_match_rank(
+        constraints, [(sid, props[sid]) for sid in ordered], match_count_fn=match_count_fn).ranked
+    top_ids = _select_with_dense_floor([r.clause_id for r in ranked], dense_floor, k)
+    texts = store.span_texts(top_ids)
+    score_of = {r.clause_id: r.match_score for r in ranked}
+    return [
+        RankedSpan(
+            span_id=sid, text=texts.get(sid, ""), function=function_of.get(sid, ""),
+            match_score=score_of.get(sid, 0.0), matched=sorted(constraints & props.get(sid, set())), rank=i,
+        )
+        for i, sid in enumerate(top_ids, 1)
+    ]
+
+

rag_wright/capabilities/query_function_classifier.py

@@ -0,0 +1,94 @@
+"""KG-5e lever (b): the taxonomy-constrained query->function classifier -- a SINGLE structured granite call.
+
+KG-5c/5e proved that query-side function routing is the dominant retrieval lever and that the LegalBERT
+classifier (trained on CLAUSE spans) is out-of-distribution on short query text. This routes instead with an
+LLM that reads the query in-distribution, its output FORCED to the closed FUNCTION taxonomy (structured output,
+then normalized at the boundary via `canonical_function`, dropping anything off-taxonomy -- the "strict
+contracts, normalize at the boundary" rule). Unlike granite's free-text `clause_type` (KG-5b, unreliable), the
+label space here is closed and ranked.
+
+`route_query` is the KG-5e (b) front door: TWO separate granite calls -- one for the typed constraints, one
+for the function -- on the hypothesis that granite does one task at a time better than both in one prompt (the
+fallback, if this underperforms, is to unify into a single prompt). The structured factory is injectable so
+the normalization is tested hermetically (no LLM, no network).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.function import FUNCTION_LABELS, canonical_function
+from rag_wright.models.tag_structured import build_tag_structured  # ADR-0045: LLM-agnostic client-side output
+
+_PROMPT = (
+    "You match a legal question about a contract to clause types from a FIXED taxonomy. Return the EXACT "
+    "taxonomy labels the question is about, MOST RELEVANT FIRST -- usually 1, at most 3, and only more than "
+    "one when the question genuinely spans multiple types. Use only labels from the taxonomy; if none apply, "
+    "return an empty list.\n\nTaxonomy:\n{taxonomy}\n\nQuestion: {query}"
+)
+
+
+class _FunctionChoice(BaseModel):
+    """The LOOSE schema the LLM fills (ranked labels); normalized to canonical `FUNCTION_LABELS` at the boundary."""
+
+    clause_types: list[str] = []
+
+
+def _taxonomy_block() -> str:
+    return "\n".join(f"- {label}" for label in FUNCTION_LABELS)
+
+
+def classify_query_functions(
+    query: str, model_id: str, *, k: int = 3, structured_factory=build_tag_structured
+) -> list[str]:
+    """The top-`k` canonical FUNCTION_LABELS a query is about, ranked, via one structured call. Off-taxonomy or
+    unmappable labels are dropped; a failed structured emit (None or a persistent parse failure) -> ``[]``
+    (degrades to no routing, never a hard error). Order preserved, deduped, truncated to `k`."""
+    try:
+        raw = structured_factory(model_id, _FunctionChoice).invoke(
+            _PROMPT.format(taxonomy=_taxonomy_block(), query=query)
+        )
+    except Exception:  # noqa: BLE001 - client-side tag parse gave up -> no routing (degrade, never a hard error)
+        return []
+    if raw is None:
+        return []
+    out: list[str] = []
+    for label in raw.clause_types:
+        mapped = canonical_function(label)
+        if mapped is not None and mapped not in out:
+            out.append(mapped)
+    return out[:k]
+
+
+def route_query(
+    query: str, *, extract_model, function_model_id: str, k: int = 3
+) -> tuple[list[tuple[str, str]], list[str]]:
+    """The KG-5e (b) query front door: TWO separate granite calls -> (typed constraints, ranked functions).
+
+    Call 1 extracts the typed (dimension, value) constraints (docling-graph + `clause_template`); call 2
+    classifies the function (this module). Two tasks, two calls -- if this underperforms a unified prompt, fold
+    them. Kept as a single wrapper so production and the eval share one shape.
+    """
+    from rag_wright.capabilities.dg_extraction import extract_clause
+    from rag_wright.contracts.identifiers import ChunkId
+    from rag_wright.spans.clause_kg_extractor import clause_to_record
+
+    constraints: list[tuple[str, str]] = []
+    clause = extract_clause(query, extract_model)
+    if clause is not None:
+        rec = clause_to_record(clause, chunk_id=ChunkId.of("q", 0, query), function="Cap On Liability")
+        constraints = [(a.dimension.value, a.value) for a in rec.assertions]
+    functions = classify_query_functions(query, function_model_id, k=k)
+    return constraints, functions
+
+
+def register_query_function_classification(registry) -> None:
+    """CAP-REG-2: register `query_function_classification` (agent_skill; taxonomy-constrained LLM classifier)."""
+    from rag_wright.contracts.function import FunctionClassification
+
+    registry.register(
+        "query_function_classification",
+        contract=FunctionClassification,
+        kind="agent_skill",
+        display_name="Query function classification",
+    )

rag_wright/capabilities/query_understanding.py

@@ -0,0 +1,109 @@
+"""CU-C1: NL->type query understanding -- the front door of the CUAD highlight pipeline.
+
+A natural-language question about a KNOWN contract is parsed in ONE structured LLM call into a `QueryIntent`:
+which clause type(s) the user asks about (mapped to the FUNCTION taxonomy), what they want done (highlight /
+extract a value / discriminate among same-type clauses), and whether the ask is in-taxonomy.
+
+This is a user-required MVP front door (robust natural-language handling, NOT templates), layered ON TOP of the
+registered capabilities. It is intentionally NOT registered under a canonical capability slug: NL->type is not
+an FR-C/FR-Q capability in the (closed) spec catalog, and registering one would invent a requirement the spec
+does not state. It is ordinary tested software the compiled query graph can call as glue.
+
+The strict `QueryIntent` validator rejects non-taxonomy labels, so the LLM emits a LOOSE schema and this module
+NORMALIZES at the boundary (canonicalize labels, drop unmappable ones, derive `in_taxonomy`) -- the "strict
+contracts, normalize at the boundary" rule. Multi-type is allowed. Out-of-taxonomy (nothing maps) ->
+`in_taxonomy=False`, `clause_types=[]` -> the serve stage does semantic fallback + a low-confidence flag.
+`structured_factory` is injectable so the mapping logic is tested hermetically (no LLM, no network).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.function import FUNCTION_LABELS, canonical_function
+from rag_wright.contracts.query_intent import QueryIntent
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.seam import build_model
+from rag_wright.models.tag_structured import build_tag_structured  # ADR-0045: LLM-agnostic client-side output
+
+_INTENTS = ("highlight", "extract", "discriminate")
+
+# Two-step (reason -> emit), the sanctioned pattern for a model that cannot combine reasoning with a forced
+# structured call (CLAUDE.md standing rule; ADR-0006 Qwen precedent; ADR-0032). Step 1 reasons in free text
+# (a GENERAL-model strength -- no forced tool, so no thinking-mode tool rejection); step 2 emits the schema
+# from that reasoning (the profile disables thinking on this forced call for the models that need it, e.g.
+# Gemma). This makes NL->type work on the cheap GENERAL model, not just DeepSeek Pro (benchmarked in CU-D2).
+_REASON_PROMPT = (
+    "You match a user's natural-language question about a SINGLE known contract to clause types from a fixed "
+    "taxonomy. Reason briefly about which type(s) the question concerns and what the user wants, then END "
+    "with EXACTLY these three lines:\n"
+    "TYPES: <comma-separated EXACT taxonomy labels the question is about, or NONE if the concept is absent "
+    "from the taxonomy>\n"
+    "INTENT: <highlight to locate the clause | extract if the user asks for a specific value inside it | "
+    "discriminate if the user wants the one clause matching a condition among several of the same type>\n"
+    "VALUE: <the value to extract or the selecting condition, or NONE>\n\n"
+    "Taxonomy:\n{taxonomy}\n\nQuestion: {query}"
+)
+_EMIT_PROMPT = (
+    "Convert this analysis into the structured intent. clause_types = the EXACT labels listed after TYPES "
+    "(empty list if TYPES is NONE). intent = the word after INTENT. value_to_extract = the VALUE when "
+    "intent is extract, else null; value_condition = the VALUE when intent is discriminate, else null. "
+    "in_taxonomy = false iff TYPES is NONE.\n\nAnalysis:\n{reasoning}"
+)
+
+
+class _RawIntent(BaseModel):
+    """The LOOSE schema the LLM fills; normalized into the strict `QueryIntent` at the boundary."""
+
+    clause_types: list[str] = []
+    intent: str = "highlight"
+    value_to_extract: str | None = None
+    value_condition: str | None = None
+    in_taxonomy: bool = True
+    confidence: float = 1.0
+
+
+def _taxonomy_block() -> str:
+    return "\n".join(f"- {label}" for label in FUNCTION_LABELS)
+
+
+def understand_query(
+    query: str,
+    *,
+    reason_factory=build_model,
+    structured_factory=build_tag_structured,
+    model_id: str | None = None,
+) -> QueryIntent:
+    """Parse a natural-language question into a `QueryIntent` via the two-step reason->emit (see the prompts
+    above): step 1 reasons in free text, step 2 emits the schema from that reasoning. Then boundary
+    normalization: `in_taxonomy` is DERIVED from what actually maps (a mapping miss degrades gracefully to
+    semantic fallback, never a hard error); a failed emit (None) degrades to out-of-taxonomy low-confidence.
+    Defaults to the GENERAL model (Gemma): the two-step ties/beats DeepSeek Pro on NL->type at ~3x less
+    latency and cost, and is not throttled (benchmarked CU-D2 / ADR-0032). Factories are injectable for
+    hermetic tests."""
+    model_id = model_id or model_for(ModelRole.GENERAL)
+    reasoning = reason_factory(model_id).invoke(
+        _REASON_PROMPT.format(taxonomy=_taxonomy_block(), query=query)
+    ).content
+    try:
+        raw = structured_factory(model_id, _RawIntent).invoke(_EMIT_PROMPT.format(reasoning=reasoning))
+    except Exception:  # noqa: BLE001 - a persistent client-side parse failure degrades like a None emit
+        raw = None
+    if raw is None:  # the emit failed -> out-of-taxonomy, low confidence (never a hard error)
+        return QueryIntent(clause_types=[], intent="highlight", in_taxonomy=False, confidence=0.0)
+    canon: list[str] = []
+    for label in raw.clause_types:
+        mapped = canonical_function(label)
+        if mapped is not None and mapped not in canon:
+            canon.append(mapped)
+    in_taxonomy = bool(canon)  # ground truth = did anything map; the LLM's own flag is advisory only
+    intent = raw.intent if raw.intent in _INTENTS else "highlight"
+    confidence = min(1.0, max(0.0, raw.confidence))
+    return QueryIntent(
+        clause_types=canon,
+        intent=intent,
+        value_to_extract=raw.value_to_extract if intent == "extract" else None,
+        value_condition=raw.value_condition if intent == "discriminate" else None,
+        in_taxonomy=in_taxonomy,
+        confidence=confidence,
+    )