cuery.seo.brands
================

.. py:module:: cuery.seo.brands

.. autoapi-nested-parse::

   Functions to identify competitors and fetch brand information.



Attributes
----------

.. autoapisummary::

   cuery.seo.brands.DEFAULT_SEARCH_MODEL
   cuery.seo.brands.COMPETITORS_PROMPT
   cuery.seo.brands.BRAND_PROMPT


Classes
-------

.. autoapisummary::

   cuery.seo.brands.Brand
   cuery.seo.brands.Brands
   cuery.seo.brands.Product
   cuery.seo.brands.BrandInfo
   cuery.seo.brands.BrandSearchConfig


Functions
---------

.. autoapisummary::

   cuery.seo.brands.find_competitors
   cuery.seo.brands.fetch_brand_info
   cuery.seo.brands.search_brands


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

.. py:data:: DEFAULT_SEARCH_MODEL
   :value: 'openai/gpt-4.1'


.. py:data:: COMPETITORS_PROMPT
   :value: ''


   Used in first step identifying competitors of a brand.

.. py:data:: BRAND_PROMPT
   :value: ''


   Prompt to extract detailed information for a single brand.

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

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


   Identifier for a brand.


   .. py:attribute:: name
      :type:  str

      Name of the brand.


   .. py:attribute:: description
      :type:  str

      Brief description of the brand.


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

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


   List of brands.


   .. py:attribute:: brands
      :type:  list[Brand]

      List of brands.


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

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


   Represents a product or service offered by a brand.


   .. py:attribute:: name
      :type:  str

      Name of the product or service.


   .. py:attribute:: category
      :type:  str | None

      Category of the product or service.


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

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


   Represents a brand and its attributes.


   .. py:attribute:: name
      :type:  str

      Name of the brand.


   .. py:attribute:: short_name
      :type:  str | None

      Short, common/canonical name of the brand, if different from the official name. E.g.
      "Tesla" instead of "Tesla, Inc.", or "Peugoet" instead of "Automobiles Peugeot.


   .. py:attribute:: description
      :type:  str

      Description of the brand.


   .. py:attribute:: domain
      :type:  str
      :value: None


      Official website of the brand.


   .. py:attribute:: portfolio
      :type:  list[Product]

      List of products or services offered by the brand.


   .. py:attribute:: market_position
      :type:  Literal['leader', 'challenger', 'niche', 'follower']

      Market position of the brand.


   .. py:attribute:: favicon
      :type:  str | None

      URL of the brand's favicon, if available.


.. py:function:: find_competitors(brand, sector, market, strict = True, instructions = None, **kwds)
   :async:


   Identify main competitors for a given brand.


.. py:function:: fetch_brand_info(brand, **kwds)
   :async:


   Fetch detailed information for a given brand.


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

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


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


   .. py:attribute:: brand
      :type:  str | list[str]

      Initial brand or list of brands to find competitors for.


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

      Sector or industry the brand operates in, e.g. 'electric cars', 'soft drinks'.


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

      Geographical market or region, e.g. 'Spain', 'global'.


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


      Whether to exclude competitors from the same parent company.


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


      Additional instructions to guide the competitor search.


   .. py:attribute:: search_kwargs
      :type:  dict | None
      :value: None


      Additional keyword arguments to pass to the search function.


.. py:function:: search_brands(cfg, to_pandas = False)
   :async:


   Fetch detailed information for a list of brands.