cuery ===== .. py:module:: cuery Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/cuery/actors/index /autoapi/cuery/asy/index /autoapi/cuery/builder/index /autoapi/cuery/call/index /autoapi/cuery/cli/index /autoapi/cuery/context/index /autoapi/cuery/cost/index /autoapi/cuery/models/index /autoapi/cuery/pretty/index /autoapi/cuery/prompt/index /autoapi/cuery/resources/index /autoapi/cuery/response/index /autoapi/cuery/search/index /autoapi/cuery/seo/index /autoapi/cuery/server/index /autoapi/cuery/task/index /autoapi/cuery/templates/index /autoapi/cuery/tool/index /autoapi/cuery/tools/index /autoapi/cuery/utils/index Attributes ---------- .. autoapisummary:: cuery.AnyContext cuery.ResponseClass Classes ------- .. autoapisummary:: cuery.Message cuery.Prompt cuery.Response cuery.ResponseSet cuery.Chain cuery.Task cuery.Tool Functions --------- .. autoapisummary:: cuery.load_env cuery.set_env Package Contents ---------------- .. py:data:: AnyContext .. py:class:: Message(/, **data) Bases: :py:obj:`pydantic.BaseModel` Message class for chat completions. .. py:attribute:: content :type: str .. py:attribute:: role :type: str :value: 'user' .. py:method:: __rich_console__(console, options) .. py:class:: Prompt(/, **data) Bases: :py:obj:`pydantic.BaseModel` Prompt class for chat completions. This class represents a chat prompt consisting of multiple messages. Each message can have a role (e.g., user, assistant) and content. It can be constructed manually or from a configuration file or a string. In the latter case, automatically detects the required variables used by the Jinja template, if any. .. py:attribute:: messages :type: list[Message] :value: None .. py:attribute:: required :type: list[str] :value: None .. py:method:: validate_messages(messages) :classmethod: Allow init from other types. .. py:method:: check_required() .. py:method:: validate_required() Validate that all required variables are present in the prompt. .. py:method:: __iter__() So `dict(model)` works. .. py:method:: from_config(source) :classmethod: .. py:method:: from_string(p) :classmethod: Create a Prompt from a string. .. py:method:: substitute(**kwds) .. py:method:: render(with_roles = False, **kwds) Render the prompt messages into single string with the given variables. Not usually needed as Task, Tools etc. will do this automatically. .. py:method:: __rich_console__(console, options) .. 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:data:: ResponseClass .. 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:class:: Chain(*tasks) Chain multiple tasks together. The output of each task is auto-converted to a DataFrame and passed to the next task as input context. The return value of the chain is the result of successively joining each task's output DataFrame with the previous one, using the corresponding prompt's variables as join keys. .. py:attribute:: tasks :value: () .. py:method:: __call__(context = None, **kwds) :async: Run the chain of tasks sequentially. .. py:class:: Task(prompt, response, name = None, model = None, log_prompt = False, log_response = False) A task that can be executed with a prompt and a response model. Tasks can be registered by name and can be called with a context to get a response. The output is always ResponseSet that contains one Reponse for each item in the iterable context. .. py:attribute:: registry :type: dict[str, Task] .. py:attribute:: name :value: None .. py:attribute:: response .. py:attribute:: prompt .. py:attribute:: log_prompt :value: False .. py:attribute:: log_response :value: False .. py:attribute:: errors .. py:attribute:: queries .. py:method:: _select_client(model = None) .. py:method:: reset_loggers(client) Reset the error and query loggers. .. py:method:: call(context = None, model = None, **kwds) :async: Call the task with a single context item (no iteration). .. py:method:: iter(context = None, model = None, callback = None, progress_callback = None, **kwds) :async: Iterate the prompt over items in the context. This is useful when subsequent calls depend on the previous response, and you thus cannot parallelize the calls. The callback can be used to process each response as it is generated and to perform any additional actions, such as logging or updating the prompt for the next call. .. py:method:: gather(context = None, model = None, n_concurrent = 1, progress_callback = None, **kwds) :async: Gather multiple calls to the task in parallel. This is useful when the calls are independent and can be parallelized. The `n_concurrent` parameter controls how many calls can be made in parallel. .. py:method:: __call__(context = None, model = None, n_concurrent = 1, **kwds) :async: Dispatch to appropriate method (call/iter/gather) based on context and concurrency. .. py:method:: from_config(prompt, response) :classmethod: Create a Task from configuration. .. py:method:: __rich_console__(console, options) Render the task as a rich panel. .. py:class:: Tool(/, **data) Bases: :py:obj:`cuery.utils.Configurable`, :py:obj:`abc.ABC` Base class for all tools. Subclasses need to implement prompt and response models; either statically as ClassVars, or dynamically as (executable) instance properties. .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:attribute:: model :type: str :value: None The LLM provider and model to use. .. py:property:: response_model :type: cuery.response.ResponseClass :abstractmethod: Defines the response model for this tool (ClassVar or property). .. py:property:: prompt :type: cuery.prompt.Prompt :abstractmethod: Defines the prompt for this tool (ClassVar or property). .. py:property:: task :type: cuery.task.Task Create a Task instance for this tool. .. py:property:: context :type: cuery.context.AnyContext | None .. py:method:: __call__(**kwargs) :async: .. py:function:: load_env(path = PKG_DIR / '.env') Load environment variables from a .env file into a dict masking their values. .. py:function:: set_env(path = PKG_DIR / '.env', apify_secrets = False, return_vars=False) Set environment variables from a .env file and optionally set local Apify environment.