cuery.response#

Base classes for LLM responses and response sets.

Faciliates conversion of responses to simpler Python objects and DataFrames, as well as caching raw API responses for token usage calculation etc.

Attributes#

TYPES

ResponseClass

Classes#

Response

Base class for all response models.

ResponseSet

A collection of responses

Functions#

token_usage(responses)

with_cost(usage, model)

transpose(dicts)

Transpose a list of dictionaries into a dictionary of lists.

is_response_subclass(obj)

get_module_responses(module)

models_from_jsonschema(schema[, log])

Create response models dynamically from configuration files.

Module Contents#

cuery.response.TYPES#
class cuery.response.Response(/, **data)#

Bases: pydantic.BaseModel

Base class for all response models.

Adds functionality to cache the raw response from the API call, calculate token usage, and to create a fallback instance, which by default is an empty model with all fields set to None.

Also implements rich’s console protocol for pretty printing of the model’s fields, and allows inspection of the model’s fields to determine if it has a single multivalued field (a list) or not (which can be used to automatically “explode” items into DataFrame rows e.g.).

Parameters:

data (Any)

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

_raw_response: Any | None = None#
token_usage()#

Get the token usage from the raw response.

Return type:

dict | None

to_dict()#

Convert the model to a dictionary.

Return type:

dict

classmethod fallback()#
Return type:

Response

classmethod iterfield()#

Check if a pydantic model has a single field that is a list.

Return type:

str | None

classmethod is_multivalued()#

Check if a pydantic model has a single field that is a list.

Return type:

bool

static from_dict(name, fields)#

Create an instance of the model from a dictionary.

Parameters:

  • name (str)

  • fields (dict)

Return type:

ResponseClass

classmethod from_config(source, *keys)#

Create an instance of the model from a configuration dictionary.

Parameters:

  • source (str | pathlib.Path | dict)

  • keys (list)

Return type:

ResponseClass

__rich_console__(console, options)#
Parameters:

  • console (cuery.pretty.Console)

  • options (cuery.pretty.ConsoleOptions)

Return type:

cuery.pretty.RenderResult

cuery.response.token_usage(responses)#
Parameters:

responses (collections.abc.Iterable[Response])

Return type:

pandas.DataFrame

cuery.response.with_cost(usage, model)#
Parameters:

  • usage (pandas.DataFrame)

  • model (str)

Return type:

pandas.DataFrame

cuery.response.ResponseClass#
cuery.response.transpose(dicts)#

Transpose a list of dictionaries into a dictionary of lists.

Parameters:

dicts (list[dict])

Return type:

dict[str, list]

class cuery.response.ResponseSet(responses, context, required)#

A collection of responses

This class is used to manage multiple responses, allowing iteration over them, conversion to records or DataFrame, and calculating token usage across all responses.

Parameters:

  • responses (Response | list[Response])

  • context (cuery.context.AnyContext | None)

  • required (list[str] | None)

responses#
context#
required#
iterfield#
__iter__()#
__len__()#
__getitem__(index)#
Parameters:

index (int)

Return type:

Response

static to_dict(item, fallback_name=None)#

Convert an item to a dictionary.

If the item is not a dict-like object, return a fallback dict if a fallback name is provided, otherwise return the item as is.

Parameters:

  • item (Any)

  • fallback_name (str | None)

Return type:

Any

to_records(explode=True)#

Convert to list of dicts, optionally with original context merged in.

Parameters:

explode (bool)

Return type:

list[dict] | pandas.DataFrame

to_pandas(explode=True, normalize=True, prefix=None)#

Convert list of responses to DataFrame.

Parameters:

  • explode (bool)

  • normalize (bool)

  • prefix (str | None)

Return type:

pandas.DataFrame

usage()#

Get the token usage for all responses.

Return type:

pandas.DataFrame

__str__()#
Return type:

str

__repr__()#
Return type:

str

cuery.response.is_response_subclass(obj)#
cuery.response.get_module_responses(module)#
Parameters:

module (types.ModuleType)

cuery.response.models_from_jsonschema(schema, log=False)#

Create response models dynamically from configuration files.

Also see: - https://koxudaxi.github.io/datamodel-code-generator/using_as_module/ - koxudaxi/datamodel-code-generator#331 - koxudaxi/datamodel-code-generator#278 - VRSEN/agency-swarm

Parameters:

  • schema (str | dict)

  • log (bool)

Return type:

list[ResponseClass]