rag-wright 0.1.0__py3-none-any.whl

rag_wright/mcp/intra_document_qa_server.py

@@ -0,0 +1,170 @@
+"""MCP-PROTO Phase B (B1): the `intra_document_qa` MCP-tool server (FastMCP).
+
+Wraps the `intra_document_qa` SUBGRAPH (A1, Leg A) as a single MCP tool
+`answer_contract_question(contract_id, question)` -> a cited `GeneratedAnswer` (as JSON). The store (the contract
+clause KG) + the models (function classifier + Gemma generation via the seam) bind SERVER-SIDE from env, so the
+tool call is just `{contract_id, question}` -- the token/coordination win. An external agent discovers this via
+ARD search and calls it. Second Tier-1 leg wrapped after `compliance_check` (`compliance_server.py`, the
+reference pattern this mirrors).
+
+Grounded (library rule): FastMCP `server.py:L278` (`FastMCP(name, instructions, version=...)`), `@mcp.tool`,
+`run(transport=...)` -- confirmed against the cloned-repo AST graph (`graphify-out/framework/graph.json`) + the
+installed 3.4.6 signatures, same surface the reference server uses.
+
+`build_intra_document_qa_mcp(qa_fn)` injects the answerer so the server is hermetically testable (a stub
+`qa_fn`, no ArcadeDB/LLM). `main()` picks the production answerer (real subgraph, env-wired) or a deterministic
+demo answerer (`RAG_MCP_DEMO=1`, no infra) and serves over stdio (so a Deep Agent can spawn it).
+
+  # real (needs the contract KG + a model backend via env, like scripts/phase_a_leg_validate.py):
+  uv run --no-sync python -m rag_wright.mcp.intra_document_qa_server
+  # demo (no infra -- deterministic answer; for the Deep-Agent prototype):
+  RAG_MCP_DEMO=1 uv run --no-sync python -m rag_wright.mcp.intra_document_qa_server
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Awaitable, Callable, Optional
+
+from fastmcp import FastMCP
+
+from rag_wright.capabilities.answer_generator import GeneratedAnswer
+
+# qa_fn: (contract_id, question) -> GeneratedAnswer. Injected so the server is testable without infra.
+# ASYNC-C1 (ADR-0057): async -- the tool handler awaits it, and it awaits the async intra_document_qa subgraph.
+from rag_wright.mcp.session_store import StoreResolver, resolve_request_store
+from rag_wright.store.seam import Store
+
+# issue 0035: store-PARAMETRIC -- the runner takes the per-request store (resolved out-of-band), never a
+# model-supplied one. The demo/stub runner ignores it.
+QAFn = Callable[[Optional[Store], str, str], Awaitable[GeneratedAnswer]]
+
+_TOOL_DESCRIPTION = (
+    "Answer a natural-language question about ONE known contract from its clause knowledge graph, returning a "
+    "grounded, cited answer. Classifies the question to its clause function(s), serves those clauses (with any "
+    "cap carve-outs), and generates the answer from that evidence ALONE: every claim cites the chunk_id(s) it "
+    "rests on, and a question the contract does not support yields an abstention (abstained=true), never a "
+    "fabrication. Use when the contract is already identified and the user asks about its terms."
+)
+
+
+def _answer_to_dict(answer: GeneratedAnswer) -> dict[str, Any]:
+    """The tool's JSON payload: the cited answer. This is the structured content the calling agent receives."""
+    return answer.model_dump(mode="json")
+
+
+def build_intra_document_qa_mcp(
+    qa_fn: QAFn, *, store_resolver: Optional[StoreResolver] = None, env_store: Any = None,
+    name: str = "rag-wright-intra-document-qa"
+) -> FastMCP:
+    """Build the FastMCP server exposing `intra_document_qa` as one tool. `qa_fn` is injected (real subgraph in
+    production; a stub in tests) so the MCP surface is testable with no ArcadeDB / LLM.
+
+    issue 0035: the tool takes NO tenant/database/scope argument (`contract_id` is a document key WITHIN the
+    resolved store, not a tenant selector). `store_resolver` (caller-supplied) binds the store PER SESSION from
+    the out-of-band MCP request context; `env_store` is the single-tenant fallback. The resolved store is passed
+    to `qa_fn` -- never a model-supplied value."""
+    mcp: FastMCP = FastMCP(
+        name=name,
+        instructions=(
+            "Contract question-answering over a per-contract clause knowledge graph. Use "
+            "answer_contract_question to answer a question about a known contract with cited evidence."
+        ),
+    )
+
+    @mcp.tool(name="answer_contract_question", description=_TOOL_DESCRIPTION)
+    async def answer_contract_question(contract_id: str, question: str) -> dict[str, Any]:
+        """Answer one question about a known contract from its clause KG.
+
+        Args:
+            contract_id: The identifier of the contract to query (its clauses must be in the KG).
+            question: The natural-language question about that contract's terms.
+
+        Returns:
+            A cited answer: {answer, citations[], abstained}. `citations` are chunk_ids present in the evidence;
+            `abstained` is true when the contract does not support an answer.
+        """
+        store = await resolve_request_store(store_resolver, env_store)  # per-request, out-of-band (issue 0035)
+        return _answer_to_dict(await qa_fn(store, contract_id, question))
+
+    return mcp
+
+
+# --- production answerer: the real intra_document_qa subgraph, env-wired (like scripts/phase_a_leg_validate.py) -
+
+
+def production_qa_fn(*, function_model_id: str | None = None, answer_model_id: str | None = None) -> QAFn:
+    """Wire the real `intra_document_qa` over the env-selected store + models: ArcadeDB contract KG (`ARCADEDB_*`,
+    `QA_DB`), the GENERAL model for generation (via the seam; `RAG_SERVING`). ADR-0047: there is no function
+    classifier anymore -- the leg serves the whole contract; `function_model_id` is kept as a back-compat alias
+    for the generation-model default. Heavy imports are lazy so `RAG_MCP_DEMO` never pays for them."""
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    from rag_wright.models.profiles import ModelRole, model_for
+    from rag_wright.subgraphs.intra_document_qa import production_intra_document_qa
+
+    default_model = answer_model_id or function_model_id or model_for(ModelRole.GENERAL)  # tenant-independent
+
+    async def _qa(store: Optional[Store], contract_id: str, question: str) -> GeneratedAnswer:
+        leg = production_intra_document_qa(store=store, answer_model_id=default_model)  # per-request store (0035)
+        out = await leg.ainvoke({"contract_id": contract_id, "question": question})
+        ans = out.get("answer")
+        if ans is None:  # a pipeline dead-letter (e.g. orphan span) -> an honest abstention, never a fabrication
+            return GeneratedAnswer(
+                answer="The contract knowledge graph could not be queried for this question.",
+                citations=[], abstained=True)
+        return ans
+
+    return _qa
+
+
+def production_env_store() -> Store:
+    """The single-tenant fallback store from `QA_DB` (demo / eval / single-tenant). Built lazily so `RAG_MCP_DEMO`
+    never touches ArcadeDB; a multi-tenant caller passes a `store_resolver` instead (issue 0035)."""
+    from rag_wright.store.arcadedb import ArcadeDBStore
+
+    return ArcadeDBStore.from_env(database=os.environ.get("QA_DB", "ragwright_cuad_full"))
+
+
+# --- demo answerer: a deterministic, real-shaped cited answer (no ArcadeDB / LLM) for the Deep-Agent prototype -
+
+
+def demo_qa_fn() -> QAFn:
+    """A deterministic stub with the REAL contract shape -- a cited, grounded cap answer. Lets the Deep-Agent
+    prototype (and the hermetic test) exercise the full MCP path with no ArcadeDB / LLM."""
+    _cid = "AcmeMSA:12:deadbeef01"
+
+    async def _qa(store: Optional[Store], contract_id: str, question: str) -> GeneratedAnswer:  # store ignored
+        return GeneratedAnswer(
+            answer=f"Seller's aggregate liability is capped at two times (2x) the fees paid in the "
+                   f"preceding 12 months [{_cid}].",
+            citations=[_cid], abstained=False)
+
+    return _qa
+
+
+def register_intra_document_qa_mcp(registry) -> None:
+    """Register `intra_document_qa_mcp` (MCP-PROTO Phase B): the ARD `mcp_tool` surface of the
+    `intra_document_qa` subgraph -- the same capability exposed as a discoverable, cross-agent MCP tool
+    (`answer_contract_question`, served by `rag_wright.mcp.intra_document_qa_server`) so an agent can call it as
+    ONE tool via ARD search instead of embedding the subgraph. Distinct ARD identity from the in-process
+    `intra_document_qa` subgraph; same output contract `GeneratedAnswer`."""
+    registry.register(
+        "intra_document_qa_mcp",
+        contract=GeneratedAnswer,
+        kind="mcp_tool",
+        display_name="Intra-document contract QA (MCP tool)",
+    )
+
+
+def main() -> None:
+    """Serve the intra_document_qa MCP tool over stdio. `RAG_MCP_DEMO=1` uses the no-infra demo answerer."""
+    if os.environ.get("RAG_MCP_DEMO") == "1":
+        build_intra_document_qa_mcp(demo_qa_fn()).run(transport="stdio")
+    else:  # single-tenant CLI serving: env-store fallback (issue 0035; a multi-tenant caller passes a resolver)
+        build_intra_document_qa_mcp(production_qa_fn(), env_store=production_env_store).run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

rag_wright/mcp/relational_qa_server.py

@@ -0,0 +1,171 @@
+"""MCP-PROTO Phase B (B2): the `relational_qa` MCP-tool server (FastMCP).
+
+Wraps the `relational_qa` SUBGRAPH (A2) as a single MCP tool
+`answer_relational_question(query, start_entity_id, max_hops)` -> a cited `GeneratedAnswer` (as JSON). The store
+(the entity/relationship graph) + the generation model (via the seam) bind SERVER-SIDE from env, so the tool
+call is just `{query, start_entity_id}` -- the token/coordination win. Evidence is GRAPH-STRUCTURAL (each reached
+entity cited by its source contract; no chunk text), so a relational answer is verifiable by contract id. Third
+Tier-1 leg wrapped, mirroring the `compliance_server.py` / `intra_document_qa_server.py` reference pattern.
+
+Grounded (library rule): FastMCP `server.py:L278` (`FastMCP(name, instructions, version=...)`), `@mcp.tool`,
+`run(transport=...)` -- confirmed against the cloned-repo AST graph (`graphify-out/framework/graph.json`) + the
+installed 3.4.6 signatures, same surface the reference servers use.
+
+`build_relational_qa_mcp(qa_fn)` injects the answerer so the server is hermetically testable (a stub `qa_fn`, no
+ArcadeDB/LLM). `main()` picks the production answerer (real subgraph, env-wired) or a deterministic demo answerer
+(`RAG_MCP_DEMO=1`, no infra) and serves over stdio (so a Deep Agent can spawn it).
+
+  # real (needs the entity graph + a model backend via env, like scripts/phase_a_leg_validate.py):
+  uv run --no-sync python -m rag_wright.mcp.relational_qa_server
+  # demo (no infra -- deterministic answer; for the Deep-Agent prototype):
+  RAG_MCP_DEMO=1 uv run --no-sync python -m rag_wright.mcp.relational_qa_server
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Awaitable, Callable, Optional
+
+from fastmcp import FastMCP
+
+from rag_wright.capabilities.answer_generator import GeneratedAnswer
+
+# qa_fn: (query, start_entity_id, max_hops) -> GeneratedAnswer. Injected so the server is testable without infra.
+# ASYNC-C1 (ADR-0057): async -- the tool handler awaits it, and it awaits the async relational_qa subgraph.
+from rag_wright.mcp.session_store import StoreResolver, resolve_request_store
+from rag_wright.store.seam import Store
+
+# issue 0035: store-PARAMETRIC -- the runner takes the per-request store (resolved out-of-band), never a
+# model-supplied one. The demo/stub runner ignores it.
+RelationalQAFn = Callable[[Optional[Store], str, str, int], Awaitable[GeneratedAnswer]]
+
+_TOOL_DESCRIPTION = (
+    "Answer a relational question about a known entity by traversing the contract entity graph, returning a "
+    "grounded, cited answer. From a start entity, follows relationship edges (default: contracting parties) up "
+    "to `max_hops`, and generates the answer from the reached graph structure ALONE: each fact is cited by the "
+    "SOURCE CONTRACT it came from (no chunk text), and a question the graph does not support yields an "
+    "abstention (abstained=true), never a fabrication. Use for 'which parties does X contract with' style "
+    "questions when the start entity is known."
+)
+
+
+def _answer_to_dict(answer: GeneratedAnswer) -> dict[str, Any]:
+    """The tool's JSON payload: the cited answer. This is the structured content the calling agent receives."""
+    return answer.model_dump(mode="json")
+
+
+def build_relational_qa_mcp(
+    qa_fn: RelationalQAFn, *, store_resolver: Optional[StoreResolver] = None, env_store: Any = None,
+    name: str = "rag-wright-relational-qa"
+) -> FastMCP:
+    """Build the FastMCP server exposing `relational_qa` as one tool. `qa_fn` is injected (real subgraph in
+    production; a stub in tests) so the MCP surface is testable with no ArcadeDB / LLM.
+
+    issue 0035: the tool takes NO tenant/database/scope argument (`start_entity_id` is an entity key WITHIN
+    the resolved store). `store_resolver` (caller-supplied) binds the store PER SESSION from the out-of-band
+    MCP request context; `env_store` is the single-tenant fallback. The resolved store is passed to `qa_fn`."""
+    mcp: FastMCP = FastMCP(
+        name=name,
+        instructions=(
+            "Relational question-answering over the contract entity graph. Use answer_relational_question to "
+            "answer a question about a known entity's relationships with cited, graph-structural evidence."
+        ),
+    )
+
+    @mcp.tool(name="answer_relational_question", description=_TOOL_DESCRIPTION)
+    async def answer_relational_question(query: str, start_entity_id: str, max_hops: int = 1) -> dict[str, Any]:
+        """Answer one relational question by traversing the entity graph from a start entity.
+
+        Args:
+            query: The natural-language relational question (e.g. "which parties does X contract with?").
+            start_entity_id: The entity_id to traverse from (must be in the graph).
+            max_hops: Traversal depth. Defaults to 1 (direct relationships).
+
+        Returns:
+            A cited answer: {answer, citations[], abstained}. `citations` are the SOURCE CONTRACT ids the facts
+            came from; `abstained` is true when the graph does not support an answer.
+        """
+        store = await resolve_request_store(store_resolver, env_store)  # per-request, out-of-band (issue 0035)
+        return _answer_to_dict(await qa_fn(store, query, start_entity_id, max_hops))
+
+    return mcp
+
+
+# --- production answerer: the real relational_qa subgraph, env-wired (like scripts/phase_a_leg_validate.py) -----
+
+
+def production_qa_fn(*, answer_model_id: str | None = None) -> RelationalQAFn:
+    """Wire the real `relational_qa` over the env-selected store + model: ArcadeDB entity graph (`ARCADEDB_*`,
+    `QA_DB`), the GENERAL model for generation (via the seam; `RAG_SERVING`). Generation goes through
+    `answer_model_for` so it takes the right path per ADR-0045 (client-side tag-parse). Heavy imports are lazy so
+    `RAG_MCP_DEMO` never pays for them."""
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    from rag_wright.capabilities.answer_generator import answer_model_for
+    from rag_wright.models.profiles import ModelRole, model_for
+    from rag_wright.subgraphs.relational_qa import production_relational_qa
+
+    answer_model = answer_model_for(answer_model_id or model_for(ModelRole.GENERAL))  # tenant-independent
+
+    async def _qa(store: Optional[Store], query: str, start_entity_id: str, max_hops: int) -> GeneratedAnswer:
+        leg = production_relational_qa(store=store, answer_model=answer_model)  # per-request store (0035)
+        out = await leg.ainvoke({"query": query, "start_entity_id": start_entity_id, "max_hops": max_hops})
+        ans = out.get("answer")
+        if ans is None:  # defensive: no answer produced -> an honest abstention, never a fabrication
+            return GeneratedAnswer(
+                answer="The entity graph could not be traversed for this question.",
+                citations=[], abstained=True)
+        return ans
+
+    return _qa
+
+
+def production_env_store() -> Store:
+    """The single-tenant fallback store from `QA_DB` (demo / eval / single-tenant). Built lazily so
+    `RAG_MCP_DEMO` never touches ArcadeDB; a multi-tenant caller passes a `store_resolver` (issue 0035)."""
+    from rag_wright.store.arcadedb import ArcadeDBStore
+
+    return ArcadeDBStore.from_env(database=os.environ.get("QA_DB", "ragwright_cuad_full"))
+
+
+# --- demo answerer: a deterministic, real-shaped cited answer (no ArcadeDB / LLM) for the Deep-Agent prototype -
+
+
+def demo_qa_fn() -> RelationalQAFn:
+    """A deterministic stub with the REAL contract shape -- a cited, graph-structural relational answer. Lets the
+    Deep-Agent prototype (and the hermetic test) exercise the full MCP path with no ArcadeDB / LLM."""
+    _cid = "AcmeBetaMSA:3:beef0002"
+
+    async def _qa(store: Optional[Store], query: str, start_entity_id: str, max_hops: int) -> GeneratedAnswer:
+        return GeneratedAnswer(
+            answer=f"AcmeCorp contracts with BetaLLC (per AcmeBetaMSA) [{_cid}].",
+            citations=[_cid], abstained=False)
+
+    return _qa
+
+
+def register_relational_qa_mcp(registry) -> None:
+    """Register `relational_qa_mcp` (MCP-PROTO Phase B): the ARD `mcp_tool` surface of the `relational_qa`
+    subgraph -- the same capability exposed as a discoverable, cross-agent MCP tool (`answer_relational_question`,
+    served by `rag_wright.mcp.relational_qa_server`) so an agent can call it as ONE tool via ARD search instead of
+    embedding the subgraph. Distinct ARD identity from the in-process `relational_qa` subgraph; same output
+    contract `GeneratedAnswer`."""
+    registry.register(
+        "relational_qa_mcp",
+        contract=GeneratedAnswer,
+        kind="mcp_tool",
+        display_name="Relational contract QA (MCP tool)",
+    )
+
+
+def main() -> None:
+    """Serve the relational_qa MCP tool over stdio. `RAG_MCP_DEMO=1` uses the no-infra demo answerer."""
+    if os.environ.get("RAG_MCP_DEMO") == "1":
+        build_relational_qa_mcp(demo_qa_fn()).run(transport="stdio")
+    else:  # single-tenant CLI: env-store fallback (issue 0035; a multi-tenant caller passes a resolver)
+        build_relational_qa_mcp(production_qa_fn(), env_store=production_env_store).run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

rag_wright/mcp/session_store.py

@@ -0,0 +1,64 @@
+"""issue 0035: the seam that lets an MCP tool be multi-tenant-safe.
+
+THE PRINCIPLE: an MCP tool NEVER takes a tenant, database, or scope as a model-supplied argument. A tool's
+arguments are filled by a language model, so a tenant argument puts a cross-tenant read one token-prediction
+away. Instead the store is resolved from **session context the CALLER establishes out-of-band** (MCP
+initialization params / transport headers), never from a model argument and never from a per-process env var
+in a multi-tenant deployment.
+
+The engine does NOT implement tenancy (that is product policy). It provides this seam: a `build_*_mcp` factory
+accepts an optional `store_resolver`, and per request resolves the store from the caller-populated MCP request
+context. When no resolver is wired, it falls back to a single process-wide store -- correct for a demo, an
+eval, or a single-tenant deployment, and still with no model-supplied tenant.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Awaitable, Callable, Optional, Union
+
+from rag_wright.store.seam import Store
+
+# The caller binds a store per SESSION: given the opaque per-request MCP context (whatever tenancy the caller
+# set out-of-band -- init params / headers), return that tenant's store. Sync or async. It is handed the MCP
+# request context, NEVER a model-supplied value.
+StoreResolver = Callable[[Any], Union[Store, Awaitable[Store]]]
+
+# argument names an MCP tool must never expose to the model (the guard test asserts none appear in any schema).
+FORBIDDEN_TENANT_ARGS = frozenset({"database", "db", "tenant", "scope", "corpus", "workspace", "customer"})
+
+
+async def resolve_request_store(
+    store_resolver: Optional[StoreResolver], env_store: Union[Store, Callable[[], Store], None]
+) -> Optional[Store]:
+    """The per-request store, resolved WITHOUT any model-supplied argument.
+
+    - `store_resolver` given (multi-tenant): resolve against the CURRENT MCP request context (`get_context()`),
+      so the caller binds tenancy per session. The context is opaque to the engine -- the caller reads its own
+      tenancy from it. Awaited if the resolver is async.
+    - `store_resolver` None (single-tenant / demo / eval): return `env_store` (a store, or a factory returning
+      one), the process-wide fallback. Still never a model argument.
+    """
+    if store_resolver is not None:
+        from fastmcp.server.dependencies import get_context  # the current request's context (caller-populated)
+
+        ctx = get_context()
+        out = store_resolver(ctx)
+        return await out if inspect.isawaitable(out) else out
+    return env_store() if callable(env_store) else env_store
+
+
+def assert_no_tenant_arguments(mcp: Any) -> list[str]:
+    """Return the offending `tool.arg` names if any MCP tool exposes a model-supplied tenant/database/scope
+    argument (issue 0035); an empty list means the server is safe. The guard test fails the build on any hit;
+    a caller may also call it on its own servers. Model-facing arguments are the tool's input-schema
+    `properties`; a `get_context()`-injected context is never in that schema, so it is correctly ignored."""
+    import asyncio
+
+    tools = asyncio.run(mcp.list_tools())
+    offenders: list[str] = []
+    for tool in tools:
+        props = set((getattr(tool, "parameters", {}) or {}).get("properties", {}))
+        for bad in sorted(props & FORBIDDEN_TENANT_ARGS):
+            offenders.append(f"{tool.name}.{bad}")
+    return offenders

rag_wright/mcp/typed_property_retrieval_server.py

@@ -0,0 +1,191 @@
+"""MCP-PROTO Phase B (B3): the `typed_property_retrieval` MCP-tool server (FastMCP).
+
+Wraps the `typed_property_retrieval` SUBGRAPH (Leg B) as a single MCP tool `retrieve_typed_property_spans(query)`
+-> a `TypedPropertyRetrieval` (the query + its property-boosted, cited ranked spans) as JSON. The store (the
+clause KG) + the encoders/models (BGE + LegalBERT + granite constraint-extraction + the function classifier via
+the seam) bind SERVER-SIDE from env, so the tool call is just `{query}` -- the token/coordination win. An
+external agent discovers this via ARD search and calls it.
+
+Unlike B1/B2 (which return a `GeneratedAnswer`), this leg's contract is `TypedPropertyRetrieval` -- corpus-wide
+RETRIEVAL, not single-answer generation -- so the tool returns ranked cited spans, not a written answer. Fourth
+and last Tier-1 leg wrapped, mirroring the `compliance_server.py` reference pattern.
+
+Grounded (library rule): FastMCP `server.py:L278` (`FastMCP(name, instructions, version=...)`), `@mcp.tool`,
+`run(transport=...)` -- confirmed against the cloned-repo AST graph (`graphify-out/framework/graph.json`) + the
+installed 3.4.6 signatures, same surface the reference servers use.
+
+`build_typed_property_retrieval_mcp(retrieval_fn)` injects the retriever so the server is hermetically testable
+(a stub, no ArcadeDB/encoders/LLM). `main()` picks the production retriever (real subgraph, env-wired) or a
+deterministic demo retriever (`RAG_MCP_DEMO=1`, no infra) and serves over stdio (so a Deep Agent can spawn it).
+
+  # real (needs the clause KG + the encoders/models via env, like scripts/phase_a_leg_validate.py):
+  uv run --no-sync python -m rag_wright.mcp.typed_property_retrieval_server
+  # demo (no infra -- deterministic ranked spans; for the Deep-Agent prototype):
+  RAG_MCP_DEMO=1 uv run --no-sync python -m rag_wright.mcp.typed_property_retrieval_server
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Awaitable, Callable, Optional
+
+from fastmcp import FastMCP
+
+from rag_wright.capabilities.property_boosted_retrieval import RankedSpan
+from rag_wright.capabilities.span_relevance_judgment import RelevanceVerdict
+from rag_wright.subgraphs.typed_property_retrieval import JudgedSpan, TypedPropertyRetrieval
+
+# retrieval_fn: (query) -> TypedPropertyRetrieval. Injected so the server is testable without infra.
+# ASYNC-C1 (ADR-0057): async -- the tool handler awaits it, and it awaits the async typed_property_retrieval subgraph.
+from rag_wright.mcp.session_store import StoreResolver, resolve_request_store
+from rag_wright.store.seam import Store
+
+# issue 0035: store-PARAMETRIC -- the runner takes the per-request store (resolved out-of-band), never a
+# model-supplied one. The demo/stub runner ignores the store.
+RetrievalFn = Callable[[Optional[Store], str], Awaitable[TypedPropertyRetrieval]]
+
+_TOOL_DESCRIPTION = (
+    "Retrieve the most relevant contract clauses for a query from across the corpus, property-boosted and "
+    "cited. Extracts the query's typed (dimension, value) constraints and routes its clause function(s), then "
+    "ranks a bounded semantic pool by constraint match, returning ranked spans each with its span_id citation, "
+    "text, clause function, match score, and the constraints it satisfied. This is corpus-wide RETRIEVAL (ranked "
+    "evidence), not a written answer. Use to find clauses matching a typed condition (e.g. 'cap on liability set "
+    "at a multiple of the fees paid') across many contracts."
+)
+
+
+def _retrieval_to_dict(retrieval: TypedPropertyRetrieval) -> dict[str, Any]:
+    """The tool's JSON payload: the query + its ranked cited spans. This is the structured content the calling
+    agent receives."""
+    return retrieval.model_dump(mode="json")
+
+
+def build_typed_property_retrieval_mcp(
+    retrieval_fn: RetrievalFn, *, store_resolver: Optional[StoreResolver] = None,
+    env_store: Any = None, name: str = "rag-wright-typed-property-retrieval"
+) -> FastMCP:
+    """Build the FastMCP server exposing `typed_property_retrieval` as one tool. `retrieval_fn` is injected (real
+    subgraph in production; a stub in tests) so the MCP surface is testable with no ArcadeDB / encoders / LLM.
+
+    issue 0035: the tool takes NO tenant/database/scope argument. `store_resolver` (caller-supplied) binds the
+    store PER SESSION from the out-of-band MCP request context; `env_store` is the single-tenant fallback used
+    when no resolver is wired. The resolved store is passed to `retrieval_fn` -- never a model-supplied value."""
+    mcp: FastMCP = FastMCP(
+        name=name,
+        instructions=(
+            "Corpus-wide, property-boosted clause retrieval over the contract KG. Use "
+            "retrieve_typed_property_spans to find the clauses matching a typed condition, ranked and cited."
+        ),
+    )
+
+    @mcp.tool(name="retrieve_typed_property_spans", description=_TOOL_DESCRIPTION)
+    async def retrieve_typed_property_spans(query: str) -> dict[str, Any]:
+        """Retrieve ranked, cited clause spans matching a query from across the corpus.
+
+        Args:
+            query: The retrieval query, ideally expressing a typed condition (a clause function and/or a
+                property value, e.g. "cap on liability at a multiple of fees").
+
+        Returns:
+            {query, results[]} where each result is a ranked cited span WITH its relevance verdict (issue 0023):
+            {span: {span_id, text, function, match_score, matched[], rank}, relevance: {verdict, rationale,
+            confidence} | null}. `verdict` is relevant | not_relevant | uncertain; `relevance` is null only when no
+            relevance judge is wired. Empty results when nothing matches.
+        """
+        store = await resolve_request_store(store_resolver, env_store)  # per-request, out-of-band (issue 0035)
+        return _retrieval_to_dict(await retrieval_fn(store, query))
+
+    return mcp
+
+
+# --- production retriever: the real Leg B subgraph, env-wired (like scripts/phase_a_leg_validate.py validate_leg_b) -
+
+
+def production_retrieval_fn(*, k: int = 8) -> RetrievalFn:
+    """Wire the real `typed_property_retrieval` over the encoders + models (BGE embedder local or the A100
+    `STACK_URL` adapter; granite constraint-extraction via the seam, `RAG_SERVING`). ADR-0047: no function
+    classifier -- whole-index pool. Heavy imports are lazy so `RAG_MCP_DEMO` never pays for them.
+
+    issue 0035: store-PARAMETRIC. The tenant-independent pieces (embedder, model) are built ONCE here; the
+    STORE arrives per request (resolved out-of-band by the caller) and the leg is wired against it per call --
+    so one server process serves many tenants without a per-process database."""
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    from rag_wright.capabilities.dg_extraction import default_extraction_model
+    from rag_wright.capabilities.remote_encoders import query_embedder
+    from rag_wright.subgraphs.typed_property_retrieval import production_typed_property_retrieval
+
+    embedder = query_embedder()  # tenant-independent, built once
+    extract_model = default_extraction_model("query-constraints")
+
+    async def _retrieve(store: Optional[Store], query: str) -> TypedPropertyRetrieval:
+        leg = production_typed_property_retrieval(store=store, embedder=embedder, extract_model=extract_model, k=k)
+        out = await leg.ainvoke({"query": query})
+        return out["retrieval"]
+
+    return _retrieve
+
+
+def production_env_store() -> Store:
+    """The single-tenant fallback store from `QA_DB` (a demo / eval / single-tenant deployment). Built lazily so
+    `RAG_MCP_DEMO` never touches ArcadeDB; a multi-tenant caller passes a `store_resolver` instead (issue 0035)."""
+    from rag_wright.store.arcadedb import ArcadeDBStore
+
+    return ArcadeDBStore.from_env(database=os.environ.get("QA_DB", "ragwright_cuad_full"))
+
+
+# --- demo retriever: deterministic, real-shaped ranked cited spans (no infra) for the Deep-Agent prototype -----
+
+
+def demo_retrieval_fn() -> RetrievalFn:
+    """A deterministic stub with the REAL contract shape -- two ranked, cited, property-matched cap spans. Lets
+    the Deep-Agent prototype (and the hermetic test) exercise the full MCP path with no ArcadeDB / encoders."""
+
+    async def _retrieve(store: Optional[Store], query: str) -> TypedPropertyRetrieval:  # store ignored (demo)
+        results = [
+            JudgedSpan(
+                span=RankedSpan(
+                    span_id="AcmeMSA:12:deadbeef01",
+                    text="Seller's aggregate liability shall not exceed two times (2x) the fees paid.",
+                    function="Cap On Liability", match_score=0.94, matched=[("cap_multiple", "2x")], rank=1),
+                relevance=RelevanceVerdict(verdict="relevant", rationale="an express liability cap", confidence=0.95)),
+            JudgedSpan(
+                span=RankedSpan(
+                    span_id="BetaSaaS:7:cafe0042",
+                    text="In no event shall liability exceed the total fees paid in the prior 12 months.",
+                    function="Cap On Liability", match_score=0.71, matched=[("cap_basis", "fees paid")], rank=2),
+                relevance=RelevanceVerdict(verdict="relevant", rationale="a fees-paid liability cap", confidence=0.9)),
+        ]
+        return TypedPropertyRetrieval(query=query, results=results)
+
+    return _retrieve
+
+
+def register_typed_property_retrieval_mcp(registry) -> None:
+    """Register `typed_property_retrieval_mcp` (MCP-PROTO Phase B): the ARD `mcp_tool` surface of the
+    `typed_property_retrieval` subgraph -- the same capability exposed as a discoverable, cross-agent MCP tool
+    (`retrieve_typed_property_spans`, served by `rag_wright.mcp.typed_property_retrieval_server`) so an agent can
+    call it as ONE tool via ARD search instead of embedding the subgraph. Distinct ARD identity from the
+    in-process `typed_property_retrieval` subgraph; same output contract `TypedPropertyRetrieval`."""
+    registry.register(
+        "typed_property_retrieval_mcp",
+        contract=TypedPropertyRetrieval,
+        kind="mcp_tool",
+        display_name="Typed property-boosted retrieval (MCP tool)",
+    )
+
+
+def main() -> None:
+    """Serve the typed_property_retrieval MCP tool over stdio. `RAG_MCP_DEMO=1` uses the no-infra demo retriever."""
+    # single-tenant CLI serving: env-store fallback (no resolver). A multi-tenant caller builds the server in
+    # process with a `store_resolver` instead (issue 0035).
+    if os.environ.get("RAG_MCP_DEMO") == "1":
+        build_typed_property_retrieval_mcp(demo_retrieval_fn()).run(transport="stdio")
+    else:
+        build_typed_property_retrieval_mcp(production_retrieval_fn(), env_store=production_env_store).run(
+            transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

rag_wright/models/__init__.py

@@ -0,0 +1,8 @@
+"""The model-profile seam (tech stack, assumption 2).
+
+Model-neutral through OpenRouter by default (Gemma 4 class for reasoning, generation,
+vision-to-text, and RLM; a smaller model for chunking and summarization; a larger model for
+quality-sensitive extraction), with local open-model deployment supported. Structured-output
+calls go through this seam, keyed by model id, applied at the single point where a model is
+constructed. Provider flags live in profile config and a dated ADR, never in node or agent code.
+"""