rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/fusion.py

@@ -0,0 +1,64 @@
+"""Fusion (FR-Q.4, T27): union and deduplicate the two evidence streams on `chunk_id`, capped.
+
+Combines the reranked retrieval top set (T22) and the graph-cited chunks (T26) into one deduplicated,
+capped evidence set for synthesis/generation. This is deliberately NOT a score fusion: the graph
+returns an answer with cited chunks, not a comparable ranked list, so there is no common score to fuse.
+It is a deterministic union — retrieval chunks first (in their reranked order), then the graph-cited
+chunks (in order of appearance), each `chunk_id` kept once with a record of which stream(s) surfaced it.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.graph_query import GraphAnswer
+from rag_wright.capabilities.reranking import RerankResult
+
+DEFAULT_UNION_CAP = 20  # the fused evidence set is capped before synthesis (§16.7)
+
+RETRIEVAL = "retrieval"
+GRAPH = "graph"
+
+
+class FusedChunk(BaseModel):
+    """One chunk in the fused evidence set: its id and which stream(s) surfaced it (no score — this is
+    a union, not a score fusion)."""
+
+    chunk_id: str
+    sources: list[str]  # subset of {"retrieval", "graph"}, sorted
+
+
+class FusionResult(BaseModel):
+    """The fused, deduplicated, capped evidence set for synthesis (T28) / generation (T29)."""
+
+    chunks: list[FusedChunk]
+
+
+def fuse(
+    reranked: RerankResult, graph: GraphAnswer, *, cap: int = DEFAULT_UNION_CAP
+) -> FusionResult:
+    """Union the reranked candidates and the graph-cited chunks on `chunk_id`, capped, deterministic.
+
+    Order is deterministic: reranked candidates first (in their order), then graph-cited chunks (first
+    appearance). A chunk surfaced by both streams appears once, tagged with both sources. The union is
+    then cut to `cap`.
+    """
+    sources: dict[str, set[str]] = {}
+    order: list[str] = []
+
+    def _add(chunk_id: str, source: str) -> None:
+        if chunk_id not in sources:
+            sources[chunk_id] = set()
+            order.append(chunk_id)
+        sources[chunk_id].add(source)
+
+    for candidate in reranked.candidates:
+        _add(candidate.chunk_id, RETRIEVAL)
+    for evidence in graph.evidence:
+        for chunk_id in evidence.chunk_ids:
+            _add(chunk_id, GRAPH)
+
+    chunks = [FusedChunk(chunk_id=chunk_id, sources=sorted(sources[chunk_id])) for chunk_id in order[:cap]]
+    return FusionResult(chunks=chunks)
+
+

rag_wright/capabilities/graph_extraction.py

@@ -0,0 +1,243 @@
+"""Graph extraction (FR-C.6, FR-I.4): the GP-1B docling-graph party/relational extractor over parsed chunks.
+
+Re-backed per ADR-0035. The capability's job is unchanged -- a chunk -> ontology-conforming graph facts
+(`ExtractionResult`) anchored to `chunk_id` with a confidence tag (FR-S.4), behind the T5 `Extractor` seam --
+but the *implementation* is now the **GP-1B docling-graph extractor** (granite-4.2-8b), the entity/relational
+extractor that populated Leg C at real recall 0.991. The earlier T23-27 hybrid stack (spaCy NER +
+Pydantic-contract extraction + LLM escalation) is retired: Leg B (clause facts / inter-corpus recall) is served
+by the typed Clause KG (typed_clause_extraction), and Leg C (party-to-party relational) by GP-1B, so the hybrid
+stack -- built to probe inter-corpus recall -- no longer earns its keep.
+
+`DoclingGraphExtractor` extracts the signing parties from the chunk text via docling-graph
+(`dg_extraction.extract_parties`) and emits ORGANIZATION mentions + structural `CONTRACTS_WITH` facts between
+them (`parties_to_extraction`), EXTRACTED. Resolution to canonical ids (EDGAR CIK) and the graph write are
+downstream (`entity_resolution` -> `write_graph`), unchanged. The docling-graph call is a raw-SDK call, so the
+LG-2c subgraph wraps it in `raw_llm_span` (the observability contract); `extract_fn` is dependency-injected so
+the extractor is hermetically testable with no docling-graph / no network.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from typing import Any, Callable
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.registry import CapabilityRegistry
+from rag_wright.contracts.extraction import (
+    EntityMention,
+    ExtractionResult,
+    Extractor,
+    run_extractors,
+)
+from rag_wright.contracts.identifiers import ChunkId
+from rag_wright.contracts.ontology import RelationshipFact
+from rag_wright.contracts.provenance import ConfidenceTag, Provenance
+# DD-5 (ADR-0066/0117): this is a CONTRACT-domain builder (reference pack). The engine contracts are
+# taxonomy-free; the reference pack's entity/edge values live in ontology/contract_taxonomy.
+from rag_wright.ontology.contract_taxonomy import AFFILIATE_OF, CONTRACTS_WITH, ORGANIZATION
+
+DEFAULT_EXTRACT_CONCURRENCY = 4  # in-flight chunk extractions (backpressure); GPU/network-bound
+# The adopted graph-extraction model (GP-1B): granite-4.2-8b via OpenRouter; config-driven (SPEC §17).
+# Precedence parallels models.profiles.model_for: the role-specific env (RAG_GRAPH_EXTRACT_MODEL) > the
+# all-roles knob (RAG_MODEL_ALL) > the built-in default. The caller's `graph_extract_model` arg wins over all
+# (it is passed explicitly). So `RAG_MODEL_ALL=<id>` now covers party+affiliation extraction too.
+DEFAULT_GRAPH_EXTRACT_MODEL = (
+    os.getenv("RAG_GRAPH_EXTRACT_MODEL") or os.getenv("RAG_MODEL_ALL") or "qwen3.8-27b-modal-or")
+
+# extract_fn: contract/chunk text -> a `ContractParties` (docling-graph output) or None when nothing extracted.
+PartyExtractFn = Callable[[str], Any]
+
+
+def parties_to_extraction(chunk_id: ChunkId, parties: list[str]) -> ExtractionResult:
+    """Known signing parties -> ORGANIZATION mentions + a `CONTRACTS_WITH` fact between each pair, EXTRACTED.
+
+    Strips + dedups (order-stable); a lone party yields a mention but no edge. ADR-0012: the parties are the
+    actual signatories, so `CONTRACTS_WITH` is structural, not a proximity guess. This is the fact shape both
+    the GP-1B extractor (below) and the no-LLM CUAD-`Parties` path share.
+    """
+    provenance = Provenance.of(chunk_id)
+    names = list(dict.fromkeys(p.strip() for p in parties if p.strip()))
+    mentions = [
+        EntityMention(text=name, entity_type=ORGANIZATION, confidence=ConfidenceTag.EXTRACTED)
+        for name in names
+    ]
+    relationships = [
+        RelationshipFact(
+            provenance=provenance, confidence=ConfidenceTag.EXTRACTED,
+            source_ref=names[i], relationship_type=CONTRACTS_WITH, target_ref=names[j],
+        )
+        for i in range(len(names))
+        for j in range(i + 1, len(names))
+    ]
+    return ExtractionResult(chunk_id=chunk_id, entity_mentions=mentions, relationship_facts=relationships)
+
+
+# --- issue 0027: corporate AFFILIATION extraction (AFFILIATE_OF) ---------------------------------
+# The reference pack declares the `AFFILIATE_OF` edge and both `write_graph` and `graph_query` handle it, but
+# nothing ever PRODUCED the edge, so corporate affiliation was unanswerable. Affiliation is stated in the text
+# ("Acme Holdings Ltd, an affiliate of Acme Corp"), so -- unlike the structural `CONTRACTS_WITH` -- it needs a
+# text-reading extraction. This runs once per contract on the preamble (like party extraction), gated by a lexical
+# pre-filter so contracts that state no affiliation cost no LLM call. Entities are NOT merged (an affiliate is a
+# separate legal entity); only the edge between the two org nodes is added.
+
+_AFFIL_PREAMBLE_CHARS = 8000  # affiliations, like parties, are named in the preamble; bound the LLM input
+
+# Lexical pre-filter: no affiliation cue in the text -> no LLM call. A miss is a false-negative (missed
+# affiliation); a spurious hit just costs a call that returns nothing. Prompt-engineering overlay (ADR-0066: the
+# relationship TYPE is ontology-declared; these cue words are mechanism, not the closed vocabulary).
+_AFFILIATION_CUE_RE = re.compile(
+    r"\b(affiliate|affiliated|subsidiar|parent\s+compan|wholly[\s-]?owned|under\s+common\s+control|"
+    r"a\s+division\s+of|owned\s+by)\b", re.IGNORECASE)
+
+_AFFILIATION_PROMPT = (
+    "From this contract text, extract statements of CORPORATE AFFILIATION -- where one organization is stated to "
+    "be an affiliate, subsidiary, parent, division of, or under common control with ANOTHER organization. For each, "
+    "give the organization and the organization it is affiliated with. Do NOT treat two organizations merely "
+    "signing the same contract as an affiliation. If none is stated, return no items.\n\nTEXT:\n{text}")
+
+
+class Affiliation(BaseModel):
+    """One corporate-affiliation statement (issue 0027): `organization` is stated to be an affiliate/subsidiary/
+    parent of / under common control with `affiliate_of`. Both are ORGANIZATION surface forms."""
+
+    organization: str = ""
+    affiliate_of: str = ""
+
+
+class Affiliations(BaseModel):
+    """The tag-parse output of the affiliation extraction: zero or more `Affiliation` pairs."""
+
+    affiliations: list[Affiliation] = []
+
+
+def affiliations_to_extraction(chunk_id: ChunkId, affiliations: list) -> ExtractionResult:
+    """Corporate-affiliation pairs -> ORGANIZATION mentions for BOTH orgs (so both endpoints resolve to nodes) +
+    an `AFFILIATE_OF` fact between them, EXTRACTED (issue 0027). Entities are NOT merged; only the edge is added.
+    Each `affiliations` item is a 2-tuple/list `(organization, affiliate_of)`. Strips/dedups; a pair with an empty
+    or self-referential side is dropped."""
+    provenance = Provenance.of(chunk_id)
+    mentions: list[EntityMention] = []
+    facts: list[RelationshipFact] = []
+    seen: set[str] = set()
+    for pair in affiliations:
+        org = (pair[0] or "").strip()
+        affil_of = (pair[1] or "").strip()
+        if not org or not affil_of or org.lower() == affil_of.lower():
+            continue
+        for name in (org, affil_of):
+            if name.lower() not in seen:
+                seen.add(name.lower())
+                mentions.append(EntityMention(
+                    text=name, entity_type=ORGANIZATION, confidence=ConfidenceTag.EXTRACTED))
+        facts.append(RelationshipFact(
+            provenance=provenance, confidence=ConfidenceTag.EXTRACTED,
+            source_ref=org, relationship_type=AFFILIATE_OF, target_ref=affil_of))
+    return ExtractionResult(chunk_id=chunk_id, entity_mentions=mentions, relationship_facts=facts)
+
+
+async def aextract_affiliations(text: str, *, model_id: str = DEFAULT_GRAPH_EXTRACT_MODEL) -> list[tuple[str, str]]:
+    """Extract corporate-affiliation pairs from `text` (issue 0027). LEXICAL PRE-FILTER first: no affiliation cue
+    word -> no LLM call (near-zero added ingestion cost, since most contracts state none). On a cue hit, a lean
+    client-side tag-parse extraction over the preamble (ADR-0045). Degrades to no affiliations on any parse
+    failure (never raised)."""
+    if not _AFFILIATION_CUE_RE.search(text or ""):
+        return []
+    from rag_wright.models.tag_structured import build_tag_structured
+
+    try:
+        out = await build_tag_structured(model_id, Affiliations, label="affiliations").ainvoke(
+            _AFFILIATION_PROMPT.format(text=text[:_AFFIL_PREAMBLE_CHARS]))
+    except Exception:  # noqa: BLE001 - a persistent client-side parse failure -> no affiliations, not a crash
+        return []
+    if out is None:
+        return []
+    return [(a.organization, a.affiliate_of) for a in out.affiliations
+            if (a.organization or "").strip() and (a.affiliate_of or "").strip()]
+
+
+class DoclingGraphExtractor:
+    """GP-1B: docling-graph party extraction (granite-4.2-8b) -- the adopted graph extractor (ADR-0035).
+
+    Extracts the signing parties from the chunk text via the injected `extract_fn` (docling-graph
+    `extract_parties`), then emits ORGANIZATION mentions + structural `CONTRACTS_WITH` facts between them. A
+    chunk that yields no parties returns an empty `ExtractionResult` (never raised). `extract_fn` is injected so
+    the extractor is hermetic in tests (a stub returning a `ContractParties`-shaped object with `.parties[].name`).
+    """
+
+    name = "docling_graph"
+
+    def __init__(self, extract_fn: PartyExtractFn) -> None:
+        self._extract_fn = extract_fn
+
+    def extract(self, chunk_id: ChunkId, text: str) -> ExtractionResult:
+        extracted = self._extract_fn(text)
+        names = [p.name for p in extracted.parties] if extracted is not None else []
+        return parties_to_extraction(chunk_id, names)
+
+
+def production_extract_fn(*, model_id: str = DEFAULT_GRAPH_EXTRACT_MODEL) -> PartyExtractFn:
+    """Bind the real docling-graph party extractor to `(text) -> ContractParties | None` (granite via OpenRouter).
+    Lazy import so the module stays import-light and hermetic (tests inject a stub instead)."""
+    from rag_wright.capabilities.dg_extraction import default_extraction_model, extract_parties
+
+    model = default_extraction_model("graph-extract", model_id)  # ADR-0100: profile-routed (RAG_SERVING/pin)
+    return lambda text: extract_parties(text, model)
+
+
+def aproduction_extract_fn(*, model_id: str = DEFAULT_GRAPH_EXTRACT_MODEL):
+    """ASYNC-B2c (ADR-0057): the async twin of `production_extract_fn` -- party extraction on the async
+    docling-graph seam (`aextract_parties`, true wall-clock deadline). Returns an async `(text) -> ContractParties
+    | None`."""
+    from rag_wright.capabilities.dg_extraction import aextract_parties, default_extraction_model
+
+    model = default_extraction_model("graph-extract", model_id)  # ADR-0100: profile-routed (RAG_SERVING/pin)
+
+    async def _afn(text: str):
+        return await aextract_parties(text, model)
+
+    return _afn
+
+
+def default_extractors() -> list[Extractor]:
+    """The default extractor: the GP-1B docling-graph party extractor (the live wiring; ADR-0035)."""
+    return [DoclingGraphExtractor(production_extract_fn())]
+
+
+async def extract_chunks(
+    items: list[tuple[ChunkId, str]],
+    *,
+    extractors: list[Extractor],
+    max_concurrency: int = DEFAULT_EXTRACT_CONCURRENCY,
+) -> list[ExtractionResult]:
+    """Extract facts from chunks concurrently (FR-I.6): each chunk's extractor stack runs in a thread,
+    bounded by a semaphore so bulk mode saturates the GPU/provider without unbounded in-flight work."""
+    semaphore = asyncio.Semaphore(max_concurrency)
+
+    async def _one(chunk_id: ChunkId, text: str) -> ExtractionResult:
+        async with semaphore:  # backpressure
+            return await asyncio.to_thread(run_extractors, extractors, chunk_id, text)
+
+    return list(await asyncio.gather(*(_one(chunk_id, text) for chunk_id, text in items)))
+
+
+def extract_chunks_sync(
+    items: list[tuple[ChunkId, str]],
+    *,
+    extractors: list[Extractor],
+    max_concurrency: int = DEFAULT_EXTRACT_CONCURRENCY,
+) -> list[ExtractionResult]:
+    """Synchronous convenience for callers not already in an event loop."""
+    return asyncio.run(extract_chunks(items, extractors=extractors, max_concurrency=max_concurrency))
+
+
+def register_graph_extraction(registry: CapabilityRegistry) -> None:
+    """Register graph extraction under FR-C.6 (`graph_extraction`, a `subgraph`; GP-1B docling-graph, ADR-0035)."""
+    registry.register(
+        "graph_extraction",
+        contract=ExtractionResult,
+        kind="subgraph",  # multi-step extractor workflow (CAP-REG-1)
+        display_name="Graph extraction (GP-1B docling-graph party/relational)",
+    )

rag_wright/capabilities/graph_query.py

@@ -0,0 +1,73 @@
+"""Graph query (FR-C.5, FR-Q.3, T26): answer relational/multi-hop questions by graph traversal.
+
+Traverses the knowledge graph (T25) from a start entity over relationship edges and returns the answer
+shaped as EVIDENCE for fusion (T27) — cited `chunk_id`s, `entity_id`s, and confidence tags — treated as
+evidence to verify, not truth (SPEC §8/§14), never a final ranked list. It **surfaces** confidence on
+every path; it does **not** filter or down-weight edges by confidence (FR-C.5/FR-Q.3). Acting on
+confidence — being confidence-aware, abstaining — is the answer generator's job (FR-Q.6 / T29).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.document_scope import validate_documents
+from rag_wright.store.seam import Store
+
+
+class GraphEvidence(BaseModel):
+    """One reached entity as a cited evidence item (not a scored result)."""
+
+    entity_id: str  # the reached entity (a candidate answer)
+    name: str
+    hops: int
+    path_entity_ids: list[str]  # the entity_id chain from start to target (the traversal evidence)
+    chunk_ids: list[str]  # the chunks the path's edges were extracted from (no claim without a citation)
+    confidences: list[str]  # the confidence tag of each edge on the path (surfaced, not filtered)
+
+
+class GraphAnswer(BaseModel):
+    """The graph query capability's output: candidate answers as evidence for fusion (FR-C.5, FR-Q.3)."""
+
+    start_entity_id: str
+    relationship_type: str
+    evidence: list[GraphEvidence]  # evidence for fusion (T27), NOT a final ranked list
+
+
+def graph_query(
+    start_entity_id: str,
+    *,
+    store: Store,
+    relationship_type: str,
+    max_hops: int = 1,
+    documents: Optional[list[str]] = None,
+) -> GraphAnswer:
+    """Traverse `relationship_type` (a generic edge-type string -- the CALLER names it; no domain default) from
+    `start_entity_id` up to `max_hops` and return cited evidence.
+
+    Every edge on every path is surfaced with its `chunk_id` and confidence tag; no edge is dropped or
+    re-weighted by confidence here (that is the generator's job, FR-Q.6). The evidence is unranked.
+
+    `documents` (issue 0031): scope the traversal to a workspace's source documents -- EVERY edge on a path
+    must belong to one of them (so a multi-hop path cannot route through an out-of-scope document). `None` =
+    the whole graph; an unknown id RAISES (`UnknownDocumentError`); `[]` = scope-to-nothing (no evidence).
+    """
+    validate_documents(store, documents)  # reject an unknown document BEFORE the traversal (issue 0031)
+    rows = store.graph_neighbors(
+        start_entity_id, relationship_type=relationship_type, max_hops=max_hops, documents=documents
+    )
+    evidence = [
+        GraphEvidence(
+            entity_id=row["target_id"], name=row["target_name"], hops=row["hops"],
+            path_entity_ids=row["path_entity_ids"], chunk_ids=row["path_chunk_ids"],
+            confidences=row["path_confidences"],
+        )
+        for row in rows
+    ]
+    return GraphAnswer(
+        start_entity_id=start_entity_id, relationship_type=relationship_type, evidence=evidence
+    )
+
+

rag_wright/capabilities/graph_storage.py

@@ -0,0 +1,111 @@
+"""Graph storage (FR-I.4, FR-I.5, T25): write resolved entities + relationships into the store, gated.
+
+A seam-bound ingestion pipeline step (no SPEC section-5 slug, so it registers nothing and authors no
+ARD manifest — like chunk write, T20). It maps a document's T24 `ResolutionResult` to store-level
+nodes and edges and writes them through the `Store` seam in ONE transaction (FR-S.1: a chunk and its
+extracted entities land together), content-hash gated so an unchanged document does no graph work
+(FR-I.5). The graph is the relationship layer only (SPEC §8): entity nodes carry id/name/type and edges
+carry the relationship — no heavy structured data.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional
+
+from rag_wright.capabilities.entity_resolution import ResolutionResult
+from rag_wright.corpus.canonicalize import normalize_entity_name
+from rag_wright.store.seam import GraphEdge, GraphNode, Store
+
+GraphWriteStatus = Literal["written", "skipped"]
+
+
+@dataclass(frozen=True)
+class GraphWriteResult:
+    """The outcome of writing one document's graph."""
+
+    source_doc_id: str
+    status: GraphWriteStatus
+    node_count: int
+    edge_count: int
+
+
+def _node_key(entity_id: Optional[str], surface_key: str) -> str:
+    """The vertex identity: the resolver's canonical id when linked, else an `UNLINKED:<key>` surrogate (so a
+    canonical-id lookup matches only linked entities, and an unlinked ref lands on the same node as its cluster)."""
+    return entity_id if entity_id else f"UNLINKED:{surface_key}"
+
+
+def to_graph(resolution: ResolutionResult) -> tuple[list[GraphNode], list[GraphEdge]]:
+    """Map a `ResolutionResult` to store nodes + edges. A relationship endpoint that has no standalone
+    entity (a ref-only endpoint) gets a minimal node so every edge connects to a vertex."""
+    nodes: dict[str, GraphNode] = {}
+    for entity in resolution.entities:
+        key = _node_key(entity.entity_id, entity.key)
+        nodes[key] = GraphNode(
+            node_key=key, entity_id=entity.entity_id or "", name=entity.representative,
+            entity_type=entity.entity_type, confidence=entity.confidence.value,
+            chunk_id=entity.chunk_ids[0] if entity.chunk_ids else "",
+        )
+
+    edges: list[GraphEdge] = []
+    for rel in resolution.relationships:
+        source_key = _node_key(rel.source_id, normalize_entity_name(rel.source_ref))
+        target_key = _node_key(rel.target_id, normalize_entity_name(rel.target_ref))
+        for key, resolved_id, ref in (
+            (source_key, rel.source_id, rel.source_ref),
+            (target_key, rel.target_id, rel.target_ref),
+        ):
+            nodes.setdefault(  # ref-only endpoint: minimal node (type UNKNOWN -- a bare ref carries no type; DD-5)
+                key,
+                GraphNode(
+                    node_key=key, entity_id=resolved_id or "", name=ref,
+                    entity_type="", confidence=rel.confidence.value,
+                    chunk_id=rel.chunk_id,
+                ),
+            )
+        edges.append(
+            GraphEdge(
+                source_key=source_key, target_key=target_key,
+                relationship_type=rel.relationship_type, confidence=rel.confidence.value,
+                chunk_id=rel.chunk_id,
+            )
+        )
+    return list(nodes.values()), edges
+
+
+class GraphWriter:
+    """Writes a document's resolved graph to the store, content-hash gated (FR-I.5). A checkpoint per
+    document keyed by content hash makes an unchanged document a no-op; the store holds the graph."""
+
+    def __init__(self, store: Store, *, checkpoint_dir: Path) -> None:
+        self._store = store
+        self._checkpoints = Path(checkpoint_dir) / "graph_checkpoints"
+        self._checkpoints.mkdir(parents=True, exist_ok=True)
+
+    def write_document(
+        self, source_doc_id: str, content_hash: str, resolution: ResolutionResult
+    ) -> GraphWriteResult:
+        """Write the document's nodes/edges (one transaction), unless an unchanged run already did."""
+        checkpoint = self._load(source_doc_id)
+        if checkpoint is not None and checkpoint["content_hash"] == content_hash:
+            return GraphWriteResult(source_doc_id, "skipped", 0, 0)  # content-hash gate: no graph work
+
+        nodes, edges = to_graph(resolution)
+        self._store.write_graph(nodes, edges)
+        self._save(source_doc_id, content_hash)
+        return GraphWriteResult(source_doc_id, "written", len(nodes), len(edges))
+
+    def _path(self, source_doc_id: str) -> Path:
+        return self._checkpoints / f"{source_doc_id}.json"
+
+    def _load(self, source_doc_id: str) -> Optional[dict]:
+        path = self._path(source_doc_id)
+        return json.loads(path.read_text(encoding="utf-8")) if path.exists() else None
+
+    def _save(self, source_doc_id: str, content_hash: str) -> None:
+        self._path(source_doc_id).write_text(
+            json.dumps({"content_hash": content_hash, "status": "complete"}), encoding="utf-8"
+        )

rag_wright/capabilities/highlight_serve.py

@@ -0,0 +1,142 @@
+"""CU-C2: serve + citation -- turn a `QueryIntent` about a KNOWN contract into a `HighlightResult`.
+
+Given `(query, contract_id, QueryIntent)`, this is the back half of the CUAD front door:
+
+  in-taxonomy, intent=highlight     -> typed within-contract filter -> the span SET (empty => "not present")
+  in-taxonomy, intent=extract       -> the set, then field-extract `value_to_extract` from each matched span
+  in-taxonomy, intent=discriminate  -> the set; the value_condition discriminator + (b) rerank is STUBBED
+                                        (passthrough hook -- the set is small: a handful of same-type spans)
+  out-of-taxonomy (in_taxonomy=False) -> semantic fallback over ALL the contract's spans + low-confidence flag
+
+Every returned span carries its exact document location (`doc_start`/`doc_end` from `SpanRecord`, CU-B2) so an
+app can highlight it. `structured_factory`/`embedder`/`store` are injected so the routing is tested
+hermetically; the field-extraction LLM calls run concurrently (the standing eval/serve concurrency rule).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.highlight import HighlightResult, HighlightSpan
+from rag_wright.contracts.query_intent import QueryIntent
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.tag_structured import build_tag_structured  # ADR-0045: LLM-agnostic client-side output
+
+DEFAULT_FALLBACK_K = 5
+_EXTRACT_CONCURRENCY = 8
+
+_EXTRACT_PROMPT = (
+    "From the following contract clause, extract {value}. Return ONLY the value as written in the clause; "
+    "if the clause does not state it, return null.\n\nClause:\n{text}"
+)
+
+
+class _Extracted(BaseModel):
+    value: str | None = None
+
+
+def _decode_bbox(raw) -> tuple[float, float, float, float] | None:
+    """issue 0032: the store keeps bbox as a JSON `[l,t,r,b]` string (best-effort); decode to a tuple or None."""
+    if not raw:
+        return None
+    try:
+        vals = json.loads(raw) if isinstance(raw, str) else raw
+        return (float(vals[0]), float(vals[1]), float(vals[2]), float(vals[3])) if vals else None
+    except (ValueError, TypeError, IndexError):
+        return None
+
+
+def _to_span(row: dict, *, confidence: float, extracted_value: str | None = None) -> HighlightSpan:
+    pages = [int(p) for p in (row.get("pages") or [])]  # issue 0032: source page(s) for the citation highlight
+    return HighlightSpan(
+        span_id=row["span_id"],
+        contract_id=row["contract_id"],
+        function=row.get("function", ""),
+        clause_ref=row.get("parent_chunk_id", ""),  # heading/number not extracted yet -> the clause id
+        text=row["text"],
+        doc_start=row.get("doc_start"),
+        doc_end=row.get("doc_end"),
+        page=(pages[0] if pages else row.get("page")),  # FIRST page (== pages[0] when known)
+        pages=pages,
+        bbox=_decode_bbox(row.get("bbox")),
+        extracted_value=extracted_value,
+        confidence=confidence,
+    )
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = sum(x * x for x in a) ** 0.5
+    nb = sum(y * y for y in b) ** 0.5
+    return dot / (na * nb) if na and nb else 0.0
+
+
+def _field_extract(spans: list[HighlightSpan], value_to_extract: str, factory, model_id: str) -> list[HighlightSpan]:
+    """One structured call per matched span (concurrent) to pinpoint `value_to_extract` within it."""
+
+    def _one(sp: HighlightSpan) -> HighlightSpan:
+        try:
+            out = factory(model_id, _Extracted).invoke(
+                _EXTRACT_PROMPT.format(value=value_to_extract, text=sp.text)
+            )
+            value = None if out is None else out.value
+        except Exception:  # noqa: BLE001 - a persistent client-side parse failure -> no value (best-effort extract)
+            value = None
+        return sp.model_copy(update={"extracted_value": value})
+
+    async def _run() -> list[HighlightSpan]:
+        sem = asyncio.Semaphore(_EXTRACT_CONCURRENCY)
+
+        async def _guarded(sp: HighlightSpan) -> HighlightSpan:
+            async with sem:
+                return await asyncio.to_thread(_one, sp)
+
+        return await asyncio.gather(*[_guarded(sp) for sp in spans])
+
+    return asyncio.run(_run())
+
+
+def serve_highlight(
+    query: str,
+    contract_id: str,
+    intent: QueryIntent,
+    *,
+    store,
+    embedder=None,
+    structured_factory=build_tag_structured,
+    model_id: str | None = None,
+    fallback_k: int = DEFAULT_FALLBACK_K,
+) -> HighlightResult:
+    """Serve a `QueryIntent` against one contract into a cited `HighlightResult`. In-taxonomy routes through
+    the typed within-contract filter; out-of-taxonomy falls back to contract-scoped semantic ranking with a
+    low-confidence flag. See the module docstring for the four branches."""
+    model_id = model_id or model_for(ModelRole.STRUCTURED_REASONING)
+    low_confidence = False
+
+    if intent.in_taxonomy:
+        rows = store.spans_by_contract(contract_id, intent.clause_types)
+        spans = [_to_span(r, confidence=intent.confidence) for r in rows]
+        if intent.intent == "extract" and intent.value_to_extract and spans:
+            spans = _field_extract(spans, intent.value_to_extract, structured_factory, model_id)
+        # intent == "discriminate": the value_condition discriminator + (b) rerank is stubbed -> passthrough.
+    else:
+        rows = store.all_spans_by_contract(contract_id)
+        query_vec = embedder.encode_dense(query) if embedder is not None else None
+        if query_vec is not None:
+            rows = sorted(rows, key=lambda r: _cosine(query_vec, r["dense"]), reverse=True)
+        spans = [_to_span(r, confidence=intent.confidence) for r in rows[:fallback_k]]
+        low_confidence = True
+
+    return HighlightResult(
+        query=query,
+        contract_id=contract_id,
+        clause_types=intent.clause_types,
+        intent=intent.intent,
+        spans=spans,
+        present=bool(spans),
+        in_taxonomy=intent.in_taxonomy,
+        low_confidence=low_confidence,
+    )