RetrievalResponse#

class scikitplot.corpus.RetrievalResponse(hits=<factory>, legs=<factory>, query=None, status=None)[source]#

Hits plus the story of how they were obtained.

Parameters:
hitslist

Fused, ranked hits.

legslist of LegOutcome, optional

One entry per evidence path considered, including skipped ones.

querystr or None, optional

The query text, for provenance.

statusRetrievalStatus or None, optional

Normally left None so it is derived from legs and hits. Pass a value only for terminal outcomes the legs cannot express, such as CANCELLED.

Parameters:

Notes

User. This object stands in for the plain list it replaced: len(), iteration and indexing all address the hits.

Developer. Deriving status rather than accepting it is what makes the EMPTY-requires-all-legs-ran rule enforceable. See _derive_status.

Examples

>>> from scikitplot.corpus._diagnostics import ErrorCategory, ErrorRecord
>>> ok = LegOutcome(LegKind.LEXICAL, LegStatus.EMPTY)
>>> RetrievalResponse(hits=[], legs=[ok]).status
<RetrievalStatus.EMPTY: 'empty'>

A leg that could not run makes an empty result DEGRADED, not EMPTY:

>>> bad = LegOutcome(
...     LegKind.DENSE,
...     LegStatus.FAILED,
...     error=ErrorRecord(
...         code="NO_QUERY_EMBEDDING",
...         category=ErrorCategory.CAPABILITY,
...         message="no query embedding supplied",
...     ),
... )
>>> RetrievalResponse(hits=[], legs=[ok, bad]).status
<RetrievalStatus.DEGRADED: 'degraded'>
property degraded_legs: list[LegOutcome]#

Legs that were requested but did not run normally.

error_records()[source]#

Return every diagnostic attached to a leg.

Return type:

list[ErrorRecord]

hits: list[source]#
leg(kind)[source]#

Return the outcome for one evidence path, if present.

Parameters:

kind (LegKind | str)

Return type:

LegOutcome | None

legs: list[LegOutcome][source]#
query: str | None = None#
status: RetrievalStatus | None = None#
to_dict()[source]#

Return a JSON-compatible mapping of the outcome (not the hits).

Return type:

dict[str, Any]