aeat.entrypoints.mcp._corpus_tools module¶

The aeat_corpus_search grounding tool: hybrid search over the legal corpus.

ADR R3’s grounding surface reaches the model as a read-only console tool that searches the bundled BOE/AEAT corpus and returns grounded hits — each carrying its corpus_ref, title, a verbatim snippet, the fused relevance score, and an aeat://corpus/{ref} URI a resources-capable client can read to pull the full verbatim text. An exact citation id short-circuits straight to the resolved authoritative text.

Like _harness_tools / _resources, this module is SDK-independent pure functions over typed models: corpus_search_payload_from_response() and render_corpus_search_text() carry no protocol detail and are unit-tested directly, while build_corpus_search_tool() lazily adapts onto the MCP SDK’s Tool type so the module still imports (and the server refuses gracefully) when the aeat-cli[agent] extra is absent. The retrieval itself is owned by the application service (search_corpus()), consumed through the package facade per service-imports-via-top-level-reexports.

CORPUS_SEARCH_TOOL¶: The grounding tool’s MCP name (the corpus.search verb, per the aeat_<key> convention).

corpus_uri(corpus_ref)[source]¶

Render the aeat://corpus/<ref> URI for a corpus reference.

Return type:: str
Parameters:: corpus_ref (str)

class CorpusSearchResultRow(**data)[source]¶

Bases: BaseModel

One grounded corpus hit surfaced to the model.

Parameters:

corpus_ref (str)
title (str)
snippet (str)
score (float)
uri (str)

corpus_ref: str¶

title: str¶

snippet: str¶

score: float¶

uri: str¶

class CorpusCitationResult(**data)[source]¶

Bases: BaseModel

The short-circuit result when the query is an exact citation id.

Parameters:

citation_id (str)
document_id (str)
permalink (str)
uri (str)
snippet (str)

citation_id: str¶

document_id: str¶

permalink: str¶

uri: str¶

snippet: str¶

class CorpusSearchPayload(**data)[source]¶

Bases: BaseModel

The grounding tool’s structured result.

mode records how the response was produced (citation / hybrid / lexical_only). For a citation query citation is populated and results is empty; otherwise results carries the ranked hits.

Parameters:

query (str)
mode (RetrievalMode)
results (tuple[CorpusSearchResultRow, ...])
citation (CorpusCitationResult | None)

query: str¶

mode: RetrievalMode¶

results: tuple[CorpusSearchResultRow, ...]¶

citation: CorpusCitationResult | None¶

corpus_search_payload_from_response(response)[source]¶

Map a RetrievalResponse to the tool’s typed payload.

Return type:: CorpusSearchPayload
Returns:: A CorpusSearchPayload.
Parameters:: response (RetrievalResponse)

build_corpus_search_payload(query, *, limit=8)[source]¶

Run grounding retrieval for query and return the tool payload.

Return type:

CorpusSearchPayload

Returns:

A CorpusSearchPayload.

Parameters:

query (str)
limit (int)

render_corpus_search_text(payload)[source]¶

Render the payload as markdown for the tool’s text content.

Return type:: str
Parameters:: payload (CorpusSearchPayload)

build_corpus_search_tool()[source]¶

Build the SDK Tool for the grounding search tool.

Lazily imports the SDK types so the module imports without the aeat-cli[agent] extra. Annotated readOnlyHint / idempotentHint: it reads the bundled corpus and never mutates state.

Return type:: Tool
Returns:: The aeat_corpus_search Tool object.