rag-wright 0.1.0__py3-none-any.whl

rag_wright/skills/rlm/agent.py

@@ -0,0 +1,292 @@
+"""RLM machinery (FR-C.10, `rlm_method`): the Deep Agents assembly the RLM method runs on.
+
+This is the reusable RLM runtime the RLM chunking (T17) and RLM synthesis (T28) capabilities apply.
+It is authored software, not a build-tool feature: the RLM node is a Deep Agent whose interpreter
+(`CodeInterpreterMiddleware`) holds the working set and runs a recursive `decompose()` *workflow* that
+dispatches sub-agents with `task()` — a **fresh `rlm_decomposer`** at each over-budget internal level
+(per-level fresh context) and an `rlm_slice_worker` at each leaf. Arbitrary depth comes from the
+interpreter re-entering `decompose()`; the interpreter holds the recursion stack.
+
+Two named sub-agents, dispatched by name (ADR-0015):
+  - `rlm_decomposer`  — decides one level's split for the slice it is handed; a fresh agent per dispatch.
+  - `rlm_slice_worker` — handles one leaf slice; per-slice tool use and per-slice skills live here.
+
+The recursion is driven by the interpreter, **not** by an agent dispatching itself: a self-referential
+sub-agent is not constructible on the pinned `deepagents==0.6.12` (its `SubAgentMiddleware.__init__`
+compiles its roster eagerly, so a config whose roster contains itself recurses at construction). See
+ADR-0015 (Q2, corrected — design B') for the grounded reason and why interpreter-driven recursion is the
+faithful realization, not a workaround.
+
+Models resolve through the model-profile seam (T11): the RLM reasoning role (orchestrator + decomposer)
+is a Gemma 4 class model (`ModelRole.GENERAL`); the leaf worker's model is chosen by the applying
+capability (a smaller model for chunking summaries, the structured-reasoning model for synthesis). No
+provider or model flag lives here.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.tools import BaseTool
+from langchain_quickjs import CodeInterpreterMiddleware
+from langgraph.graph.state import CompiledStateGraph
+
+from deepagents import create_deep_agent
+from deepagents.middleware.subagents import SubAgent
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.seam import build_model
+
+# The two named sub-agents (ADR-0015 Q1). Also the exact `grantedSubagents` the manifests declare.
+RLM_DECOMPOSER = "rlm_decomposer"
+RLM_SLICE_WORKER = "rlm_slice_worker"
+GRANTED_SUBAGENTS: tuple[str, str] = (RLM_DECOMPOSER, RLM_SLICE_WORKER)
+
+# LOAD-BEARING, do NOT remove as an "uncontended lock in a serial path" (KI-1, ADR-0020). Two QuickJS
+# interpreter runtimes coexisting in one process race on shared Rust state and silently complete without
+# dispatching ~half the time, with zero exceptions. This process-wide semaphore serializes the FULL
+# interpreter-session lifetime (build -> run -> teardown) so no two RLM runtimes are ever alive at once.
+# It is uncontended (zero cost) while ingestion is serial; it makes the safe behaviour the DEFAULT so that
+# adding concurrency later turns a silent-correctness failure into a visible-performance one (slower, not
+# wrong). It lifts only when the upstream coexistence bug is fixed (ADR-0020 exit path). Task T35 designs
+# the real concurrent batch; this is the always-on correctness floor beneath it, not throughput tuning.
+_INTERPRETER_SEMAPHORE = threading.BoundedSemaphore(1)
+
+
+@contextmanager
+def rlm_interpreter_session(
+    *, ptc: Sequence[BaseTool] = (), max_result_chars: Optional[int] = None
+) -> Iterator[CodeInterpreterMiddleware]:
+    """Own the process for exactly one RLM interpreter session (KI-1, ADR-0020).
+
+    Holds `_INTERPRETER_SEMAPHORE` from before the interpreter runtime is built (the middleware is created
+    here; its QuickJS runtime is built lazily on first `eval`, inside the lock) until after it is torn down
+    (the registry is closed here, deterministically, not on GC timing) — the whole coexistence window, not
+    just the dispatch call. Build the RLM agent with the yielded middleware and run it inside the `with`;
+    do parsing/String work outside it. Reentrant call from within one session would deadlock — one session
+    per call stack, which the discoverer/extractor honour (they invoke once, then parse outside).
+
+    `ptc` are Programmatic-Tool-Calling tools exposed **inside** the interpreter as `tools.<camelCase>()`
+    and never as top-level tools — this is how the working set is delivered as a JS value that stays out of
+    the model's context (`working_set` → `tools.workingSet()`, T36 / GraphWright working-set contract).
+    """
+    # `max_result_chars` overrides the interpreter's 4,000-char eval-result cap (which truncates a large
+    # JSON return mid-string). A capability whose workflow returns a big result (e.g. okf_navigate's shortlist
+    # + decision log at a high frontier budget) raises it; RLM leaves it at the default.
+    _INTERPRETER_SEMAPHORE.acquire()
+    kwargs: dict = {"subagents": True, "ptc": list(ptc) or None}
+    if max_result_chars is not None:
+        kwargs["max_result_chars"] = max_result_chars
+    interpreter = CodeInterpreterMiddleware(**kwargs)
+    try:
+        yield interpreter
+    finally:
+        try:
+            interpreter._registry.close()  # tear the QuickJS runtime down inside the lock (no coexistence)
+        finally:
+            _INTERPRETER_SEMAPHORE.release()
+
+_DECOMPOSER_PROMPT = (
+    "You decide how to split ONE working-set slice (a list of items) for a recursive divide-and-conquer. "
+    "If the slice is small and focused enough to handle directly, mark it a leaf; otherwise return the "
+    "split offsets that partition it into coherent contiguous groups. Reply as JSON: {\"leaf\": true} for "
+    "a leaf, or {\"leaf\": false, \"cuts\": [i, j, ...]} where each cut is an ascending index into the "
+    "slice at which a new group begins. The cuts partition the slice, so no item is lost. Decide only THIS "
+    "level; the interpreter re-dispatches you on each group."
+)
+_SLICE_WORKER_PROMPT = (
+    "You handle ONE focused working-set slice end to end. Use the tools and skills you are given as "
+    "needed, then return the result for this slice only. You never see the whole working set."
+)
+
+# The canonical interpreter-driven recursive workflow (ADR-0015 Q2 corrected, design B'). Reads the
+# working set from the runtime PTC tool `tools.workingSet()` (T36) — a JS value that never enters context —
+# and dispatches sub-agents by name via `task()`. Recursion lives HERE, in the interpreter: a fresh
+# `rlm_decomposer` decides each level's split, `decompose()` re-enters itself on the returned parts
+# (depth capped at _MAX_DEPTH = 3, the interpreter holds the stack), and `rlm_slice_worker` handles each leaf. The RLM
+# skill (SKILL.md) teaches this workflow; the node writes it into the `eval` tool when its request asks
+# for a "workflow" (the trigger GraphWright's applier guarantees, requiresDynamicDispatch). It returns
+# the per-leaf results plus the depths at which splitting occurred, so the descent is inspectable.
+RLM_WORKFLOW_JS = r"""
+// Recursive divide-and-conquer over a working set of items. Read it from the runtime tool (a JS value
+// that stays in the interpreter and never enters the model's context), then fan the work out to
+// sub-agents in code (a "workflow"), never one grinding tool call at a time. The interpreter holds the
+// working set and the recursion stack; the model is only ever called on a focused slice.
+const workingSet = await tools.workingSet();  // [{id, ...}, ...] delivered by the runtime, never in context
+// LOAD-COMPLETENESS ASSERTION (T37): verify you loaded the WHOLE delivered set before anything else. The
+// size comes from the runtime (a scalar it cannot under-read); if the load is short, fail loud rather than
+// silently working over a truncated set — the coverage tail below only guarantees coverage over what you
+// loaded, so an under-read here is a silent evidence drop nothing downstream catches.
+const _delivered = await tools.workingSetSize();
+if (workingSet.length !== _delivered) {
+  throw new Error("LOAD UNDER-READ: loaded " + workingSet.length + " of " + _delivered + " delivered items");
+}
+const _MAX_DEPTH = 3;                // hard cap on recursion — beyond this, force leaf (no runaway splits)
+const _splitDepths = [];             // the depths at which decompose() re-entered itself (proof of descent)
+const _handled = new Set();          // ids of working-set items a leaf worker covered
+async function decompose(items, depth) {
+  if (items.length === 0) return [];    // empty slice — nothing to dispatch (no-op leaf)
+  if (depth >= _MAX_DEPTH) {
+    for (const it of items) _handled.add(it.id);
+    return [await task({ description: "handle leaf depth " + depth + " over " + items.length + " items: " + JSON.stringify(items), subagentType: "rlm_slice_worker" })];
+  }
+  const decision = JSON.parse(await task({
+    description: "decompose depth " + depth + " over " + items.length + " items",
+    subagentType: "rlm_decomposer",
+  }));
+  if (decision.leaf) {
+    for (const it of items) _handled.add(it.id);
+    return [await task({ description: "handle leaf depth " + depth + " over " + items.length + " items: " + JSON.stringify(items), subagentType: "rlm_slice_worker" })];
+  }
+  _splitDepths.push(depth);
+  // decision.cuts partition `items` into contiguous groups (no item lost); recurse on every group.
+  const bounds = [0, ...decision.cuts, items.length];
+  const groups = [];
+  for (let i = 0; i < bounds.length - 1; i++) groups.push(items.slice(bounds[i], bounds[i + 1]));
+  const handled = await Promise.all(groups.map((g) => decompose(g, depth + 1)));
+  return handled.flat();
+}
+const _leaves = await decompose(workingSet, 0);
+// COVERAGE TAIL (structural, in-interpreter): the code holds EVERY item, so it guarantees coverage even
+// if the recursion missed a deep leaf out of context — a silent drop otherwise (T37). Any uncovered item
+// is dispatched now, not dropped. This is code checking coverage, not the model asked to be thorough.
+const _missed = workingSet.filter((it) => !_handled.has(it.id));
+if (_missed.length) {
+  for (const it of _missed) _handled.add(it.id);
+  _leaves.push(await task({ description: "cover " + _missed.length + " missed items: " + JSON.stringify(_missed), subagentType: "rlm_slice_worker" }));
+}
+JSON.stringify({
+  leaves: _leaves,
+  leafCount: _leaves.length,
+  covered: _handled.size,
+  total: workingSet.length,
+  missed: _missed.length,
+  maxSplitDepth: _splitDepths.length ? Math.max(..._splitDepths) : -1,
+});
+""".strip()
+
+
+_SKILL_PATH = Path(__file__).parent / "SKILL.md"
+
+
+def method_prompt() -> str:
+    """The RLM method (SKILL.md body, YAML frontmatter stripped) as the orchestrator's instructions.
+
+    The method is loaded into the orchestrator's **system prompt**, not wired as a lazy `skills=` source:
+    grounded on the pinned stack (2026-07-15), a real model does NOT proactively open a lazy skill source
+    before writing its `eval` workflow, so a lazy method never reaches it and it improvises a flat split.
+    The RLM method IS this node's defining job, so it belongs in the system prompt, always in front of the
+    model. (`skills=`/`worker_skills=` remain for auxiliary per-slice worker skills, which the worker may
+    open on demand.) See ADR-0018.
+    """
+    text = _SKILL_PATH.read_text(encoding="utf-8")
+    if text.startswith("---"):  # strip YAML frontmatter
+        end = text.find("\n---", 3)
+        if end != -1:
+            text = text[end + 4 :]
+    return text.strip()
+
+
+_ModelArg = Union[BaseChatModel, str, None]
+
+
+def _resolve_model(model: _ModelArg, default_role: ModelRole) -> BaseChatModel:
+    """Resolve a model argument to a concrete `BaseChatModel` instance.
+
+    An instance passes through (tests inject fakes here); a string is a model id built through the seam;
+    `None` falls back to the profile for `default_role`. Always an instance — `create_deep_agent` would
+    otherwise resolve a bare id through its own provider path, which our OpenRouter-via-`langchain_openai`
+    seam does not use.
+    """
+    if isinstance(model, BaseChatModel):
+        return model
+    return build_model(model or model_for(default_role))
+
+
+def decomposer_config(*, model: _ModelArg = None) -> SubAgent:
+    """The `rlm_decomposer` sub-agent: decides one level's split; a fresh agent per dispatch.
+
+    Reasoning work, so it defaults to the Gemma 4 class RLM role (`ModelRole.GENERAL`). It carries no
+    roster of its own — the interpreter, not the decomposer, drives the recursion (ADR-0015 Q2).
+    """
+    return {
+        "name": RLM_DECOMPOSER,
+        "description": "Decides how to split one working-set slice for recursive RLM decomposition.",
+        "system_prompt": _DECOMPOSER_PROMPT,
+        "model": _resolve_model(model, ModelRole.GENERAL),
+    }
+
+
+def slice_worker_config(
+    *,
+    model: _ModelArg = None,
+    system_prompt: str = _SLICE_WORKER_PROMPT,
+    tools: Sequence[Union[BaseTool, Callable[..., Any], dict[str, Any]]] = (),
+    skills: Sequence[str] = (),
+) -> SubAgent:
+    """The `rlm_slice_worker` sub-agent: handles one leaf slice, with per-slice tools and skills.
+
+    The applying capability supplies `tools`, `skills`, and (via the `task()` description) the per-call
+    specialization (summarize for chunking, extract-and-synthesize for synthesis), so one config serves
+    both. The worker model is the applying capability's choice; it defaults to the RLM role.
+    """
+    config: SubAgent = {
+        "name": RLM_SLICE_WORKER,
+        "description": "Handles one focused leaf slice end to end, using per-slice tools and skills.",
+        "system_prompt": system_prompt,
+        "model": _resolve_model(model, ModelRole.GENERAL),
+        "tools": list(tools),
+    }
+    if skills:
+        config["skills"] = list(skills)
+    return config
+
+
+def build_rlm_agent(
+    *,
+    reasoning_model: _ModelArg = None,
+    decomposer_model: _ModelArg = None,
+    worker_model: _ModelArg = None,
+    worker_system_prompt: str = _SLICE_WORKER_PROMPT,
+    worker_tools: Sequence[Union[BaseTool, Callable[..., Any], dict[str, Any]]] = (),
+    worker_skills: Sequence[str] = (),
+    tools: Sequence[Union[BaseTool, Callable[..., Any], dict[str, Any]]] = (),
+    system_prompt: Optional[str] = None,
+    skills: Optional[Sequence[str]] = None,
+    interpreter: Optional[CodeInterpreterMiddleware] = None,
+) -> CompiledStateGraph:
+    """Assemble the RLM Deep Agent: an interpreter orchestrator over the two named sub-agents.
+
+    The orchestrator holds the working set in the interpreter and runs the recursive `decompose()`
+    workflow (`RLM_WORKFLOW_JS`) via the `eval` tool, dispatching `rlm_decomposer` per level and
+    `rlm_slice_worker` per leaf. `reasoning_model` is the orchestrator; `decomposer_model`/`worker_model`
+    default to it / the profile. `system_prompt` defaults to the RLM method (`method_prompt()`), always in
+    front of the orchestrator; `skills`/`worker_skills`/`worker_tools` are auxiliary (the leaf worker's).
+    Tests inject fake models per role.
+
+    Returns the compiled agent. This is the reference assembly RAG_Wright's own tests and evals run and
+    the applying capabilities (T17, T28) build on; the graph half (GraphWright) assembles the production
+    node equivalently from the same skill and `grantedSubagents`.
+    """
+    orchestrator = _resolve_model(reasoning_model, ModelRole.GENERAL)
+    subagents: list[SubAgent] = [
+        decomposer_config(model=decomposer_model if decomposer_model is not None else reasoning_model),
+        slice_worker_config(
+            model=worker_model,
+            system_prompt=worker_system_prompt,
+            tools=worker_tools,
+            skills=worker_skills,
+        ),
+    ]
+    return create_deep_agent(
+        model=orchestrator,
+        tools=list(tools),
+        system_prompt=system_prompt if system_prompt is not None else method_prompt(),
+        subagents=subagents,
+        middleware=[interpreter or CodeInterpreterMiddleware(subagents=True)],
+        skills=list(skills) if skills else None,
+    )

rag_wright/skills/span_relevance_judgment/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: span_relevance_judgment
+description: >
+  The corpus-retrieval RELEVANCE method: given ONE retrieved span (a contract clause's operative text) and ONE
+  structured condition being searched for (a clause type, optionally a specific value condition, with the user's
+  question as context), decide whether the span ACTUALLY ADDRESSES that condition -- relevant, not_relevant, or
+  uncertain from the text. This is the retrieval analog of the compliance judge (does this text satisfy this
+  thing?) and of answer abstention (does the evidence support an answer?): it returns a VERDICT, not a score, so
+  no caller has to choose a similarity threshold. The applying capability owns the deterministic guarantees
+  (verdict vocab, conservative default) -- this skill teaches only the reading.
+---
+
+# Span relevance: does this retrieved span address this condition?
+
+`typed_property_retrieval` always returns the top-k nearest spans, so a nonsense query still comes back with a
+full page of clauses. Retrieval ranks by similarity; it never asks whether a span is *about* the thing searched
+for. This skill supplies that missing judgement, so a sweep can honestly say "nothing in this corpus addresses
+this condition" instead of surfacing eight near-misses.
+
+## The one hard constraint: you see only the span text
+
+You are given the condition and ONE span's text. You judge whether **that span text** addresses the condition.
+You cannot see the rest of the contract or the corpus. Judge only what the span itself shows.
+
+## What the condition is (and how to weigh its parts)
+
+- **clause type** (primary) — the kind of clause being searched for, e.g. "Cap On Liability", "Renewal Term",
+  "Source Code Escrow". This is the main test: is the span a clause of, or squarely about, this type?
+- **specific condition** (when present) — a narrower test within the type, e.g. "capped at a multiple of fees",
+  "auto-renews unless notice is given". When given, the span must address THIS, not just the general type.
+- **the user's question** — CONTEXT ONLY. In a multi-condition sweep one question is shared across several
+  conditions, so it may be broader than, or only loosely tied to, this particular condition. Never treat a span
+  as relevant just because it echoes a word from the question; anchor on the clause type and the specific
+  condition.
+
+## Typed properties are evidence, not proof
+
+The span may arrive with typed properties already detected on it (e.g. `cap_basis = multiple_of_fees`). These
+were extracted from the question ONCE and reused across every condition in the sweep, so a property being
+present does **not** prove the span is about *this* condition. A Source Code Escrow clause can carry
+`cap_basis = multiple_of_fees` and still have nothing to do with a Cap On Liability search. Read the properties
+as a hint, then decide from the span text itself.
+
+## The three verdicts
+
+- **relevant** — the span is clearly a clause of the condition's type, or squarely addresses the specific
+  condition. A lawyer scanning results would say "yes, this is the clause you were looking for."
+
+- **not_relevant** — the span is about something else. It was returned because it was among the nearest by
+  similarity (or shares an incidental property), but it does not address this clause type / condition. This is
+  the verdict that makes an honest "not found" reachable: when every returned span is not_relevant, the corpus
+  does not contain the condition.
+
+- **uncertain** — the span text is too ambiguous, partial, or truncated to tell whether it addresses the
+  condition. Reserve this for genuine ambiguity, not for "probably not" (that is not_relevant) and not for
+  "probably yes" (that is relevant). Do not use uncertain to avoid a decision the text supports.
+
+## Output
+
+Return the verdict (relevant / not_relevant / uncertain), a one- or two-sentence rationale grounded in the span
+text, and a confidence in [0, 1].
+
+## What this skill does NOT own
+
+The vocabulary mapping, the conservative default when you cannot be read, and how the verdicts roll up into a
+product's matched / possible / not-found grouping are the APPLYING capability's and the caller's concern, not
+this method's. This skill decides one span against one condition and explains why.

rag_wright/skills/vision_to_text/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: vision_to_text
+description: >
+  The scanned-image transcription method: given a single page image from an image-only filing, transcribe all
+  visible text exactly, preserving reading order, and output only the transcribed text. A single grounded
+  vision-language act on the GENERAL model (Gemma 4 class) through the model seam; the ingestion-side twin of
+  answer generation (both are the FR-C.9 generation capability, ADR-0014). Applied by the vision_to_text skill
+  runtime at ingestion for the image-only PDF subset.
+---
+
+# Vision-to-text: transcribe the text visible in this image
+
+This skill teaches a **method** for turning a page image into its text, so an image-only filing can be chunked,
+embedded, and reasoned over like any parsed document. It is a single vision-language reading, not a workflow.
+
+## The method
+
+- **Transcribe all text visible in the image exactly.** Reproduce the characters as written -- do not
+  paraphrase, summarize, correct, translate, or complete anything.
+- **Preserve reading order.** Follow the page's natural top-to-bottom, left-to-right flow (and column order
+  where the page is multi-column), so the transcription reads as the document reads.
+- **Output only the transcribed text.** No commentary, no description of the layout, no headings you invent,
+  no "here is the text" preamble -- just the text itself.
+
+## Boundaries
+
+- If a region is unreadable, transcribe what is legible and do not fabricate the rest.
+- The transcription is downstream evidence: it must be faithful to the page, because everything built on top
+  of it (chunks, embeddings, extracted facts, citations) inherits its errors.
+
+## What this skill does NOT own (the applying capability's job)
+
+- the **model choice and the seam** (the GENERAL role via the model-profile seam -- product = self-hosted
+  Gemma-class, ADR-0039) and the **multimodal message assembly** (base64 data URI) are the capability runtime's
+  plumbing, not the method;
+- the **output contract** (`VisionTranscription`) is attached by the capability.

rag_wright/skills/vision_to_text/__init__.py

@@ -0,0 +1 @@
+"""vision_to_text agent-skill folder: SKILL.md (the scanned-image transcription method)."""

rag_wright/spans/__init__.py

@@ -0,0 +1 @@
+"""Operative-span segmentation (FR-R, ADR-0025)."""

rag_wright/spans/boundary.py

@@ -0,0 +1,78 @@
+"""Provision-boundary decision: deterministic-first, with a decision-model (Jev) fallback for the UNCERTAIN residue.
+
+`provision_boundary_verdict` (``spans.segment``) classifies each span deterministically into ``start`` / ``continue``
+/ ``uncertain``. The ``uncertain`` residue -- short, plausibly-heading lines in styles the deterministic rules do not
+confidently classify (a new document convention, a colon/odd heading) -- is adjudicated by a pluggable async decider,
+the ``jev_decision`` capability by default (invoked THROUGH the engine invoker, one batched call for the whole
+residue). The decider is OPTIONAL: with no decision model configured, or on any error, an uncertain span GRACEFULLY
+DEGRADES to "not a new provision" (the prior deterministic behavior) -- so ingestion never requires a decision model
+and the hermetic tests stay offline. This is the neuro-symbolic shape (ADR-0040): a cheap, exact symbolic layer for
+the clear majority + a model only for the ambiguous part -- flexible where regex is rigid, bounded in cost.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Awaitable, Callable, Optional
+
+from rag_wright.spans.segment import provision_boundary_verdict
+
+# A residue decider: candidate texts (the UNCERTAIN spans) -> a start flag each (True = begins a new provision).
+BoundaryDecider = Callable[[list[str]], Awaitable[list[bool]]]
+
+_THRESHOLD = 0.5
+
+
+async def adecide_provision_starts(
+    texts: list[str], *, decider: Optional[BoundaryDecider] = None
+) -> list[bool]:
+    """Per-span "starts a new provision?" flags, aligned to ``texts``. Deterministic ``start``/``continue`` are
+    decided for free; only the ``uncertain`` residue is passed to ``decider`` (one batched call). No decider, or a
+    decider error, degrades the residue to False (fold in) -- never an exception, never a lost span."""
+    verdicts = [provision_boundary_verdict(t) for t in texts]
+    starts = [v == "start" for v in verdicts]
+    residue = [i for i, v in enumerate(verdicts) if v == "uncertain"]
+    if residue and decider is not None:
+        try:
+            decided = await decider([texts[i] for i in residue])
+        except Exception:  # noqa: BLE001 - a decision-model blip must not fail ingestion; degrade to deterministic
+            decided = [False] * len(residue)
+        for i, flag in zip(residue, decided):
+            starts[i] = bool(flag)
+    return starts
+
+
+def jev_boundary_decider(resources: Any = None) -> Optional[BoundaryDecider]:
+    """Build the Jev-backed residue decider, or ``None`` when no decision model is configured/registered (then the
+    boundary stays purely deterministic). It invokes the ``jev_decision`` capability THROUGH the engine invoker --
+    one batched call with all candidate lines in the ``state`` and one ``noul`` question per line."""
+    from rag_wright.api import ainvoke_model, capability_index
+    from rag_wright.models.profiles import decision_profile
+
+    model = os.environ.get("RAG_DECISION_MODEL")
+    prof = decision_profile(model)
+    if not os.environ.get(prof.api_key_env) or "jev_decision" not in capability_index():
+        return None  # no decision model available -> deterministic-only
+
+    async def _decide(texts: list[str]) -> list[bool]:
+        state = "\n".join(f"[{i}] {t.strip()}" for i, t in enumerate(texts))
+        questions = {
+            f"c{i}": {
+                "type": "noul",
+                "instructions": (
+                    f"In the numbered lines above, does line [{i}] BEGIN a new numbered section or provision of a "
+                    "contract (a section heading / start), rather than continue the previous provision's text?"
+                ),
+                "criteria": {
+                    "true": f"line [{i}] begins a new section or provision",
+                    "false": f"line [{i}] continues the current provision",
+                },
+            }
+            for i in range(len(texts))
+        }
+        out = await ainvoke_model(
+            "jev_decision", {"state": state, "questions": questions, "model": model}, resources=resources
+        )
+        answers = out.get("answers", {}) if isinstance(out, dict) else {}
+        return [float((answers.get(f"c{i}") or {}).get("noul", 0.0)) >= _THRESHOLD for i in range(len(texts))]
+
+    return _decide