cuery.seo.tools =============== .. py:module:: cuery.seo.tools .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: 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 Classes ------- .. autoapisummary:: cuery.seo.tools.SerpIntentAssignment cuery.seo.tools.PurchaseProbability cuery.seo.tools.Entity cuery.seo.tools.Entities cuery.seo.tools.SerpTopicExtractor cuery.seo.tools.SerpTopicAssigner cuery.seo.tools.SerpMultiTopicAssigner cuery.seo.tools.SerpIntentAssigner cuery.seo.tools.EntityExtractor cuery.seo.tools.PurchaseProbAssigner Module Contents --------------- .. py:data:: TOPICS_PROMPT :value: '' .. py:data:: TOPIC_ASSIGNMENT_PROMPT_SYSTEM :value: '' .. py:data:: TOPIC_ASSIGNMENT_PROMPT_USER :value: '' .. py:data:: MULTI_TOPIC_ASSIGNMENT_PROMPT_SYSTEM :value: '' .. py:data:: MULTI_TOPIC_ASSIGNMENT_PROMPT_USER :value: '' .. py:data:: INTENT_ASSIGNMENT_PROMPT_SYSTEM :value: '' .. py:data:: INTENT_ASSIGNMENT_PROMPT_USER :value: '' .. py:data:: PURCHASE_PROBABILITY_PROMPT :value: '' .. py:data:: ENTITY_EXTRACTION_PROMPT :value: Multiline-String .. raw:: html
Show Value .. code-block:: python """ # 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 -%} """ .. raw:: html
.. py:class:: SerpIntentAssignment(/, **data) Bases: :py:obj:`cuery.response.Response` Intent classification for SERP keyword data. .. py:attribute:: intent :type: Literal['informational', 'navigational', 'transactional', 'commercial'] :value: None .. py:class:: PurchaseProbability(/, **data) Bases: :py:obj:`cuery.response.Response` Purchase probability score for SERP keyword data. .. py:attribute:: score :type: int :value: None .. py:class:: Entity(/, **data) Bases: :py:obj:`cuery.response.Response` Individual entity extracted from AI Overview content. .. py:attribute:: name :type: str :value: None .. py:attribute:: type :type: Literal['brand_company', 'product_service', 'technology', 'other'] :value: None .. py:class:: Entities(/, **data) Bases: :py:obj:`cuery.response.Response` Result containing all extracted entities from AI Overview data. .. py:attribute:: entities :type: list[Entity] :value: None .. py:class:: SerpTopicExtractor(/, **data) Bases: :py:obj:`cuery.utils.Configurable` Extract topics from keyword SERP data. .. py:attribute:: text_column :type: str :value: 'term' Column name in the DataFrame containing the main texts. .. py:attribute:: extra_columns :type: list[str] :value: None List of additional columns to include in the context for topic extraction. .. py:attribute:: n_topics :type: int :value: None Maximum number of top-level topics to extract (maximum 20). .. py:attribute:: n_subtopics :type: int :value: None Maximum number of subtopics per top-level topic (At least 2, maximum 10). .. py:attribute:: min_ldist :type: int :value: None Minimum Levenshtein distance between topic labels. .. py:attribute:: extra :type: str :value: '' Additional use-case specific instructions or context for the topic extraction. .. py:attribute:: max_samples :type: int :value: 500 Maximum number of samples to use for topic extraction. .. py:attribute:: model :type: str :value: None Model to use for topic extraction. .. py:attribute:: _task :type: cuery.task.Task | None :value: None .. py:method:: __call__(df, model = None, **kwds) :async: Extract topics from SERP data DataFrame. .. py:class:: SerpTopicAssigner(/, **data) Bases: :py:obj:`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. .. py:attribute:: topics :type: cuery.tools.topics.Topics | dict[str, list[str]] Topics and subtopics to use for assignment, either as a Topics object or a dict. .. py:attribute:: text_column :type: str :value: 'term' Column name in the DataFrame containing the main texts. .. py:attribute:: extra_columns :type: list[str] :value: None List of additional columns to include in the context for topic extraction. .. py:attribute:: model :type: str :value: None Model to use for topic extraction. .. py:attribute:: _task :type: cuery.task.Task | None :value: None .. py:method:: __call__(df, model = None, **kwds) :async: Assign topics for each keyword in the DataFrame. .. py:class:: SerpMultiTopicAssigner(/, **data) Bases: :py:obj:`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. .. py:attribute:: topics :type: cuery.tools.topics.Topics | dict[str, list[str]] Topics and subtopics to use for assignment, either as a Topics object or a dict. .. py:attribute:: text_column :type: str :value: 'term' Column name in the DataFrame containing the main texts. .. py:attribute:: extra_columns :type: list[str] :value: None List of additional columns to include in the context for topic extraction. .. py:attribute:: model :type: str :value: None Model to use for topic extraction. .. py:attribute:: max_labels :type: int :value: None Maximum number of topic-subtopic pairs to assign per keyword (default 3). .. py:attribute:: _task :type: cuery.task.Task | None :value: None .. py:attribute:: _response :type: cuery.response.ResponseSet | None :value: None .. py:method:: __call__(df, model = None, **kwds) :async: Assign multiple topics for each keyword in the DataFrame. .. py:class:: SerpIntentAssigner(/, **data) Bases: :py:obj:`cuery.utils.Configurable` Classify intent for keywords based on their SERP results. .. py:attribute:: text_column :type: str :value: 'term' Column name in the DataFrame containing the main texts. .. py:attribute:: extra_columns :type: list[str] :value: None List of additional columns to include in the context for topic extraction. .. py:attribute:: model :type: str :value: None Model to use for topic extraction. .. py:attribute:: _task :type: cuery.task.Task | None :value: None .. py:method:: __call__(df, model = None, **kwds) :async: Classify intent for each keyword in the DataFrame. .. py:class:: EntityExtractor(/, **data) Bases: :py:obj:`cuery.utils.Configurable` "Extract SEO-relevant entities from Google SERP AI Overview data. .. py:attribute:: columns :type: list[str] List of columns to include in the context for entity extraction. .. py:attribute:: model :type: str :value: None Model to use for topic extraction. .. py:attribute:: _task :type: cuery.task.Task | None :value: None .. py:method:: __call__(df, model = None, **kwds) :async: .. py:class:: PurchaseProbAssigner(/, **data) Bases: :py:obj:`cuery.utils.Configurable` Classify intent for keywords based on their SERP results. .. py:attribute:: text_column :type: str :value: 'term' Column name in the DataFrame containing the main texts. .. py:attribute:: extra_columns :type: list[str] :value: None List of additional columns to include in the context. .. py:attribute:: model :type: str :value: None Model to use for purchase probability estimation. .. py:attribute:: _task :type: cuery.task.Task | None :value: None .. py:method:: __call__(df, model = None, **kwds) :async: Estimate purchase probability for each keyword in the DataFrame.