aito.client.v2.responses

Response classes returned by the AitoClientV2

The v2 envelope (core/docs/v2-response-format.md §3) is:

{"kind": "<rows|estimate|aggregate|evaluation|batch|error>",
 <payload>,          # `hits` (+ offset, total) for rows; `data` otherwise
 "meta":     {...},  # opt-in, see AitoClientV2(meta=True)
 "warnings": [...]}  # non-fatal notes, always additive

Two things about that envelope are worth knowing before reading this module.

`rows` is bare. For v1 compatibility a rows response carries no kind at all — {offset, total, hits}. The documented client rule is kind ?? "rows".

…but an absent `kind` does not prove `rows`. The non-rows envelopes are built by the rep2-native code paths only. A legacy type: table answered through a v2 endpoint falls to the rep1 compatibility shim, which returns the flat v1 shape — so POST /api/v2/_estimate returns {"estimate": ..., "why": ...} for a legacy table and {"kind": "estimate", "data": {"value": ...}} for a collection, on the same build. Applying kind ?? "rows" to the first one classifies a scalar as a page of rows.

unwrap_payload() is the single place that copes with this: the caller says which kind it asked for, an envelope of that kind is unwrapped, a bare body is passed through, and a different kind raises. When the engine unifies the two shapes, that one function is the only thing to delete.

Module Attributes

KIND_TO_RESPONSE_CLS

result kind -> the response class that parses it

Functions

response_for_kind(kind)	return the response class for a result kind, defaulting to V2RowsResponse
unwrap_payload(json, kind)	return the payload of a v2 response, whether or not it is enveloped

Classes

V2AggregateResponse(json)	An aggregate response — a small object of aggregate results
V2BatchResponse(json)	A batch response — an array of typed sub-results
V2EstimateResponse(json)	An estimate response — a single predicted numeric value
V2EvaluationResponse(json)	An evaluation response — the metrics of a held-out evaluation
V2Hit(json)	A single hit of a rows response
V2Response(json)	The base class of a v2 API response
V2RowsResponse(json)	A rows response — a page of hits
V2Warning(json)	A non-fatal note attached to a v2 response