rag-wright 0.1.0__py3-none-any.whl

rag_wright/spans/scarce_function_labels.py

@@ -0,0 +1,105 @@
+"""Step-4 (classifier rare-class improvement): source SILVER training labels for the SCARCE CUAD function
+classes (0.00-recall / <35 real train spans). Same T60 pattern as `new_function_labels.py`: the operative
+spans CUAD leaves unlabeled (NONE) are candidates -- these classes are under-annotated, so their real
+instances hide in the NONE pool -- narrowed by a cheap high-recall KEYWORD pre-filter, then confirmed by an
+LLM. Unlike T60 these are EXISTING `ClauseCategory` types (they have CUAD gold too); the silver only augments
+TRAINING (mined from train contracts; the SEED=0 holdout stays pure gold, no leakage).
+
+Confirmer defaults to the GENERAL model (Gemma) per the benchmarked model decisions -- its structured
+thinking-disable (ADR-0032) makes this single-label forced call reliable; A/B against DeepSeek if it
+underperforms. Keyword pre-filter is unit-testable + free; the confirmer is stub-injectable.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.function import canonical_function
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.seam import build_structured
+
+NONE_LABEL = "NONE"
+
+# High-recall keyword pre-filter (lowercased substring). Broad on purpose -- precision is the LLM's job; this
+# only must avoid dropping true positives. Keys MUST be canonical FUNCTION_LABELS.
+SCARCE_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "Unlimited/All-You-Can-Eat-License": (
+        "unlimited", "all-you-can-eat", "all you can eat", "without limit", "no limit",
+        "unrestricted", "no restriction on the number",
+    ),
+    "Irrevocable Or Perpetual License": (
+        "irrevocable", "perpetual", "in perpetuity",
+    ),
+    "Notice Period To Terminate Renewal": (
+        "renew", "auto-renew", "automatically renew", "written notice", "days notice",
+        "days' notice", "prior written notice", "non-renew", "not to renew",
+    ),
+    "Most Favored Nation": (
+        "most favored", "most-favored", "no less favorable", "as favorable as", "mfn",
+    ),
+    "Non-Disparagement": (
+        "disparage", "denigrate", "defame",
+    ),
+    "Third Party Beneficiary": (
+        "third party beneficiar", "third-party beneficiar", "no third party",
+    ),
+}
+
+_VALID = {canonical_function(k) for k in SCARCE_KEYWORDS}  # canonical-guard the keys at import
+assert None not in _VALID, "SCARCE_KEYWORDS keys must be canonical FUNCTION_LABELS"
+
+
+class ScarceLabel(BaseModel):
+    """Structured confirm output: the chosen scarce label string (validated to the candidates by the caller)."""
+
+    label: str
+
+
+def scarce_candidates(text: str) -> frozenset[str]:
+    """The scarce labels a span MIGHT be, by keyword. Empty => skip the LLM entirely."""
+    low = text.lower()
+    return frozenset(
+        label for label, kws in SCARCE_KEYWORDS.items() if any(kw in low for kw in kws)
+    )
+
+
+def scarce_prompt(text: str, candidates: frozenset[str]) -> str:
+    options = "\n- ".join(sorted(candidates))
+    return (
+        "You label a contract clause span for a function classifier. A keyword filter flagged it as possibly "
+        "one of these clause types:\n- " + options + "\n\n"
+        "Decide which ONE it ACTUALLY is by its operative meaning (not a passing mention), or answer NONE if "
+        "it is none of them. Respond with EXACTLY one of the type strings above, or NONE.\n\n"
+        "Span:\n" + text[:2000]
+    )
+
+
+@runtime_checkable
+class ScarceConfirmer(Protocol):
+    def __call__(self, text: str, candidates: frozenset[str]) -> str: ...
+
+
+class SeamScarceConfirmer:
+    """The real confirmer: structured output through the model-profile seam. Defaults to GENERAL (Gemma);
+    pass `model_id` to A/B another model (e.g. DeepSeek). Returns a validated label in `candidates` or NONE
+    (a hallucinated / off-list label is treated as NONE, conservative). Retries a transient bare `None`."""
+
+    def __init__(self, model_id: Optional[str] = None, *, retries: int = 3) -> None:
+        self._runnable = build_structured(model_id or model_for(ModelRole.GENERAL), ScarceLabel)
+        self._retries = retries
+
+    def __call__(self, text: str, candidates: frozenset[str]) -> str:
+        prompt = scarce_prompt(text, candidates)
+        last_error: Exception | None = None
+        for _ in range(self._retries):
+            try:
+                v = self._runnable.invoke(prompt)
+            except Exception as e:  # noqa: BLE001 - transient provider/parse error; retry
+                last_error = e
+                continue
+            if v is not None:
+                canon = canonical_function(v.label)
+                return canon if canon in candidates else NONE_LABEL
+        raise last_error or ValueError("no structured output after retries")

rag_wright/spans/segment.py

@@ -0,0 +1,341 @@
+"""T55 (FR-R, ADR-0025): operative-span segmenter — re-chunk a clause into operative spans.
+
+The recall investigation showed the function/property signal is a LOCAL operative provision, which a
+whole-clause embedding drowns. So we index at the span level (small-to-big): split a clause body on legal
+structure and point each span back to its parent clause. The span is the classified/retrieved unit; the parent
+clause is what we return and rerank.
+
+Deterministic and byte-faithful. Split signals (no LLM, no new dependency — the spaCy escalation is added only
+if the downstream metric demands it):
+  - enumeration markers at a provision start: `(a)`, `(i)`, `1.`, `12.1`, `12.1.1`, `§`,
+  - semicolon / colon list separators,
+  - sentence-ending `.` that is a genuine terminator (not a known abbreviation, not a decimal / section ref).
+Sub-floor fragments (a lone heading like "12.1 Limitation of Liability.") fold into the following provision.
+
+Invariant: the spans TILE the body -- `"".join(s.text) == body` -- so no character is lost, duplicated, or
+reordered. The `function` tag and embeddings are filled by later tasks (T56); this task produces the spans and
+their parent pointers only.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.span import SpanRecord
+
+DEFAULT_MIN_CHARS = 25  # a span whose stripped text is shorter folds into its neighbour (a bare heading/marker)
+
+# Abbreviations whose trailing '.' does not end a provision (lower-cased, no trailing dot).
+_ABBREV = {
+    "inc", "corp", "co", "ltd", "llc", "llp", "plc", "no", "nos", "art", "sec", "secs", "para", "paras",
+    "cf", "vs", "v", "mr", "mrs", "ms", "dr", "st", "ave", "etc", "al", "viz", "e.g", "i.e", "u.s", "u.s.c",
+}
+
+# An enumeration marker opening a provision: (a) (iv) (12) a) 12) 1. 12.1 12.1.1 §  -- captured as group 1.
+_ENUM = re.compile(
+    r"(?:(?<=\s)|(?<=[.;:])|\A)\s*"
+    r"(\(\s*(?:[a-zA-Z]|[ivxlcdm]{1,4}|\d{1,3})\s*\)"      # (a) (iv) (12)
+    r"|(?:[a-zA-Z]|[ivxlcdm]{1,4}|\d{1,3})\)"              # a) iv) 12)
+    r"|\d+(?:\.\d+){1,3}\.?"                                # 12.1  12.1.1.
+    r"|§+)\s+(?=[A-Z\"'(])"                                # followed by space + capital / quote / paren
+)
+
+# A sentence/list terminator followed by whitespace + start of a new provision.
+_TERM = re.compile(r"[.;:]\s+(?=[A-Z\"'(])")
+
+# 0006-B: a leading enumeration marker to strip before deciding if a span is a bare HEADING ('9.', '(a)', '12.1').
+_LEADING_ENUM = re.compile(r"^\s*(?:\(?[\dA-Za-z]{1,4}\s*[.)]|\d+(?:\.\d+){0,3}\.?|§+)\s+")
+
+# issue 0014: a markdown TABLE row (a line whose first non-space character is a pipe). A run of >=2 such lines is
+# a table block, kept as ONE atomic operative span -- the rows are meaningless without the header row, so a fee
+# schedule / payment table must retrieve as a unit (header + all rows), never split by the paragraph/sentence cutter.
+_TABLE_LINE = re.compile(r"^[ \t]*\|")
+_MIN_TABLE_LINES = 2
+
+
+def _table_block_ranges(body: str) -> list[tuple[int, int]]:
+    """issue 0014: the char ranges of contiguous markdown table blocks (>= `_MIN_TABLE_LINES` consecutive
+    pipe-led lines). Each range is atomic: `segment_clause` cuts at its edges and never inside it, so the whole
+    table is one operative span. Byte offsets tile the body (a range ends at the start of the first non-table
+    line, i.e. after the last row's newline)."""
+    ranges: list[tuple[int, int]] = []
+    run_start: int | None = None
+    run_lines = 0
+    pos = 0
+    for line in body.splitlines(keepends=True):
+        if _TABLE_LINE.match(line):
+            if run_start is None:
+                run_start, run_lines = pos, 0
+            run_lines += 1
+        else:
+            if run_start is not None and run_lines >= _MIN_TABLE_LINES:
+                ranges.append((run_start, pos))
+            run_start, run_lines = None, 0
+        pos += len(line)
+    if run_start is not None and run_lines >= _MIN_TABLE_LINES:
+        ranges.append((run_start, pos))
+    return ranges
+
+
+_MIN_CLAUSE_ALPHA = 6  # fewer alphabetic chars than this = a page number / "By:" / "9" -- not a clause
+_MIN_ALLCAPS_WORDS = 6  # a short ALL-CAPS span is a label/heading ("EXHIBIT C"); a long one may be a real clause
+_WORD_RE = re.compile(r"[A-Za-z]{2,}")
+# A signature / execution-block or notice-block label line -- universal, domain-neutral contract furniture
+# ("By: /s/ ...", "Name:", "Title:", "Attest:", "Its:", "Date:"; and the notice-block contacts "Attention:",
+# "Fax:", "Email:", "Telephone:"). The trailing ':' anchored right after the leading word makes it a LABEL, not a
+# provision that merely mentions the word (e.g. "By signing below, the parties agree ..." and "All notices shall
+# be sent to the following address:" both start with other words, so neither matches). issue 0036 adds the notice
+# contacts; a bare street/city address line has no such label and stays recall-first (kept -> a thin clause).
+_FURNITURE_LINE = re.compile(
+    r"^\s*(?:by|name|title|attest|witness|its|date|signature"
+    r"|attention|attn|facsimile|fax|e-?mail|telephone|tel|phone)\s*:", re.IGNORECASE)
+# A table-of-contents entry: a dotted leader (>=3 dots, optionally spaced) running to a trailing page number.
+# High-precision furniture; a decimal like "Section 3.1" or "(see Section 3.1)." has no long leader-to-page run.
+_TOC_LEADER = re.compile(r"(?:\.\s*){3,}\d+\s*$")
+
+
+def is_extractable_span(text: str) -> bool:
+    """EXTRACT-GUARD-1: whether a span is a CLAUSE worth attempting typed-property extraction on. RECALL-FIRST:
+    returns True for anything carrying lowercase prose (a real provision has function words -- 'the', 'shall',
+    'of'); only DECLINES clear document FURNITURE that bears no clause properties and only burns a docling-graph
+    call + retries -- a page number ('9'), a docket reference, a short bare ALL-CAPS heading ('EXHIBIT C',
+    'FORM OF SUBLICENSE', 'AMENDMENT OF DEFINITIONS.'), or a signature/execution-block label line ('By: /s/ ...',
+    'Name:', 'Title:').
+
+    A skipped span is NOT a content loss: it stays in the SPAN INDEX for retrieval (indexing is independent of
+    clause extraction); the guard only declines to mint a clause-KG node from furniture. A long ALL-CAPS provision
+    (a capitalised disclaimer, `>= _MIN_ALLCAPS_WORDS` words) is still extracted."""
+    t = text.strip()
+    if sum(c.isalpha() for c in t) < _MIN_CLAUSE_ALPHA:  # near-empty: page numbers, "By:", pure digits/punct
+        return False
+    if _FURNITURE_LINE.match(t):  # a signature/execution-block or notice-block contact-label line, not a provision
+        return False
+    if _TOC_LEADER.search(t):  # a table-of-contents dotted-leader-to-page-number line, not a provision
+        return False
+    if not any(c.islower() for c in t):  # ALL-CAPS: a label/heading unless it is a long (capitalised) clause
+        return len(_WORD_RE.findall(t)) >= _MIN_ALLCAPS_WORDS
+    return True  # has lowercase prose -> treat as a real clause (recall-first)
+
+
+# issue 0038/0039: a span that STARTS a new numbered contract section -- the provision unit. DEPTH-CAPPED at
+# TWO levels ('2.' or '2.1.'): a top-level or one-level-nested number opens a provision, but a DEEPER number
+# ('10.5.1.', '10.5.1.1.') is a LIST ITEM within its parent provision and must FOLD IN, per 0038's own grouping
+# rule (issue 0039: a naive marker/number regex over-splits at depth 3-4, trading one granularity bug for a
+# smaller one). A parenthesised letter/roman item ('(a)', '(i)') is likewise not a section (no leading digit).
+_SECTION_START = re.compile(r"^\(?\d{1,2}(?:\.\d{1,2})?\)?\.\s")
+# A section-WORD prefix ('Section 8', 'Article 2', 'Clause 12', 'Sec.'/'Art.', '§3') before a number -- the dominant
+# contract heading style. Stripped so the depth-capped number rule above decides exactly as for a bare '8.'. The
+# digit lookahead means a prose line like 'Section hereof shall mean ...' is left untouched (not a start).
+_SECTION_WORD = re.compile(r"^(?:§\s*|(?:section|article|clause|sec|art)\.?\s+)(?=\(?\d)", re.IGNORECASE)
+# The number FOLLOWING a section word (depth-capped to two levels; trailing '.'/')' optional, since the section
+# word already signals a heading): 'Section 8.' and 'Clause 12 Governing Law' both start a provision.
+_SECTION_NUM = re.compile(r"^\(?\d{1,2}(?:\.\d{1,2})?\)?[.)]?(?:\s|$)")
+
+
+def starts_new_provision(text: str) -> bool:
+    """issue 0038/0039: whether a span BEGINS a new provision, used to group contiguous spans into a provision for
+    clause extraction (retrieval stays per span). Tiered, deterministic:
+
+      - a span with a LEADING NUMBER is decided SOLELY by `_SECTION_START` (depth-capped to two levels): '2.' or
+        '2.1.' starts a provision; a deeper '10.5.1.'/'10.5.1.1.' is a list item and FOLDS IN (issue 0039 -- a
+        depth-blind rule over-splits nested list items into their own provisions);
+      - a span with NO leading number starts a provision if it is a bare Title-case heading or a short ALL-CAPS
+        heading (an un-numbered but headed contract).
+
+    When a document has none of these, no intra-chunk boundary fires and grouping falls back to the chunk (the
+    caller also breaks on a chunk change), so a heading-less contract degrades to chunk-level -- never one clause
+    per sentence, never per document."""
+    t = text.strip()
+    m = _SECTION_WORD.match(t)
+    if m:  # an explicit 'Section/Article/Clause N' heading -> a start (depth-capped; trailing period optional)
+        return bool(_SECTION_NUM.match(t[m.end():]))
+    if re.match(r"^\(?\d", t):  # a numbered item: ONLY the depth-capped section rule decides (no heading override)
+        return bool(_SECTION_START.match(t))
+    if _is_bare_heading(t):  # un-numbered but titled ('Governing Law', a short Title-case line)
+        return True
+    if t and not any(c.islower() for c in t) and len(_WORD_RE.findall(t)) < _MIN_ALLCAPS_WORDS:
+        return True  # a short ALL-CAPS heading ('CONFIDENTIALITY')
+    return False
+
+
+def provision_boundary_verdict(text: str) -> str:
+    """Three-way boundary classification used to group spans into provisions: `"start"` (a confident, deterministic
+    provision start), `"continue"` (clearly provision body), or `"uncertain"` (a short, plausibly-heading line in a
+    style the deterministic rules do not confidently classify -- e.g. a roman-numeral or colon heading). Only the
+    `"uncertain"` residue is sent to a decision model (Jev) by `spans.boundary`; a deterministic `"start"`/
+    `"continue"` never pays for a model call, so cost stays bounded to the ambiguous SHORT lines -- and new heading
+    styles get a model's judgment instead of another regex (the flexibility regex alone cannot give)."""
+    t = text.strip()
+    if starts_new_provision(t):
+        return "start"
+    if _heading_candidate(t):
+        return "uncertain"
+    return "continue"
+
+
+def _heading_candidate(text: str) -> bool:
+    """A short line that plausibly BEGINS a provision but was not a confident deterministic start: an enumerated
+    lead-in (number / roman numeral / letter) we did not confidently start, or a short capitalized title-like line
+    that is NOT a full sentence (no sentence punctuation). Deliberately broad -- the model decides -- but bounded to
+    SHORT lines, so ordinary body prose (long, lowercase-led, or a terminated sentence) is never a candidate."""
+    t = text.strip()
+    if not t or len(t) > 90 or t[0].islower():
+        return False  # empty, long, or lowercase-led -> provision body, never a candidate
+    if _LEADING_ENUM.match(t):
+        return True  # an enumerated lead-in the deterministic rules did not confidently start
+    return not (re.search(r"\.\s", t) or t.endswith("."))  # short + capitalized + NOT a full sentence -> a heading candidate
+
+
+def _is_bare_heading(text: str) -> bool:
+    """A bare SECTION HEADING (e.g. '9. Limitation of Liability') -- a short enumerated/Title-case line with NO
+    sentence terminator. It must fold INTO its body, never stand alone: a standalone heading gets classified as
+    a clause pointing at a bare heading, which pollutes evidence and can hide the real clause (issue 0006). A
+    genuine short provision carries an operative sentence (terminal '.'/';'/':'), so it is NOT a heading."""
+    t = text.strip()
+    if not t or len(t) > 60:
+        return False
+    rest = _LEADING_ENUM.sub("", t, count=1)  # drop a leading '9.' / '(a)' / '12.1' enumeration marker
+    if not rest or not rest[0].isupper():  # a heading's title starts capitalised
+        return False
+    return not re.search(r"[.;:]", rest)  # a bare title has no sentence punctuation; a provision does
+
+
+class OperativeSpan(BaseModel):
+    """One operative span of a clause, pointing back to its parent clause (FR-R small-to-big unit)."""
+
+    span_id: str  # "{parent_chunk_id}#{span_index}" -- embeds the parent (identifier rule, ADR-0025)
+    parent_chunk_id: str
+    parent_okf_path: str  # where the parent clause lives in the clause OKF bundle (locate/fetch for rerank)
+    span_index: int
+    start: int  # char offset into the parent clause body
+    end: int  # exclusive; spans tile the body: body[start:end] concatenated == body
+    text: str  # body[start:end] (raw slice; strip at use time)
+    pages: list[int] = []  # issue 0032: the source page(s) this span's canonical range overlaps (set at ingest)
+    bbox: tuple[float, float, float, float] | None = None  # best-effort single-item box (l, t, r, b)
+
+
+def _boundaries(body: str) -> list[int]:
+    """Deterministic cut offsets that partition `body` into operative spans (includes 0 and len(body)).
+
+    A markdown table block (issue 0014) is atomic: cuts are forced at its edges and every candidate cut INSIDE
+    it is suppressed, so the whole table stays one span (header + rows)."""
+    blocks = _table_block_ranges(body)
+
+    def _inside(c: int) -> bool:  # strictly inside a table block -> not a valid cut
+        return any(bs < c < be for bs, be in blocks)
+
+    cuts: set[int] = {0, len(body)}
+    for bs, be in blocks:  # a table block's edges are always boundaries
+        cuts.add(bs)
+        cuts.add(be)
+    for m in re.finditer(r"\n+", body):  # paragraph breaks
+        if not _inside(m.end()):
+            cuts.add(m.end())
+    for m in _ENUM.finditer(body):  # split BEFORE an enumeration marker opening a provision
+        if not _inside(m.start(1)):
+            cuts.add(m.start(1))
+    for m in _TERM.finditer(body):  # split AFTER a genuine sentence/list terminator
+        p = m.start()  # index of the '.' ';' or ':'
+        if _inside(m.end()):
+            continue
+        if body[p] == ".":
+            prev = body[p - 1] if p > 0 else ""
+            if prev.isdigit():  # decimal / section reference (12.1) -- not a terminator
+                continue
+            word = re.search(r"([A-Za-z.]+)$", body[max(0, p - 8):p])
+            if word and word.group(1).lower().strip(".") in _ABBREV:  # known abbreviation
+                continue
+        cuts.add(m.end())
+    return sorted(cuts)
+
+
+def _merge_subfloor(ranges: list[tuple[int, int]], body: str, min_chars: int) -> list[tuple[int, int]]:
+    """Fold a sub-floor fragment (bare heading/marker) into the FOLLOWING span; a trailing one into the previous.
+    Merges only extend adjacent ranges, so the tiling invariant (contiguous, gap-free) is preserved."""
+    merged: list[tuple[int, int]] = []
+    carry: int | None = None
+    for i, (s, e) in enumerate(ranges):
+        start = carry if carry is not None else s
+        is_last = i == len(ranges) - 1
+        # fold FORWARD a sub-floor fragment OR a bare heading (0006-B) -- so a heading never stands alone
+        if (len(body[start:e].strip()) < min_chars or _is_bare_heading(body[start:e])) and not is_last:
+            carry = start  # carry its start into the next span (its body)
+            continue
+        merged.append((start, e))
+        carry = None
+    if carry is not None:  # trailing sub-floor: extend the previous span to the end
+        last_end = ranges[-1][1]
+        if merged:
+            merged[-1] = (merged[-1][0], last_end)
+        else:
+            merged.append((carry, last_end))
+    return merged
+
+
+def segment_clause(
+    parent_chunk_id: str,
+    body: str,
+    *,
+    parent_okf_path: str = "",
+    min_chars: int = DEFAULT_MIN_CHARS,
+) -> list[OperativeSpan]:
+    """Segment a clause body into operative spans. Deterministic; spans tile the body byte-faithfully."""
+    if not body:
+        return []
+    cuts = _boundaries(body)
+    ranges = [(cuts[i], cuts[i + 1]) for i in range(len(cuts) - 1)]
+    ranges = _merge_subfloor(ranges, body, min_chars)
+    return [
+        OperativeSpan(
+            span_id=f"{parent_chunk_id}#{i}",
+            parent_chunk_id=parent_chunk_id,
+            parent_okf_path=parent_okf_path,
+            span_index=i,
+            start=s,
+            end=e,
+            text=body[s:e],
+        )
+        for i, (s, e) in enumerate(ranges)
+    ]
+
+
+def to_span_record(
+    op: OperativeSpan,
+    *,
+    contract_id: str,
+    chunk_doc_start: int,
+    dense_vector: list[float],
+    sparse_vector: dict[int, float],
+    function: str = "",
+    functions: list[str] | None = None,
+    parent_okf_path: str | None = None,
+) -> SpanRecord:
+    """CU-B2 (ADR-0029): OperativeSpan -> SpanRecord with DOCUMENT-ABSOLUTE offsets.
+
+    Composes `doc_start = chunk_doc_start + op.start`, `doc_end = chunk_doc_start + op.end` (the span's
+    clause-relative offsets shifted by the parent chunk's offset in the canonical document text, CU-B1). The
+    RAW span text (`op.text = body[start:end]`) is stored -- NOT stripped -- so the citation invariant
+    `canonical_document_text[doc_start:doc_end] == span.text` holds byte-faithfully. The caller may embed over
+    `op.text.strip()`; the stored text stays raw for the highlight.
+    """
+    return SpanRecord(
+        span_id=op.span_id,
+        parent_chunk_id=op.parent_chunk_id,
+        parent_okf_path=op.parent_okf_path if parent_okf_path is None else parent_okf_path,
+        span_index=op.span_index,
+        text=op.text,
+        function=function,
+        functions=list(functions) if functions else ([function] if function else []),
+        dense_vector=dense_vector,
+        sparse_vector=sparse_vector,
+        contract_id=contract_id,
+        doc_start=chunk_doc_start + op.start,
+        doc_end=chunk_doc_start + op.end,
+        page=(op.pages[0] if op.pages else None),  # issue 0032: FIRST page for the singular highlight field
+        pages=list(op.pages),  # ALL pages the span overlaps (cross-page clause -> a list)
+        bbox=op.bbox,  # best-effort single-item box
+    )
+
+

rag_wright/spans/semantic_judge.py

@@ -0,0 +1,197 @@
+"""JUDGE-SEMANTIC (ADR-0040), SKILL-SPLIT: Layer 3 of the neuro-symbolic extraction-fidelity cascade, the ONLY
+place an LLM is spent on judging -- split into a SKILL + a deterministic FUNCTION.
+
+Per the capability-architecture principle (a `function` is deterministic and takes no model; a single LLM act is
+an authored `agent_skill`; a workflow is a `subgraph`), the semantic judge is two capabilities:
+
+- **`extraction_semantic_judge` (agent_skill)** -- the verify-or-refute reading METHOD, authored as
+  `skills/extraction_semantic_judge/SKILL.md` and applied through the model seam (product = Granite, ADR-0039).
+  Given one property (`dimension = value`, with its meaning) and the clause text, it returns a raw
+  `SemanticVerdict` (supported / reason). `build_semantic_judge_fn` is its runtime; `structured_factory` is
+  injected for hermetic tests.
+- **`extraction_semantic_gate` (function)** -- `semantic_judge`: DETERMINISTIC, no model. Selects the surviving
+  (non-AMBIGUOUS) assertions on a SEMANTIC dimension (`SEMANTIC_DIMENSIONS`), runs the skill over each
+  concurrently, and downgrades a refuted one to AMBIGUOUS (kept but flagged), exactly like `reground` /
+  `symbolic_validate`. A judge that fails/returns None leaves the assertion untouched (never downgrade on a
+  judge error). Ingestion-side only; NOT on queries (KG-5d: judging the query text false-flags real constraints).
+
+Layers 1-2 (lexical grounding + symbolic SHACL) already cleared the type / cardinality / deontic / textual-anchor
+errors deterministically, so this LLM call class is small and focused: the closed SEMANTIC dimensions whose value
+is a READING with no surface form (`mutuality=mutual` vs `unilateral`, `favorability`, `cap_basis`, ...).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.property import CLOSED_VOCAB, ClausePropertyRecord, PropertyDimension
+from rag_wright.contracts.provenance import ConfidenceTag
+from rag_wright.models.tag_structured import build_tag_structured
+from rag_wright.spans.property_grounding import GROUNDING_CUES
+from rag_wright.util.concurrent import map_concurrent
+
+_SKILL_PATH = Path(__file__).parents[1] / "skills" / "extraction_semantic_judge" / "SKILL.md"
+
+# The closed SEMANTIC dimensions: a closed vocabulary (so not open-valued) with NO lexical cue (so not
+# checkable by the grounding judge) -- their value is a reading, not a surface token. This is exactly the
+# residual Layers 1-2 cannot reach.
+SEMANTIC_DIMENSIONS: frozenset[PropertyDimension] = frozenset(
+    d for d in CLOSED_VOCAB if d not in GROUNDING_CUES
+)
+
+# A short plain-language gloss so the judge understands what each (dimension, value) claims about the clause.
+_DIMENSION_GLOSS: dict[PropertyDimension, str] = {
+    PropertyDimension.MUTUALITY: "whether the obligation runs BOTH ways (mutual) or only one party's (unilateral)",
+    PropertyDimension.FAVORABILITY: "which side the term favors (buyer_favorable / seller_favorable)",
+    PropertyDimension.PARTY_ASYMMETRY: "whether the terms are the same for both parties (symmetric) or differ per party",
+    PropertyDimension.CAP_BASIS: "the shape of the liability cap (a fixed_fee amount vs a multiple_of_fees)",
+    PropertyDimension.LAW_MULTIPLICITY: "whether ONE governing law applies (single) or more than one (multiple)",
+    PropertyDimension.IP_OWNERSHIP: "who owns the IP (assigned to one party / joint / retained by the originator)",
+    PropertyDimension.NONSOLICIT_TARGET: "who may not be solicited (employees / customers)",
+    PropertyDimension.RENEWAL_MECHANISM: "how the term renews (auto-renews / requires_notice to renew)",
+    PropertyDimension.COC_CONSENT: "how a change of control is treated (consent_required / notice_only / unrestricted)",
+    PropertyDimension.ASSIGNMENT_CONSENT: "how assignment is treated (consent_required / notice_only / free)",
+    PropertyDimension.MFN_SCOPE: "what a most-favored-nation term covers (price / terms / price_and_terms)",
+    PropertyDimension.TERMINATION_RIGHT: "who may terminate for convenience (either_party / one_party)",
+}
+
+# The per-call appendix bound onto the SKILL method (the static method teaches the reading; the specific
+# property + clause are appended at call time, the compliance_judgment `_PROMPT_TAIL` pattern).
+_PROMPT_TAIL = "\n\nProperty: {dimension} = {value}\nMeaning: {gloss}\n\nClause:\n{clause}"
+
+
+class SemanticVerdict(BaseModel):
+    """The judge's ruling on one semantic assertion: is the reading supported by the clause text?"""
+
+    supported: bool
+    reason: str = ""
+
+
+# judge_fn: (dimension, value, clause_text) -> verdict, or None if the judge could not rule (left untouched).
+JudgeFn = Callable[[PropertyDimension, str, str], Optional[SemanticVerdict]]
+
+
+def judgment_method() -> str:
+    """The semantic-judge method (the `extraction_semantic_judge` SKILL body, YAML frontmatter stripped) used as
+    the judge's system/method prompt. Authored knowledge (skills/extraction_semantic_judge/SKILL.md)."""
+    text = _SKILL_PATH.read_text(encoding="utf-8")
+    if text.startswith("---"):
+        marker = text.find("\n---", 3)
+        if marker != -1:
+            text = text[marker + 4 :]
+    return text.strip()
+
+
+def _judge_prompt(method: str, dimension: PropertyDimension, value: str, text: str) -> str:
+    return method + _PROMPT_TAIL.format(
+        dimension=dimension.value, value=value,
+        gloss=_DIMENSION_GLOSS.get(dimension, dimension.value), clause=text)
+
+
+def build_semantic_judge_fn(model_id: str, *, structured_factory=build_tag_structured) -> JudgeFn:
+    """The `extraction_semantic_judge` SKILL's runtime: a Granite-backed verify-or-refute `JudgeFn` through the
+    model seam (model-neutral; the product points the seam at self-hosted vLLM-Granite). The SKILL.md method is
+    the system prompt; the specific property + clause are appended. `structured_factory` is injected for tests."""
+    method = judgment_method()
+
+    def judge(dimension: PropertyDimension, value: str, text: str) -> Optional[SemanticVerdict]:
+        return structured_factory(model_id, SemanticVerdict, label="semantic_judge.judge").invoke(
+            _judge_prompt(method, dimension, value, text))
+
+    return judge
+
+
+def build_asemantic_judge_fn(model_id: str, *, structured_factory=build_tag_structured):
+    """ASYNC-B2b (ADR-0057): the async twin of `build_semantic_judge_fn` -- the judge call on the async seam
+    (`.ainvoke`, true wall-clock deadline)."""
+    method = judgment_method()
+
+    async def ajudge(dimension: PropertyDimension, value: str, text: str) -> Optional[SemanticVerdict]:
+        return await structured_factory(model_id, SemanticVerdict, label="semantic_judge.judge").ainvoke(
+            _judge_prompt(method, dimension, value, text))
+
+    return ajudge
+
+
+def semantic_judge(
+    record: ClausePropertyRecord, text: str, judge_fn: JudgeFn, *, max_concurrency: int = 8
+) -> ClausePropertyRecord:
+    """`extraction_semantic_gate` (FUNCTION -- deterministic, no model): the ADR-0040 Layer-3 quality gate. Apply
+    the `extraction_semantic_judge` SKILL (`judge_fn`) to every surviving (non-AMBIGUOUS) assertion on a SEMANTIC
+    dimension; downgrade a refuted one to AMBIGUOUS. A no-op when there is nothing semantic to judge. The judge
+    calls run concurrently (async + semaphore, per the parallel-LLM rule). A None verdict is a judge failure ->
+    the assertion is left untouched (never downgrade on a judge error). The model lives in the SKILL, not here."""
+    targets = [
+        a for a in record.assertions
+        if a.dimension in SEMANTIC_DIMENSIONS and a.confidence != ConfidenceTag.AMBIGUOUS
+    ]
+    if not targets:
+        return record
+    verdicts = map_concurrent(
+        targets, lambda a: judge_fn(a.dimension, a.value, text), max_concurrency=max_concurrency
+    )
+    return _apply_verdicts(record, targets, verdicts)
+
+
+def _apply_verdicts(record: ClausePropertyRecord, targets: list, verdicts: list) -> ClausePropertyRecord:
+    """Downgrade to AMBIGUOUS every target assertion whose verdict refuted it; a None verdict (judge failure)
+    leaves the assertion untouched. Shared by the sync and async gates."""
+    refuted = {id(a) for a, v in zip(targets, verdicts) if v is not None and not v.supported}
+    if not refuted:
+        return record
+    new = [
+        a.model_copy(update={"confidence": ConfidenceTag.AMBIGUOUS}) if id(a) in refuted else a
+        for a in record.assertions
+    ]
+    return record.model_copy(update={"assertions": new})
+
+
+def _semantic_targets(record: ClausePropertyRecord) -> list:
+    return [a for a in record.assertions
+            if a.dimension in SEMANTIC_DIMENSIONS and a.confidence != ConfidenceTag.AMBIGUOUS]
+
+
+async def asemantic_judge(
+    record: ClausePropertyRecord, text: str, ajudge_fn: Any, *, max_concurrency: int = 8
+) -> ClausePropertyRecord:
+    """ASYNC-B2b (ADR-0057): the async twin of `semantic_judge`. Judges each surviving semantic assertion via the
+    async judge, concurrently, bounded by a semaphore (native form of the parallel-LLM rule); each call carries
+    the true wall-clock deadline. A None verdict leaves the assertion untouched (never downgrade on a failure)."""
+    targets = _semantic_targets(record)
+    if not targets:
+        return record
+    sem = asyncio.Semaphore(max_concurrency)
+
+    async def _one(a: Any) -> Any:
+        async with sem:
+            return await ajudge_fn(a.dimension, a.value, text)
+
+    verdicts = list(await asyncio.gather(*(_one(a) for a in targets)))
+    return _apply_verdicts(record, targets, verdicts)
+
+
+def register_extraction_semantic_judge(registry) -> None:
+    """Register `extraction_semantic_judge` as an AGENT_SKILL (ADR-0040 Layer 3): a single grounded LLM
+    verify-or-refute reading, authored as `skills/extraction_semantic_judge/SKILL.md` and applied via the seam.
+    Typed output = `SemanticVerdict`."""
+    registry.register(
+        "extraction_semantic_judge",
+        contract=SemanticVerdict,
+        kind="agent_skill",
+        display_name="Extraction semantic judge (clause property -> supported?; authored skill)",
+    )
+
+
+def register_extraction_semantic_gate(registry) -> None:
+    """Register `extraction_semantic_gate` (FUNCTION -- deterministic): apply the `extraction_semantic_judge`
+    SKILL over each surviving semantic assertion and downgrade a refuted one to AMBIGUOUS. No model."""
+    registry.register(
+        "extraction_semantic_gate",
+        contract=ClausePropertyRecord,
+        kind="function",
+        display_name="Extraction semantic gate (semantic-dimension AMBIGUOUS downgrade)",
+    )