cuery.seo.geo
=============

.. py:module:: cuery.seo.geo

.. autoapi-nested-parse::

   Tools to apply SEO to LLM responses.



Attributes
----------

.. autoapisummary::

   cuery.seo.geo.DEFAULT_MODELS


Classes
-------

.. autoapisummary::

   cuery.seo.geo.Brands
   cuery.seo.geo.GeoConfig


Functions
---------

.. autoapisummary::

   cuery.seo.geo.normalize_brand
   cuery.seo.geo.find_competitors
   cuery.seo.geo.generate_prompts
   cuery.seo.geo.query_ais
   cuery.seo.geo.token_rank_in_text
   cuery.seo.geo.token_pos_in_list
   cuery.seo.geo.add_brand_ranks
   cuery.seo.geo.in_strings
   cuery.seo.geo.pos_in_strings
   cuery.seo.geo.in_dicts
   cuery.seo.geo.pos_in_dicts
   cuery.seo.geo.summarize_ranks
   cuery.seo.geo.analyse


Module Contents
---------------

.. py:data:: DEFAULT_MODELS
   :value: ['openai/gpt-4.1-mini', 'google/gemini-2.5-flash']


.. py:class:: Brands(/, **data)

   Bases: :py:obj:`cuery.Response`


   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:: names
      :type:  list[str]

      List of brand names.


.. py:function:: normalize_brand(url)

   Extract the brand name (domain) from a URL.


.. py:function:: find_competitors(brands = None, sector = None, market = None, max_count = 5, model = 'openai/gpt-4.1', known = None)
   :async:


   Find a list of competitor brands using LLM with live search.


.. py:function:: generate_prompts(n, intents = None, language = 'English', sector = None, market = None, brands = None, include_brands = 'sometimes', seed_prompts = None)
   :async:


   Generate N realistic commercial/consumer search queries using an LLM meta-instruction.


.. py:function:: query_ais(prompts, models, use_search = True, search_country = None, progress_callback = None, to_pandas = True)
   :async:


   Run a list of prompts through a list of models and return a combined DataFrame.

   Gathers all model and prompt comnbinations concurrently.


.. py:function:: token_rank_in_text(text, tokens, whole_word = True)

   Find mention of first(!) token in text, returning list of (token, rank) tuples.


.. py:function:: token_pos_in_list(items, tokens, key = 'url', whole_word = True, include_none = False)

   Find mention of first token in list of strings, returning list of (token, position) tuples.


.. py:function:: add_brand_ranks(search_result, brands)

   Add brand rank columns to a search result DataFrame.


.. py:function:: in_strings(values, lst)

   Check if any of values is among list items.


.. py:function:: pos_in_strings(values, lst)

   Find first position of any of values among list items. To Do: optimize.


.. py:function:: in_dicts(values, lst, key)

   Check if any of values is in any dict under the specified key.


.. py:function:: pos_in_dicts(values, lst, key)

   Find first position of any of values in any dict under the specified key


.. py:function:: summarize_ranks(df, own, competitors, models)

   Summarize brand ranks in a results DataFrame.


.. py:class:: GeoConfig(/, **data)

   Bases: :py:obj:`cuery.utils.Configurable`


   Configuration for GEO analysis (LLM brand mentions and ranks).


   .. py:attribute:: brands
      :type:  list[str] | None
      :value: None


      List of own(!) brand names or URLs.


   .. py:attribute:: models
      :type:  list[str] | None
      :value: None


      List of LLM models to evaluate.


   .. py:attribute:: prompts
      :type:  list[str] | None
      :value: None


      List of seed prompts.


   .. py:attribute:: prompts_max
      :type:  int
      :value: 20


      Maximum number of prompts to generate using LLM.


   .. py:attribute:: prompt_intents
      :type:  list[str] | None
      :value: None


      List of user intents to focus on in generated prompts.


   .. py:attribute:: prompt_language
      :type:  str
      :value: 'English'


      Language for generated prompts.


   .. py:attribute:: brands_in_prompt
      :type:  Literal['never', 'sometimes', 'always']
      :value: 'never'


      Whether to include brand names in generated prompts.


   .. py:attribute:: competitors
      :type:  list[str] | None
      :value: None


      List of seed brand names or URLs.


   .. py:attribute:: competitors_max
      :type:  int
      :value: 10


      Maximum number of competitor brands to identify using LLM.


   .. py:attribute:: competitors_model
      :type:  str
      :value: 'openai/gpt-4.1'


      LLM model to use for competitor brand identification.


   .. py:attribute:: sector
      :type:  str | None
      :value: None


      Sector to focus on.


   .. py:attribute:: market
      :type:  str | None
      :value: None


      Market to focus on.


   .. py:attribute:: use_search
      :type:  bool
      :value: True


      Whether to enable web/live search when evaluating LLMs.


   .. py:attribute:: search_country
      :type:  str | None
      :value: None


      Country code for search localisation, e.g. 'us', 'uk', 'de '.


   .. py:method:: check_params()


.. py:function:: analyse(cfg, progress_callback = None)
   :async:


   Run a list of prompts through a list of models and return a combined DataFrame.