cuery

Submodules

• cuery.actors
• cuery.asy
• cuery.builder
• cuery.call
• cuery.cli
• cuery.context
• cuery.cost
• cuery.models
• cuery.pretty
• cuery.prompt
• cuery.resources
• cuery.response
• cuery.search
• cuery.seo
• cuery.server
• cuery.task
• cuery.templates
• cuery.tool
• cuery.tools
• cuery.utils

Attributes

AnyContext
ResponseClass

Classes

Message	Message class for chat completions.
Prompt	Prompt class for chat completions.
Response	Base class for all response models.
ResponseSet	A collection of responses
Chain	Chain multiple tasks together.
Task	A task that can be executed with a prompt and a response model.
Tool	Base class for all tools.

Functions

load_env([path])	Load environment variables from a .env file into a dict masking their values.
set_env([path, apify_secrets, return_vars])	Set environment variables from a .env file and optionally set local Apify environment.

Package Contents

cuery.AnyContext

class cuery.Message(/, **data)

Bases: pydantic.BaseModel

Message class for chat completions.

Parameters:

data (Any)

content: str

role: str = 'user'

__rich_console__(console, options)

Parameters:

• console (cuery.pretty.Console)

• options (cuery.pretty.ConsoleOptions)

Return type:

cuery.pretty.RenderResult

class cuery.Prompt(/, **data)

Bases: 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.

Parameters:

data (Any)

messages: list[Message] = None

required: list[str] = None

classmethod validate_messages(messages)

Allow init from other types.

Return type:

list

check_required()

validate_required()

Validate that all required variables are present in the prompt.

__iter__()

So dict(model) works.

classmethod from_config(source)

Parameters:

source (str | pathlib.Path | dict)

Return type:

Prompt

classmethod from_string(p)

Create a Prompt from a string.

Parameters:

p (str)

Return type:

Prompt

substitute(**kwds)

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.

Parameters:

with_roles (bool)

Return type:

str

__rich_console__(console, options)

Parameters:

• console (cuery.pretty.Console)

• options (cuery.pretty.ConsoleOptions)

Return type:

cuery.pretty.RenderResult

class cuery.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.ResponseClass

class cuery.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

class cuery.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.

Parameters:

tasks (list[Task])

tasks = ()

async __call__(context=None, **kwds)

Run the chain of tasks sequentially.

Parameters:

context (cuery.context.AnyContext | None)

Return type:

pandas.DataFrame

class cuery.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.

Parameters:

• prompt (str | pathlib.Path | cuery.prompt.Prompt)

• response (cuery.response.ResponseClass)

• name (str | None)

• model (str | None)

• log_prompt (bool)

• log_response (bool)

registry: dict[str, Task]

name = None

response

prompt

log_prompt = False

log_response = False

errors

queries

_select_client(model=None)

Parameters:

model (str | None)

Return type:

instructor.Instructor

reset_loggers(client)

Reset the error and query loggers.

Parameters:

client (instructor.Instructor)

Return type:

None

async call(context=None, model=None, **kwds)

Call the task with a single context item (no iteration).

Parameters:

• context (cuery.context.AnyContext | None)

• model (str | None)

Return type:

cuery.response.ResponseSet

async iter(context=None, model=None, callback=None, progress_callback=None, **kwds)

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.

Parameters:

• context (cuery.context.AnyContext | None)

• model (str | None)

• callback (collections.abc.Callable[[cuery.response.Response, cuery.prompt.Prompt, dict], None] | None)

• progress_callback (collections.abc.Callable | None)

Return type:

cuery.response.ResponseSet

async gather(context=None, model=None, n_concurrent=1, progress_callback=None, **kwds)

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.

Parameters:

• context (cuery.context.AnyContext | None)

• model (str | None)

• n_concurrent (int)

• progress_callback (collections.abc.Callable | None)

Return type:

cuery.response.ResponseSet

async __call__(context=None, model=None, n_concurrent=1, **kwds)

Dispatch to appropriate method (call/iter/gather) based on context and concurrency.

Parameters:

• context (cuery.context.AnyContext | None)

• model (str | None)

• n_concurrent (int)

Return type:

cuery.response.ResponseSet

classmethod from_config(prompt, response)

Create a Task from configuration.

Parameters:

• prompt (AnyCfg)

• response (AnyCfg)

Return type:

Task

__rich_console__(console, options)

Render the task as a rich panel.

Parameters:

• console (cuery.pretty.Console)

• options (cuery.pretty.ConsoleOptions)

Return type:

cuery.pretty.RenderResult

class cuery.Tool(/, **data)

Bases: cuery.utils.Configurable, 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.

Parameters:

data (Any)

model_config

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

model: str = None

The LLM provider and model to use.

property response_model: cuery.response.ResponseClass

Abstractmethod:

Return type:

cuery.response.ResponseClass

Defines the response model for this tool (ClassVar or property).

property prompt: cuery.prompt.Prompt

Abstractmethod:

Return type:

cuery.prompt.Prompt

Defines the prompt for this tool (ClassVar or property).

property task: cuery.task.Task

Create a Task instance for this tool.

Return type:

cuery.task.Task

property context: cuery.context.AnyContext | None

Return type:

cuery.context.AnyContext | None

async __call__(**kwargs)

Return type:

cuery.response.Response | cuery.response.ResponseSet

cuery.load_env(path=PKG_DIR / '.env')

Load environment variables from a .env file into a dict masking their values.

Parameters:

path (str | pathlib.Path)

Return type:

dict[str, Secret]

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

Parameters:

• path (str | pathlib.Path)

• apify_secrets (bool)

Return type:

dict[str, Secret] | None