cuery.seo.tools#

AI-powered SERP topic extraction and search intent classification.

This module provides sophisticated analysis tools for Search Engine Results Page (SERP) data using large language models. It performs two-level analysis to extract meaningful insights from SERP content: hierarchical topic extraction that identifies themes and subtopics from aggregated SERP data, and search intent classification that categorizes keywords into informational, navigational, transactional, or commercial intent types.

The analysis leverages domain patterns, page titles, and breadcrumb navigation to understand the semantic meaning and commercial context behind search queries. This enables SEO professionals to better understand search landscapes, identify content opportunities, and optimize for user intent. The module uses configurable language models and provides structured outputs suitable for further analysis and reporting.

Attributes#

`TOPICS_PROMPT`
`TOPIC_ASSIGNMENT_PROMPT_SYSTEM`
`TOPIC_ASSIGNMENT_PROMPT_USER`
`MULTI_TOPIC_ASSIGNMENT_PROMPT_SYSTEM`
`MULTI_TOPIC_ASSIGNMENT_PROMPT_USER`
`INTENT_ASSIGNMENT_PROMPT_SYSTEM`
`INTENT_ASSIGNMENT_PROMPT_USER`
`PURCHASE_PROBABILITY_PROMPT`
`ENTITY_EXTRACTION_PROMPT`

Classes#

`SerpIntentAssignment`	Intent classification for SERP keyword data.
`PurchaseProbability`	Purchase probability score for SERP keyword data.
`Entity`	Individual entity extracted from AI Overview content.
`Entities`	Result containing all extracted entities from AI Overview data.
`SerpTopicExtractor`	Extract topics from keyword SERP data.
`SerpTopicAssigner`	Assign topics for keywords based on their SERP results.
`SerpMultiTopicAssigner`	Assign multiple topics for keywords based on their SERP results.
`SerpIntentAssigner`	Classify intent for keywords based on their SERP results.
`EntityExtractor`	"Extract SEO-relevant entities from Google SERP AI Overview data.
`PurchaseProbAssigner`	Classify intent for keywords based on their SERP results.

Module Contents#

cuery.seo.tools.TOPICS_PROMPT = ''#

cuery.seo.tools.TOPIC_ASSIGNMENT_PROMPT_SYSTEM = ''#

cuery.seo.tools.TOPIC_ASSIGNMENT_PROMPT_USER = ''#

cuery.seo.tools.MULTI_TOPIC_ASSIGNMENT_PROMPT_SYSTEM = ''#

cuery.seo.tools.MULTI_TOPIC_ASSIGNMENT_PROMPT_USER = ''#

cuery.seo.tools.INTENT_ASSIGNMENT_PROMPT_SYSTEM = ''#

cuery.seo.tools.INTENT_ASSIGNMENT_PROMPT_USER = ''#

cuery.seo.tools.PURCHASE_PROBABILITY_PROMPT = ''#

cuery.seo.tools.ENTITY_EXTRACTION_PROMPT = Multiline-String#

Show Value

"""
# Instructions
From the "AI Overview Data" section below, which contains AI overviews from Google SERPs,
extract entities that are relevant to SEO analysis. Focus on identifying 3 kinds of entities:

- brand mentions and company names (label "brand_company")
- products and services (label "product_service")
- technologies and tools (label "technology")

Categorize other entities as "other".

For each entity, provide the entity name/text as it appears, and the type/category of entity.
Pay special attention to URLs, which may refer to brands, companies or
products. Ensure to report the names of entities always in lowercase and singular form, even if
they appear in plural or uppercase in the source titles, to avoid inconsistencies in the output.

# AI Overview Data

{% for attr_name in aio.keys() | list -%}

## {{ attr_name }}

{% if aio[attr_name] is iterable and aio[attr_name] is not string -%}
{%- for item in aio[attr_name] -%}
- {{ item | trim }}

{% endfor %}
{% elif aio[attr_name] -%}
{{ aio[attr_name] }}
{% endif %}

{% endfor -%}
"""

class cuery.seo.tools.SerpIntentAssignment(/, **data)#

Bases: cuery.response.Response

Intent classification for SERP keyword data.

Parameters:: data (Any)

intent: Literal['informational', 'navigational', 'transactional', 'commercial'] = None#

class cuery.seo.tools.PurchaseProbability(/, **data)#

Bases: cuery.response.Response

Purchase probability score for SERP keyword data.

Parameters:: data (Any)

score: int = None#

class cuery.seo.tools.Entity(/, **data)#

Bases: cuery.response.Response

Individual entity extracted from AI Overview content.

Parameters:: data (Any)

name: str = None#

type: Literal['brand_company', 'product_service', 'technology', 'other'] = None#

class cuery.seo.tools.Entities(/, **data)#

Bases: cuery.response.Response

Result containing all extracted entities from AI Overview data.

Parameters:: data (Any)

entities: list[Entity] = None#

class cuery.seo.tools.SerpTopicExtractor(/, **data)#

Bases: cuery.utils.Configurable

Extract topics from keyword SERP data.

Parameters:: data (Any)

text_column: str = 'term'#: Column name in the DataFrame containing the main texts.

extra_columns: list[str] = None#: List of additional columns to include in the context for topic extraction.

n_topics: int = None#: Maximum number of top-level topics to extract (maximum 20).

n_subtopics: int = None#: Maximum number of subtopics per top-level topic (At least 2, maximum 10).

min_ldist: int = None#: Minimum Levenshtein distance between topic labels.

extra: str = ''#: Additional use-case specific instructions or context for the topic extraction.

max_samples: int = 500#: Maximum number of samples to use for topic extraction.

model: str = None#: Model to use for topic extraction.

_task: cuery.task.Task | None = None#

async __call__(df, model=None, **kwds)#

Extract topics from SERP data DataFrame.

Parameters:

df (pandas.DataFrame)
model (str | None)

Return type:

cuery.tools.topics.Topics

class cuery.seo.tools.SerpTopicAssigner(/, **data)#

Bases: cuery.utils.Configurable

Assign topics for keywords based on their SERP results.

Returns a DataFrame containing the configured input columns along with the assigned topics and subtopics.

Parameters:: data (Any)

topics: cuery.tools.topics.Topics | dict[str, list[str]]#: Topics and subtopics to use for assignment, either as a Topics object or a dict.

text_column: str = 'term'#: Column name in the DataFrame containing the main texts.

extra_columns: list[str] = None#: List of additional columns to include in the context for topic extraction.

model: str = None#: Model to use for topic extraction.

_task: cuery.task.Task | None = None#

async __call__(df, model=None, **kwds)#

Assign topics for each keyword in the DataFrame.

Parameters:

df (pandas.DataFrame)
model (str | None)

Return type:

pandas.DataFrame

class cuery.seo.tools.SerpMultiTopicAssigner(/, **data)#

Bases: cuery.utils.Configurable

Assign multiple topics for keywords based on their SERP results.

Returns a DataFrame containing the configured input columns along with the assigned topics and subtopics. Unlike SerpTopicAssigner, this class can assign multiple topic-subtopic pairs to each keyword when SERP data covers multiple themes.

Parameters:: data (Any)

topics: cuery.tools.topics.Topics | dict[str, list[str]]#: Topics and subtopics to use for assignment, either as a Topics object or a dict.

text_column: str = 'term'#: Column name in the DataFrame containing the main texts.

extra_columns: list[str] = None#: List of additional columns to include in the context for topic extraction.

model: str = None#: Model to use for topic extraction.

max_labels: int = None#: Maximum number of topic-subtopic pairs to assign per keyword (default 3).

_task: cuery.task.Task | None = None#

_response: cuery.response.ResponseSet | None = None#

async __call__(df, model=None, **kwds)#

Assign multiple topics for each keyword in the DataFrame.

Parameters:

df (pandas.DataFrame)
model (str | None)

Return type:

pandas.DataFrame

class cuery.seo.tools.SerpIntentAssigner(/, **data)#

Bases: cuery.utils.Configurable

Classify intent for keywords based on their SERP results.

Parameters:: data (Any)

text_column: str = 'term'#: Column name in the DataFrame containing the main texts.

extra_columns: list[str] = None#: List of additional columns to include in the context for topic extraction.

model: str = None#: Model to use for topic extraction.

_task: cuery.task.Task | None = None#

async __call__(df, model=None, **kwds)#

Classify intent for each keyword in the DataFrame.

Parameters:

df (pandas.DataFrame)
model (str | None)

Return type:

pandas.DataFrame

class cuery.seo.tools.EntityExtractor(/, **data)#

Bases: cuery.utils.Configurable

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

Parameters:: data (Any)

columns: list[str]#: List of columns to include in the context for entity extraction.

model: str = None#: Model to use for topic extraction.

_task: cuery.task.Task | None = None#

async __call__(df, model=None, **kwds)#

Parameters:

df (pandas.DataFrame)
model (str | None)

Return type:

cuery.response.ResponseSet

class cuery.seo.tools.PurchaseProbAssigner(/, **data)#

Bases: cuery.utils.Configurable

Classify intent for keywords based on their SERP results.

Parameters:: data (Any)

text_column: str = 'term'#: Column name in the DataFrame containing the main texts.

extra_columns: list[str] = None#: List of additional columns to include in the context.

model: str = None#: Model to use for purchase probability estimation.

_task: cuery.task.Task | None = None#

async __call__(df, model=None, **kwds)#

Estimate purchase probability for each keyword in the DataFrame.

Parameters:

df (pandas.DataFrame)
model (str | None)

Return type:

pandas.DataFrame

cuery.seo.tools#

Attributes#

Classes#

Module Contents#

This Page