cuery.tools.flex

Flex tools (flexible tools) are tools with flexible inputs.

Instead of expecting a fixed set of attributes in input records (DataFrame rows), which are validated on execution, and mapped to specific substitutions in prompt templates, flexible tools allow data records with arbitrary attributes. Each record is essentially an object/dict with a single “record” key and a nested object as value, which in turn can have arbitrary data. Prompts are dynamically generated from Jinja templates based on the attributes present in the input records.

Submodules

• cuery.tools.flex.base
• cuery.tools.flex.classify
• cuery.tools.flex.entities
• cuery.tools.flex.generic
• cuery.tools.flex.score
• cuery.tools.flex.topics

Classes

Classifier	Zero-shot classify a data record with arbitrary attributes.
EntityExtractor	"Extract SEO-relevant entities from Google SERP AI Overview data.
Scorer	Classify intent for keywords based on their SERP results.
MultiTopicAssigner	Enforce correct multi-topic-subtopic assignment via a Pydantic model.
TopicAssigner	Assign topics to records with arbitrary attributes.
TopicExtractor	Extract topics from records with arbitrary attributes.

Package Contents

class cuery.tools.flex.Classifier(/, **data)

Bases: cuery.tools.flex.base.FlexTool

Zero-shot classify a data record with arbitrary attributes.

Parameters:

data (Any)

categories: dict[str, str]

Dictionary of category labels and their descriptions.

instructions: str = ''

Additional instructions (context) for the classification task.

property prompt: cuery.Prompt

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

Return type:

cuery.Prompt

property response_model: cuery.ResponseClass

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

Return type:

cuery.ResponseClass

class cuery.tools.flex.EntityExtractor(/, **data)

Bases: cuery.tools.flex.base.FlexTool

“Extract SEO-relevant entities from Google SERP AI Overview data.

Parameters:

data (Any)

entities: dict[str, str]

Dictionary of entity names/categories and their descriptions.

property prompt: cuery.Prompt

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

Return type:

cuery.Prompt

property response_model: cuery.ResponseClass

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

Return type:

cuery.ResponseClass

async __call__(**kwargs)

Normalize the nested input records back into individual columns in output.

Return type:

pandas.DataFrame

class cuery.tools.flex.Scorer(/, **data)

Bases: cuery.tools.flex.base.FlexTool

Classify intent for keywords based on their SERP results.

Parameters:

data (Any)

name: str

Name of the score to assign.

type: Literal['integer', 'float'] = 'float'

Whether to return the score as integer or float.

min: float

Minimum value of the score.

max: float

Maximum value of the score.

description: str

Description of the score to assign.

classmethod validate_name(name)

Ensure the name is a valid Python identifier.

Parameters:

name (str)

Return type:

str

property scorer_params: dict

Get the parameters for the score model.

Return type:

dict

property prompt: cuery.Prompt

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

Return type:

cuery.Prompt

property response_model: cuery.ResponseClass

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

Return type:

cuery.ResponseClass

class cuery.tools.flex.MultiTopicAssigner(/, **data)

Bases: TopicAssigner

Enforce correct multi-topic-subtopic assignment via a Pydantic model.

Parameters:

data (Any)

SYSTEM_PROMPT: ClassVar[str] = ''

USER_PROMPT: ClassVar[str] = ''

property response_model: cuery.ResponseClass

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

Return type:

cuery.ResponseClass

class cuery.tools.flex.TopicAssigner(/, **data)

Bases: cuery.tools.flex.base.FlexTool

Assign topics to records with arbitrary attributes.

Parameters:

data (Any)

topics: cuery.tools.topics.Topics

Topics and subtopics to use for assignment, either as a Topics object or a dict.

instructions: str = ''

Additional use-case specific instructions or context for the topic extraction.

SYSTEM_PROMPT: ClassVar[str] = ''

USER_PROMPT: ClassVar[str] = ''

classmethod validate_topics(topics)

Return type:

cuery.tools.topics.Topics

property prompt: cuery.Prompt

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

Return type:

cuery.Prompt

property response_model: cuery.ResponseClass

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

Return type:

cuery.ResponseClass

class cuery.tools.flex.TopicExtractor(/, **data)

Bases: cuery.tools.flex.base.FlexTool

Extract topics from records with arbitrary attributes.

Parameters:

data (Any)

n_topics: int = None

Approximate number of top-level topics to extract (maximum 20).

n_subtopics: int = None

Approximate number of subtopics per top-level topic (At least 2, maximum 10).

instructions: str = ''

Additional use-case specific instructions or context for the topic extraction.

min_ldist: int = None

Minimum Levenshtein distance between topic labels.

max_samples: int = 500

Maximum number of samples to use for topic extraction.

record_format: Literal['attr_wise', 'rec_wise'] = 'attr_wise'

Format of the records in the prompt.

property response_model: cuery.ResponseClass

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

Return type:

cuery.ResponseClass

property prompt: cuery.Prompt

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

Return type:

cuery.Prompt

property context: dict

Override FlexTool base implementation.

This tool is different because it doesn’t iterate over records, but rather processes them all at once to extract topics.

Return type:

dict

async __call__(**kwargs)

Normalize the nested input records back into individual columns in output.

Return type:

cuery.tools.topics.Topics