"""
Typed requests and functions for the ``query`` and ``reindex`` commands.
"""
from __future__ import annotations
from typing import Optional
from pydantic import Field
from ..evidence_processing import apply_evidence_filter, apply_evidence_reranker
from ..models import QueryBudget, RetrievalResult
from ..retrievers import get_retriever
from ._common import ApiRequestModel, ApiResponseModel, open_request_corpus
[docs]
class QueryRequest(ApiRequestModel):
"""
Request to run a retrieval query against a built snapshot.
The query never builds a snapshot. When ``snapshot_id`` is absent the corpus latest snapshot
is used, and a corpus without one is an error.
:ivar corpus_path: Corpus path or uniform resource identifier.
:vartype corpus_path: str
:ivar query_text: Query text.
:vartype query_text: str
:ivar snapshot_id: Snapshot identifier, or None for the corpus latest snapshot.
:vartype snapshot_id: str or None
:ivar retriever_id: Retriever the snapshot must use, or None to accept the snapshot retriever.
:vartype retriever_id: str or None
:ivar budget: Evidence selection budget.
:vartype budget: QueryBudget
:ivar reranker_id: Optional reranker applied after retrieval.
:vartype reranker_id: str or None
:ivar minimum_score: Optional minimum score threshold applied after retrieval.
:vartype minimum_score: float or None
"""
corpus_path: str = Field(min_length=1)
query_text: str
snapshot_id: Optional[str] = Field(default=None, min_length=1)
retriever_id: Optional[str] = Field(default=None, min_length=1)
budget: QueryBudget
reranker_id: Optional[str] = Field(default=None, min_length=1)
minimum_score: Optional[float] = None
[docs]
class ReindexRequest(ApiRequestModel):
"""
Request to rebuild the corpus catalog from the on-disk corpus.
:ivar corpus_path: Corpus path or uniform resource identifier.
:vartype corpus_path: str
"""
corpus_path: str = Field(min_length=1)
[docs]
class ReindexResponse(ApiResponseModel):
"""
Catalog rebuild statistics.
:ivar scanned: Files examined.
:vartype scanned: int
:ivar skipped: Files skipped.
:vartype skipped: int
:ivar inserted: Catalog entries added.
:vartype inserted: int
:ivar updated: Catalog entries refreshed.
:vartype updated: int
"""
scanned: int = Field(ge=0)
skipped: int = Field(ge=0)
inserted: int = Field(ge=0)
updated: int = Field(ge=0)
[docs]
def query(request: QueryRequest) -> RetrievalResult:
"""
Run a retrieval query and return structured evidence.
:param request: Validated request.
:type request: QueryRequest
:return: Retrieval result with evidence.
:rtype: RetrievalResult
:raises ValueError: If no snapshot is available or the retriever does not match the snapshot.
"""
corpus = open_request_corpus(request.corpus_path)
snapshot_id = request.snapshot_id or corpus.latest_snapshot_id
if not snapshot_id:
raise ValueError(
"No snapshot identifier provided and no latest snapshot is recorded for this corpus"
)
snapshot = corpus.load_snapshot(snapshot_id)
if request.retriever_id and request.retriever_id != snapshot.configuration.retriever_id:
raise ValueError(
"Retriever mismatch: snapshot uses "
f"{snapshot.configuration.retriever_id!r} but {request.retriever_id!r} was requested"
)
retriever = get_retriever(snapshot.configuration.retriever_id)
result = retriever.query(
corpus, snapshot=snapshot, query_text=request.query_text, budget=request.budget
)
processed_evidence = result.evidence
if request.reranker_id:
processed_evidence = apply_evidence_reranker(
reranker_id=request.reranker_id,
query_text=result.query_text,
evidence=processed_evidence,
)
if request.minimum_score is not None:
processed_evidence = apply_evidence_filter(
filter_id="filter-minimum-score",
query_text=result.query_text,
evidence=processed_evidence,
config={"minimum_score": float(request.minimum_score)},
)
if processed_evidence is not result.evidence:
result = result.model_copy(update={"evidence": processed_evidence})
return result
[docs]
def reindex(request: ReindexRequest) -> ReindexResponse:
"""
Rebuild the corpus catalog from the on-disk corpus.
:param request: Validated request.
:type request: ReindexRequest
:return: Catalog rebuild statistics.
:rtype: ReindexResponse
"""
return ReindexResponse.model_validate(open_request_corpus(request.corpus_path).reindex())