rag-wright 0.1.0__py3-none-any.whl

rag_wright/subgraphs/graph_extraction.py

@@ -0,0 +1,102 @@
+"""LG-2: `graph_extraction` as a granular, PARALLEL LangGraph subgraph.
+
+The extractor stack (FR-C.6), behind the `Extractor` seam, expressed as a fan-out/fan-in graph rather than a
+sequential `run_extractors` loop. The default stack is now the single GP-1B docling-graph party extractor
+(ADR-0035; the retired T23-27 hybrid was spaCy NER + contract-LLM + escalation), but the graph is generic over
+any list of extractors:
+
+        START
+       /  |  \\           (one node per extractor, run in parallel)
+     ex0 ex1 ...
+       \\  |  /
+        merge            (ExtractionResult.merge over all results)
+          |
+         END
+
+- **parallel fan-out**: the extractors are independent (each reads the same chunk text), so they run in one
+  superstep; each appends its `ExtractionResult` to a reducer-accumulated `results` list (no write conflict).
+- **graceful degradation**: an extractor that fails after retries contributes an EMPTY `ExtractionResult`
+  (via runtime.execution_info.node_attempt) rather than dropping the whole chunk -- partial facts beat none.
+- **observability**: the GP-1B extractor calls docling-graph (a raw-SDK call that bypasses LangChain), so it
+  is INVISIBLE to tracing unless wrapped -- each extractor node is wrapped in `raw_llm_span` per the
+  GraphWright observability contract.
+- **merge**: `ExtractionResult.merge` combines mentions + clause/relationship facts, deterministically.
+
+`extractors` is injected (defaulting to `default_extractors()`), so the graph is hermetically testable with
+stub extractors -- no live docling-graph / no network.
+"""
+
+from __future__ import annotations
+
+import operator
+from typing import Annotated, Any, Optional, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.runtime import Runtime
+
+from rag_wright.capabilities.graph_extraction import Extractor, default_extractors
+from rag_wright.contracts.extraction import ExtractionResult
+from rag_wright.contracts.identifiers import ChunkId
+from rag_wright.subgraphs.scaffold import DEFAULT_RETRY, raw_llm_span
+from rag_wright.subgraphs.typed_clause_extraction import TransientExtraction  # retryable-blip signal
+
+
+class GraphExtractionState(TypedDict, total=False):
+    chunk_id: ChunkId
+    text: str
+    results: Annotated[list, operator.add]  # each extractor node appends its ExtractionResult (reducer)
+    result: ExtractionResult  # the merged output
+
+
+def _extractor_node(extractor: Extractor, max_attempts: int):
+    name = getattr(extractor, "name", extractor.__class__.__name__)
+
+    def node(state: GraphExtractionState, runtime: Runtime) -> GraphExtractionState:
+        attempt = runtime.execution_info.node_attempt
+        # GP-1B docling-graph is a raw-SDK call (ADR-0035); the model id is carried by the extractor.
+        with raw_llm_span(f"graph_extraction.{name}", model=getattr(extractor, "model_id", "docling-graph")):
+            try:
+                result = extractor.extract(state["chunk_id"], state["text"])
+            except Exception as exc:  # noqa: BLE001 - retry (as a transient), or degrade to empty on exhaustion
+                if attempt >= max_attempts:
+                    return {"results": [ExtractionResult(chunk_id=state["chunk_id"])]}  # graceful: no facts
+                raise TransientExtraction(str(exc)) from exc  # normalize so the RetryPolicy retries it
+        return {"results": [result]}
+
+    return node
+
+
+def build_graph_extraction(
+    extractors: Optional[list[Extractor]] = None,
+    *,
+    retry_policy: Any = DEFAULT_RETRY,
+):
+    """Compile the `graph_extraction` subgraph (per chunk). `extractors` is injected (defaulting to the live
+    hybrid stack). `retry_policy` is each extractor node's policy (overridable for fast tests)."""
+
+    extractors = extractors if extractors is not None else default_extractors()
+    max_attempts = int(getattr(retry_policy, "max_attempts", 3))
+
+    def merge(state: GraphExtractionState) -> GraphExtractionState:
+        return {"result": ExtractionResult.merge(state["chunk_id"], state.get("results", []))}
+
+    g = StateGraph(GraphExtractionState)
+    g.add_node("merge", merge)
+    for i, extractor in enumerate(extractors):
+        name = f"extract_{i}_{getattr(extractor, 'name', 'x')}"
+        g.add_node(name, _extractor_node(extractor, max_attempts), retry_policy=retry_policy)
+        g.add_edge(START, name)   # fan-out: all extractors run in parallel
+        g.add_edge(name, "merge")  # fan-in: merge runs after all complete
+    g.add_edge("merge", END)
+    return g.compile()
+
+
+def register_graph_extraction_subgraph(registry) -> None:
+    """LG-2: register `graph_extraction` (subgraph). The manifest/slug already exist (reclassified in
+    CAP-REG-1); this binds the LangGraph runnable's contract (ExtractionResult)."""
+    registry.register(
+        "graph_extraction",
+        contract=ExtractionResult,
+        kind="subgraph",
+        display_name="Graph extraction (GP-1B docling-graph party/relational)",
+    )

rag_wright/subgraphs/intra_document_qa.py

@@ -0,0 +1,328 @@
+"""LG-3b: `intra_document_qa` as a composite LangGraph subgraph.
+
+Answer a question scoped to ONE contract with a grounded, cited answer, composing the intra-contract scoped
+KG query (KG-4, `contract_kg_serve`) with grounded answer generation (FR-Q.6):
+
+    START --> serve [RetryPolicy]  (scoped KG query: contract_id + question -> cited CitedClauses)
+                 |
+                 v
+             assemble [RetryPolicy]  (rehydrate each clause's REAL span text -> cited EvidenceItem)
+                 |                     --orphan span--> dead_letter --> END
+                 v
+             generate  (generate_answer: grounded/cited/abstaining answer)  --> END
+
+Query-side posture (matches `query_constraint_extraction` / `relational_qa`): judicious hardening.
+  - **serve** retries a transient store blip; on retry exhaustion it DEGRADES to no clauses -> empty evidence
+    -> the generator abstains, so the query is never dropped.
+  - **assemble** rehydrates each served clause to its OPERATIVE SPAN TEXT (the clause node stores only
+    id/function/folio; the text lives on the SPAN records, reached via each clause's `span_id` provenance).
+    The evidence the generator reads is the real clause language, cited by `clause_id`, with the typed
+    `(dimension, value)` facts appended and the worst-case property confidence surfaced (FR-S.4). A span_id
+    the store cannot resolve (an orphan) dead-letters rather than fabricating; a property-less clause (no
+    span) cites its function label. A transient rehydration blip retries, then dead-letters on exhaustion.
+  - **generate** enforces no-claim-without-a-citation in code (FR-Q.6): empty evidence abstains with no model
+    call; fabricated citations are dropped.
+
+`serve_fn` / `clause_text_fn` / `generate_fn` are dependency-injected so the graph is hermetically testable
+with stubs -- no live LLM or store. `production_intra_document_qa` wires the real scoped query
+(function-classified + serve), the span-text rehydration (`spans_by_contract`), and `generate_answer`. None is
+a raw-SDK call (serve/rehydrate are store reads; generate_answer uses the LangChain seam, auto-captured), so
+per-node visibility is a `business_span`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Optional, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.runtime import Runtime
+
+from rag_wright.capabilities.answer_generator import EvidenceItem, GeneratedAnswer
+from rag_wright.capabilities.clause_exception_linking import CAP_FUNCTION
+from rag_wright.capabilities.contract_kg_serve import CitedClause, CitedProperty
+from rag_wright.contracts.provenance import ConfidenceTag
+from rag_wright.models import tracing  # 0048: emit retrieval as a Langfuse span, split from the generation
+from rag_wright.subgraphs.scaffold import DEFAULT_RETRY, business_span, dead_letter
+from rag_wright.subgraphs.typed_clause_extraction import TransientExtraction  # shared retryable-blip signal
+
+# serve_fn: (contract_id, question) -> the scoped clauses (must raise on a transient store blip).
+ServeFn = Callable[[str, str], list[CitedClause]]
+# clause_text_fn: (contract_id, clauses) -> {clause_id: operative-span text}; a clause with a span_id that
+# cannot be resolved raises KeyError (no silent drop); a property-less clause is simply absent from the map.
+ClauseTextFn = Callable[[str, list[CitedClause]], dict[str, str]]
+# ASYNC-C1 (ADR-0057): generate_fn is async (the model call gets a true wall-clock deadline via the seam).
+GenerateFn = Callable[[str, list[EvidenceItem]], Awaitable[GeneratedAnswer]]
+
+# Worst-case provenance surfaced to the generator: the least-trusted tag among a clause's properties wins.
+_CONFIDENCE_ORDER = ("AMBIGUOUS", "INFERRED", "EXTRACTED")
+
+
+class IntraDocumentQAState(TypedDict, total=False):
+    contract_id: str
+    question: str
+    clauses: list[CitedClause]
+    evidence: list[EvidenceItem]
+    answer: GeneratedAnswer
+    dead_letter: Optional[dict]
+
+
+def _clause_confidence(properties: list[CitedProperty]) -> Optional[str]:
+    tags = {p.confidence for p in properties if p.confidence}
+    for tag in _CONFIDENCE_ORDER:  # worst-case first
+        if tag in tags:
+            return tag
+    return None
+
+
+def _humanize_properties(clause: CitedClause) -> str:
+    """Body-less path (issue 0011): render typed facts as reader-safe natural text -- NOT the `[dim=value]`
+    schema syntax the model latched onto and paraphrased. Domain-agnostic prettify (snake_case -> spaces); the
+    structured form still rides out-of-band on `EvidenceItem.properties`. No `[`, no `=`, no backticks."""
+    def pretty(s: str) -> str:
+        return str(s).replace("_", " ")
+    return "; ".join(f"{pretty(p.dimension)}: {pretty(p.value)}" for p in clause.properties)
+
+
+def _clause_to_evidence(clause: CitedClause, body: Optional[str]) -> Optional[EvidenceItem]:
+    """One cited evidence item: the clause's REAL span text (when rehydrated), cited by `clause_id`, confidence
+    surfaced. Typed properties ride OUT-OF-BAND on `EvidenceItem.properties`, never in the evidence text.
+
+    Engine issue 0002 / ADR-0054: the KG-assigned function label is NOT put in the evidence text (it was the
+    source of the auto-tag paraphrase leak -- a sometimes-wrong classification narrated in the engine's voice).
+
+    Engine issue 0011 / ADR-0064: the SAME move for typed properties. They used to be concatenated into the text
+    as `[dimension=value; ...]`; the model paraphrased that schema string into prose ("as indicated by the typed
+    property cap_quantum=..."), around the bracket scrub. They now travel out-of-band on `EvidenceItem.properties`
+    (code-generated `{dimension, value}`), so the generator never sees the schema tokens and narration is
+    structurally impossible. The body span already states in natural language what the properties encode, so
+    dropping them from the text costs the generator nothing; they stay available for the product's UI chips.
+
+    Body-less path: where a clause has NO span text, the properties are the only content, so they must stay
+    citable -- rendered as reader-safe natural text (`_humanize_properties`), never the `[dim=value]` syntax.
+
+    A clause with no span text AND no typed facts is contentless -- nothing to ground a citation on -- so it is
+    DROPPED (returns None), rather than cited by a bare function label (superseding PREC-1a's fallback)."""
+    props = [{"dimension": p.dimension, "value": p.value} for p in clause.properties] or None
+    if body:
+        text = body  # 0011: properties NOT appended -> the generator cannot quote the schema tokens
+    elif props:
+        text = _humanize_properties(clause)  # body-less: reader-safe natural text, still citable
+    else:
+        return None  # contentless: no span text, no facts -> not citable -> drop
+    if clause.exception_of:
+        # ADR-0044: an INFERRED carve-out/exception to a cap clause -> frame it as such and surface INFERRED
+        # confidence, so the generator answers "capped, EXCEPT ..." and treats it as inferred, never a hard claim.
+        return EvidenceItem(
+            chunk_id=clause.clause_id,
+            text=f"[Exception to the liability cap (inferred)] {text}",
+            confidence=ConfidenceTag.INFERRED.value, properties=props)
+    return EvidenceItem(chunk_id=clause.clause_id, text=text,
+                        confidence=_clause_confidence(clause.properties), properties=props)
+
+
+def attach_exception_links(
+    clauses: list[CitedClause], exceptions_fn: Callable[[str], list[dict]], *, contract_id: str
+) -> list[CitedClause]:
+    """ADR-0044 query consumption: for each served Cap clause, pull its `IsExceptionTo` carve-outs
+    (`exceptions_fn(cap_clause_id) -> [{clause_id, function, span_id}]`) and include them as INFERRED exceptions
+    (`exception_of` set), deduped. Pulls the cap's conditions into the evidence EVEN IF the classifier did not
+    return the Uncapped function -- that is the point. A clause already served (via classification) is marked
+    as this cap's exception; a not-yet-served one is added (property-less, rehydrated from its own span_id)."""
+    by_id = {c.clause_id: c for c in clauses}
+    for cap in list(clauses):
+        if cap.function != CAP_FUNCTION or cap.exception_of:
+            continue
+        for exc in exceptions_fn(cap.clause_id):
+            eid = exc.get("clause_id")
+            if not eid or eid == cap.clause_id:
+                continue
+            if eid in by_id:
+                if not by_id[eid].exception_of:
+                    by_id[eid].exception_of = cap.clause_id
+            else:
+                added = CitedClause(
+                    contract_id=contract_id, clause_id=eid, function=exc.get("function") or "",
+                    span_id=exc.get("span_id") or "", exception_of=cap.clause_id, properties=[])
+                by_id[eid] = added
+                clauses.append(added)
+    return clauses
+
+
+def rehydrate_clause_texts(store: Any, contract_id: str, clauses: list[CitedClause]) -> dict[str, str]:
+    """Map each clause to its operative-span TEXT for citation. A clause WITH typed properties uses its property
+    span_ids (grounding invariant: they MUST resolve, else KeyError). A PROPERTY-LESS clause uses its OWN
+    `span_id` (1:1, ADR-0025) -- real span text, not a bare function label, and never a function-label guess
+    (which is one-to-many). A clause with no span link at all (legacy pre-backfill) is omitted, and the evidence
+    builder falls back to the function label. This is why the clause-level span_id is persisted."""
+    functions = sorted({c.function for c in clauses if c.function})
+    text_by_span = {row["span_id"]: row["text"] for row in store.spans_by_contract(contract_id, functions)}
+    out: dict[str, str] = {}
+    for clause in clauses:
+        span_ids = list(dict.fromkeys(p.span_id for p in clause.properties if p.span_id))
+        if span_ids:
+            bodies = []
+            for span_id in span_ids:
+                if span_id not in text_by_span:  # property provenance MUST resolve (grounding invariant)
+                    raise KeyError(
+                        f"clause {clause.clause_id}: span {span_id!r} has no text in contract {contract_id}")
+                bodies.append(text_by_span[span_id])
+            out[clause.clause_id] = " ".join(bodies)
+        elif clause.span_id and clause.span_id in text_by_span:
+            out[clause.clause_id] = text_by_span[clause.span_id]  # property-less: its OWN span (1:1), real text
+    return out
+
+
+def build_intra_document_qa(
+    serve_fn: ServeFn,
+    clause_text_fn: ClauseTextFn,
+    generate_fn: GenerateFn,
+    *,
+    retry_policy: Any = DEFAULT_RETRY,
+):
+    """Compile the `intra_document_qa` subgraph. `serve_fn` / `clause_text_fn` / `generate_fn` are injected for
+    hermetic testing; `retry_policy` is the serve and assemble nodes' policy (overridable for fast tests)."""
+    max_attempts = int(getattr(retry_policy, "max_attempts", 3))
+
+    def serve(state: IntraDocumentQAState, runtime: Runtime) -> IntraDocumentQAState:
+        # node_attempt is 1-indexed; a transient blip re-raises so the RetryPolicy retries, EXCEPT on the
+        # final attempt where it degrades to NO clauses (the generator abstains -- the query is never lost).
+        attempt = runtime.execution_info.node_attempt
+        with business_span("intra_document_qa.serve", contract_id=state["contract_id"]), \
+                tracing.traced_step("intra_document_qa.serve"):  # 0048: retrieval span, separable from generate
+            try:
+                clauses = serve_fn(state["contract_id"], state["question"])
+            except Exception as exc:  # noqa: BLE001 - transient -> retry, or degrade to empty on exhaustion
+                if attempt >= max_attempts:
+                    return {"clauses": []}
+                raise TransientExtraction(str(exc)) from exc
+        return {"clauses": clauses}
+
+    def assemble(state: IntraDocumentQAState, runtime: Runtime) -> IntraDocumentQAState:
+        clauses = state.get("clauses", [])
+        if not clauses:
+            return {"evidence": []}
+        attempt = runtime.execution_info.node_attempt
+        contract_id = state["contract_id"]
+        with business_span("intra_document_qa.assemble", clause_count=len(clauses)), \
+                tracing.traced_step("intra_document_qa.assemble"):  # 0048: rehydration/retrieval span
+            try:
+                texts = clause_text_fn(contract_id, clauses)
+            except KeyError as exc:  # an orphan span_id is a pipeline inconsistency: surface, never fabricate
+                return {"dead_letter": dead_letter(
+                    "clause_text_orphan_span", contract_id=contract_id, error=str(exc))}
+            except Exception as exc:  # noqa: BLE001 - transient store blip -> retry, or dead-letter on exhaust
+                if attempt >= max_attempts:
+                    return {"dead_letter": dead_letter(
+                        "clause_text_rehydration_failed", contract_id=contract_id, error=str(exc))}
+                raise TransientExtraction(str(exc)) from exc
+        # drop contentless clauses (no span text, no facts) -> None (engine issue 0002 / ADR-0054)
+        evidence = [ev for c in clauses if (ev := _clause_to_evidence(c, texts.get(c.clause_id))) is not None]
+        return {"evidence": evidence}
+
+    async def generate(state: IntraDocumentQAState) -> IntraDocumentQAState:
+        with business_span("intra_document_qa.generate"):
+            answer = await generate_fn(state["question"], state.get("evidence", []))
+        return {"answer": answer}
+
+    g = StateGraph(IntraDocumentQAState)
+    g.add_node("serve", serve, retry_policy=retry_policy)
+    g.add_node("assemble", assemble, retry_policy=retry_policy)
+    g.add_node("generate", generate)
+    g.add_edge(START, "serve")
+    g.add_edge("serve", "assemble")
+    g.add_conditional_edges("assemble", lambda s: "end" if s.get("dead_letter") else "generate",
+                            {"generate": "generate", "end": END})
+    g.add_edge("generate", END)
+    return g.compile()
+
+
+def _answer_model_for_impl(model_id: str | None = None, **kwargs: Any) -> Any:
+    """Indirection over `answer_model_for` so `production_intra_document_qa` can default the answer model (and
+    tests can monkeypatch this hook). Lazy import keeps the subgraph module import-light."""
+    from rag_wright.capabilities.answer_generator import answer_model_for
+    return answer_model_for(model_id, **kwargs)
+
+
+def production_intra_document_qa(
+    *, store: Any, reranker: Any = None, answer_model: Any = None, answer_model_id: str | None = None,
+    top_k: int = 12,
+):
+    """Wire the real scoped query + span-text rehydration + `generate_answer` into the composite. `serve` takes
+    the WHOLE per-contract clause KG (`contract_clause_index`) and ranks it by BGE cross-encoder relevance to the
+    question, serving only the top-`k` (bounded evidence). Rehydration maps each clause's `span_id` provenance to
+    its operative-span text (`spans_by_contract`, contract-scoped and light -- no dense vectors).
+
+    ADR-0047: the function-classifier narrowing (`clauses_of_function`) was REPLACED by this SEMANTIC narrowing --
+    a clause mislabel can no longer hide the real clause (BGE ranks by MEANING, not the LegalBERT label), while
+    the top-`k` cap keeps generation bounded (a contract can hold 100+ clauses ~= 13k tokens, too much to dump
+    whole). The `reranker` defaults to `BGEReranker` (injectable for tests / the A100 path).
+
+    The answer model defaults to `answer_model_for(answer_model_id)` (GENERAL role when None), so the configured
+    generation model automatically takes the RIGHT path -- the client-side free-text tag-parse for a
+    `client_side_structured` model (self-hosted Gemma), the structured-output seam otherwise. A caller may still
+    inject a specific `answer_model` (tests, or to force a strategy). Imports are lazy so the subgraph module
+    stays import-light and hermetic (tests inject stubs)."""
+    from rag_wright.capabilities.answer_generator import agenerate_answer
+
+    if answer_model is None:
+        answer_model = _answer_model_for_impl(answer_model_id)
+    if reranker is None:
+        from rag_wright.capabilities.reranking import BGEReranker
+        reranker = BGEReranker()
+    from rag_wright.capabilities.contract_kg_serve import contract_clause_index
+    from rag_wright.capabilities.contract_kg_store import ContractKGStore
+
+    # EP-REF-1a-ii: the typed-KG edge reads moved to the domain store extension; the raw `store` still serves the
+    # generic retrieval (span search, rehydrate). The serving reads go through a ContractKGStore over it.
+    ckg = ContractKGStore(store)
+
+    def serve(contract_id: str, question: str) -> list[CitedClause]:
+        # ADR-0044: pull each cap clause's INFERRED carve-outs (IsExceptionTo) so "how is liability capped, and
+        # under what conditions?" sees "capped, except uncapped for ...".
+        # 0006-D: include_untyped so a clause the classifier left NONE is still a candidate (recall must not
+        # depend on classification -- else a classifier miss is a silent recall hole, engine issue 0006).
+        base = attach_exception_links(
+            contract_clause_index(ckg, contract_id, include_untyped=True), ckg.exceptions_of_clause,
+            contract_id=contract_id)
+        if len(base) <= top_k:
+            return base  # small contract -> no narrowing needed
+        # SEMANTIC top-K (ADR-0047): BGE-rerank the contract's clauses by relevance to the question.
+        texts = rehydrate_clause_texts(store, contract_id, base)
+        scores = reranker.score(question, [texts.get(c.clause_id, "") for c in base])
+        ranked = [c for c, _ in sorted(zip(base, scores), key=lambda cs: -cs[1])]
+        top = ranked[:top_k]
+        kept = {c.clause_id for c in top}
+        for c in base:  # ADR-0044: keep a kept cap clause's carve-outs even if they scored outside top-K
+            if c.exception_of and c.exception_of in kept and c.clause_id not in kept:
+                top.append(c)
+                kept.add(c.clause_id)
+        return top
+
+    def clause_text(contract_id: str, clauses: list[CitedClause]) -> dict[str, str]:
+        return rehydrate_clause_texts(store, contract_id, clauses)
+
+    async def generate(question: str, evidence: list[EvidenceItem]) -> GeneratedAnswer:
+        return await agenerate_answer(question, evidence, model=answer_model)
+
+    return build_intra_document_qa(serve, clause_text, generate)
+
+
+def register_intra_document_qa(registry) -> None:
+    """LG-3b: register `intra_document_qa` (composite subgraph; scoped KG query -> rehydrate -> generate)."""
+    registry.register(
+        "intra_document_qa",
+        contract=GeneratedAnswer,
+        kind="subgraph",
+        display_name="Intra-document QA (cited answer scoped to one contract)",
+    )
+
+
+async def ainvoke(resources, inputs: dict):
+    """EP-CORE-2 (ADR-0118): the capability invoke factory (impl_ref target)."""
+    from rag_wright.capabilities.answer_generator import answer_model_for
+    from rag_wright.models.profiles import ModelRole
+
+    graph = production_intra_document_qa(store=resources._store,
+                                         answer_model=answer_model_for(resources.model_id(ModelRole.GENERAL)),
+                                         top_k=inputs.get("top_k", 12))
+    return await graph.ainvoke({"contract_id": inputs["contract_id"], "question": inputs["question"]})

rag_wright/subgraphs/observability.py

@@ -0,0 +1,140 @@
+"""LG-0 observability: the vendor-neutral seam over the AMBIENT OpenTelemetry tracer.
+
+Per GraphWright's observability contract (`temp/observability-contract.md`): we DO NOT create a tracer
+provider, exporter, or Langfuse client, and we DO NOT initialize global tracing. GraphWright installs global
+OTel instrumentation and exports to Langfuse (or ANY OTLP backend -- Phoenix/Jaeger/collector; the backend is
+swappable with **zero change here**, which is the whole point). Our only jobs:
+
+  1. Build every model through the LangChain seam (`models/seam.py` -> `ChatOpenAI`), so token counts + latency
+     are captured automatically -- no code here for those.
+  2. Instrument the ONE gap: **raw-SDK** calls that bypass LangChain (docling-graph / LiteLLM, sandboxed or
+     out-of-band model calls) -- give them a span on the AMBIENT tracer with a model name + token usage.
+  3. Optionally add domain **business spans** (retrieval stats, a custom segment) on the ambient tracer.
+  4. Propagate the OTel context across any boundary WE introduce (separate process / worker / queue / custom
+     async loop). Std-lib threads are carried by GraphWright's threading instrumentation.
+
+This module is a safe NO-OP unless a REAL tracer provider is installed (GraphWright's runtime): standalone /
+hermetic tests, every helper no-ops; under GraphWright it attaches to the installed provider and nests
+correctly. Activation hinges on a real provider being set, NOT on `opentelemetry` merely being importable --
+the API can arrive as a transitive dependency (e.g. via FastMCP) with no SDK/provider configured, and that must
+NOT flip instrumentation on. Never import Langfuse; never construct a provider. Ground OTel via the framework
+index / docs when it is installed under GraphWright.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+try:  # the API may be importable standalone (transitive dep) -> gate ACTIVATION on a real provider, not this
+    from opentelemetry import context as _context
+    from opentelemetry import trace as _trace
+    from opentelemetry.propagate import extract as _extract
+    from opentelemetry.propagate import inject as _inject
+
+    _OTEL_IMPORTABLE = True
+except Exception:  # noqa: BLE001 - opentelemetry not installed -> graceful no-op seam
+    _OTEL_IMPORTABLE = False
+
+# The default (unconfigured) providers the OTel API returns before GraphWright sets a real SDK provider. When
+# the current provider is one of these, spans are non-recording, so every helper must no-op.
+_NOOP_PROVIDER_TYPES = frozenset({"ProxyTracerProvider", "NoOpTracerProvider", "DefaultTracerProvider"})
+
+
+def _provider_installed() -> bool:
+    """True only when a REAL tracer provider is installed (GraphWright's instrumented runtime), not the default
+    proxy/no-op the API ships with. This, not mere importability, is what activates the seam."""
+    if not _OTEL_IMPORTABLE:
+        return False
+    return type(_trace.get_tracer_provider()).__name__ not in _NOOP_PROVIDER_TYPES
+
+# OpenTelemetry GenAI semantic-convention attribute names (what OTLP backends read for token/cost views).
+_GENAI_MODEL = "gen_ai.request.model"
+_GENAI_SYSTEM = "gen_ai.system"
+_GENAI_IN = "gen_ai.usage.input_tokens"
+_GENAI_OUT = "gen_ai.usage.output_tokens"
+_GENAI_TOTAL = "gen_ai.usage.total_tokens"
+
+
+def otel_active() -> bool:
+    """True when a real tracer provider is installed (i.e. running under GraphWright's instrumented runtime)."""
+    return _provider_installed()
+
+
+def _tracer():
+    return _trace.get_tracer("rag_wright.subgraphs") if _provider_installed() else None
+
+
+@contextmanager
+def business_span(name: str, **attributes: Any) -> Iterator[Any]:
+    """A domain/business span on the AMBIENT tracer (never a new provider). No-op when OTel is absent.
+
+    For domain steps / retrieval stats -- NOT for standard LangChain LLM/tool calls (already captured; a manual
+    span would duplicate them).
+    """
+    tr = _tracer()
+    if tr is None:
+        yield None
+        return
+    with tr.start_as_current_span(name) as span:
+        for key, value in attributes.items():
+            span.set_attribute(key, value)
+        yield span
+
+
+@contextmanager
+def raw_llm_span(name: str, *, model: str, system: Optional[str] = None) -> Iterator[Any]:
+    """Instrument a RAW-SDK model call (the one gap: docling-graph/LiteLLM, sandboxed calls) on the ambient
+    tracer, so it shows up in traces with a model name. Call `record_tokens(span, ...)` after the call for
+    usage. Duration is the span's own. No-op when OTel is absent."""
+    tr = _tracer()
+    if tr is None:
+        yield None
+        return
+    with tr.start_as_current_span(name) as span:
+        span.set_attribute(_GENAI_MODEL, model)
+        if system:
+            span.set_attribute(_GENAI_SYSTEM, system)
+        yield span
+
+
+def record_tokens(
+    span: Any,
+    *,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+    total_tokens: Optional[int] = None,
+) -> None:
+    """Record token usage on a raw-SDK span (the only counting you own; LangChain calls set these themselves).
+    No-op on a None span."""
+    if span is None:
+        return
+    if input_tokens is not None:
+        span.set_attribute(_GENAI_IN, input_tokens)
+    if output_tokens is not None:
+        span.set_attribute(_GENAI_OUT, output_tokens)
+    if total_tokens is not None:
+        span.set_attribute(_GENAI_TOTAL, total_tokens)
+
+
+def inject_context(carrier: dict) -> dict:
+    """Producer side: serialize the current OTel context into `carrier` before crossing a boundary you
+    introduce (separate process / external worker / queue / custom async). Returns the carrier. No-op without
+    OTel. Std-lib threads do NOT need this (GraphWright instruments them)."""
+    if _provider_installed():
+        _inject(carrier)
+    return carrier
+
+
+@contextmanager
+def attach_context(carrier: dict) -> Iterator[None]:
+    """Consumer side: re-attach a context carried across a boundary so the work nests under the original run.
+    No-op without a real provider."""
+    if not _provider_installed():
+        yield
+        return
+    token = _context.attach(_extract(carrier))
+    try:
+        yield
+    finally:
+        _context.detach(token)

rag_wright/subgraphs/query_constraint_extraction.py

@@ -0,0 +1,73 @@
+"""LG-2: `query_constraint_extraction` as a hardened LangGraph subgraph.
+
+The query-side counterpart of `typed_clause_extraction` (LG-1): run the SAME granite + `clause_template`
+extractor on the QUERY, producing its typed (dimension, value) constraints (KG-5b). Two differences from the
+clause subgraph, both deliberate:
+
+  - **no reground / escalation** -- the query IS the source text, and KG-5d found reground-on-query FALSE-FLAGS
+    real constraints (e.g. "control the defense" != the clause cue "control of the defense"), so we do not
+    ground query constraints; a single extract call is the pattern (KG-5e, granite json_schema);
+  - **no dead-letter-drops-the-item** -- a query that yields nothing degrades to an EMPTY constraint set
+    (the retrieval falls back to embedding-only ranking), never a dropped item.
+
+Hardening applied JUDICIOUSLY (not every subgraph needs every primitive): a single extract with **graceful
+degradation** -- a transient OR genuine failure yields an EMPTY constraint set (the query survives), so there
+is no RetryPolicy or dead-letter here. The observability wrap on the raw-SDK (docling-graph/LiteLLM) call is
+kept. `record_fn` is injected for hermetic testing.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+from rag_wright.contracts.property import ClausePropertyRecord
+from rag_wright.subgraphs.scaffold import raw_llm_span
+from rag_wright.subgraphs.typed_clause_extraction import TransientExtraction  # shared retryable-blip signal
+
+RecordFn = Callable[[str, str], Optional[ClausePropertyRecord]]
+
+
+class QueryConstraintState(TypedDict, total=False):
+    query_text: str
+    model_id: str
+    record: Optional[ClausePropertyRecord]
+    constraints: list  # [(dimension, value), ...] -- empty when extraction yields nothing
+
+
+def _constraints_of(record: Optional[ClausePropertyRecord]) -> list:
+    if record is None:
+        return []
+    return [(a.dimension.value, a.value) for a in record.assertions]
+
+
+def build_query_constraint_extraction(record_fn: RecordFn, *, model_id: str):
+    """Compile the `query_constraint_extraction` subgraph. `record_fn` is injected for hermetic testing.
+    A genuine extraction failure (record_fn -> None) or a transient failure that exhausts retries degrades to
+    an empty constraint set -- the query is never dropped."""
+
+    def extract(state: QueryConstraintState) -> QueryConstraintState:
+        model = state.get("model_id", model_id)
+        try:
+            with raw_llm_span("query_constraint_extraction.extract", model=model):
+                record = record_fn(state["query_text"], model)
+        except TransientExtraction:
+            record = None  # any failure -> empty constraints; the query survives (embedding-only fallback)
+        return {"record": record, "constraints": _constraints_of(record)}
+
+    g = StateGraph(QueryConstraintState)
+    g.add_node("extract", extract)
+    g.add_edge(START, "extract")
+    g.add_edge("extract", END)
+    return g.compile()
+
+
+def register_query_constraint_extraction(registry) -> None:
+    """LG-2: register `query_constraint_extraction` (subgraph; query-side typed constraint extraction)."""
+    registry.register(
+        "query_constraint_extraction",
+        contract=ClausePropertyRecord,
+        kind="subgraph",
+        display_name="Query constraint extraction",
+    )