cuery.response
==============

.. py:module:: cuery.response

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   cuery.response.TYPES
   cuery.response.ResponseClass


Classes
-------

.. autoapisummary::

   cuery.response.Response
   cuery.response.ResponseSet


Functions
---------

.. autoapisummary::

   cuery.response.token_usage
   cuery.response.with_cost
   cuery.response.transpose
   cuery.response.is_response_subclass
   cuery.response.get_module_responses
   cuery.response.models_from_jsonschema


Module Contents
---------------

.. py:data:: TYPES

.. py:class:: Response(/, **data)

   Bases: :py:obj:`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.).


   .. py:attribute:: model_config

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


   .. py:attribute:: _raw_response
      :type:  Any | None
      :value: None



   .. py:method:: token_usage()

      Get the token usage from the raw response.



   .. py:method:: to_dict()

      Convert the model to a dictionary.



   .. py:method:: fallback()
      :classmethod:



   .. py:method:: iterfield()
      :classmethod:


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



   .. py:method:: is_multivalued()
      :classmethod:


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



   .. py:method:: from_dict(name, fields)
      :staticmethod:


      Create an instance of the model from a dictionary.



   .. py:method:: from_config(source, *keys)
      :classmethod:


      Create an instance of the model from a configuration dictionary.



   .. py:method:: __rich_console__(console, options)


.. py:function:: token_usage(responses)

.. py:function:: with_cost(usage, model)

.. py:data:: ResponseClass

.. py:function:: transpose(dicts)

   Transpose a list of dictionaries into a dictionary of lists.


.. py:class:: 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.


   .. py:attribute:: responses


   .. py:attribute:: context


   .. py:attribute:: required


   .. py:attribute:: iterfield


   .. py:method:: __iter__()


   .. py:method:: __len__()


   .. py:method:: __getitem__(index)


   .. py:method:: to_dict(item, fallback_name = None)
      :staticmethod:


      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.



   .. py:method:: to_records(explode = True)

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



   .. py:method:: to_pandas(explode = True, normalize = True, prefix = None)

      Convert list of responses to DataFrame.



   .. py:method:: usage()

      Get the token usage for all responses.



   .. py:method:: __str__()


   .. py:method:: __repr__()


.. py:function:: is_response_subclass(obj)

.. py:function:: get_module_responses(module)

.. py:function:: 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/
   - https://github.com/koxudaxi/datamodel-code-generator/issues/331
   - https://github.com/koxudaxi/datamodel-code-generator/issues/278#issuecomment-764498857
   - https://github.com/VRSEN/agency-swarm/blob/main/agency_swarm/tools/ToolFactory.py