cuery.seo.funnels
=================

.. py:module:: cuery.seo.funnels


Attributes
----------

.. autoapisummary::

   cuery.seo.funnels.FUNNEL
   cuery.seo.funnels.CUSTOM_PROMPT
   cuery.seo.funnels.EXAMPLES_PROMPT
   cuery.seo.funnels.PARAPHRASE_PROMPT


Classes
-------

.. autoapisummary::

   cuery.seo.funnels.FunnelCategory
   cuery.seo.funnels.FunnelStage
   cuery.seo.funnels.Funnel
   cuery.seo.funnels.Seeds
   cuery.seo.funnels.KeywordFunnel


Functions
---------

.. autoapisummary::

   cuery.seo.funnels.custom
   cuery.seo.funnels.flatten_level
   cuery.seo.funnels.paraphrase


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

.. py:data:: FUNNEL

.. py:data:: CUSTOM_PROMPT
   :value: ''


   A prompts to customize the generic marketing funnel and categories,
   given a specific industrial sector and geographic market.

.. py:data:: EXAMPLES_PROMPT
   :value: ''


.. py:data:: PARAPHRASE_PROMPT
   :value: ''


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

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


   A category of Google search keywords within a marketing funnel stage.


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

      The name of a keyword category within a marketing funnel stage.


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

      A brief description of the category and its purpose.


   .. py:attribute:: keyword_patterns
      :type:  list[str]

      Common keyword patterns or phrases associated with this category.


   .. py:attribute:: intent
      :type:  str

      The primary search intent for this category
      (e.g., Informational, Commercial, Transactional, Navigational).


   .. py:attribute:: examples
      :type:  list[str]

      Example Google search keywords that fit within this category.


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

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


   A stage in the marketing funnel containing multiple keyword categories.


   .. py:attribute:: stage
      :type:  str

      The name of the marketing funnel stage (e.g., Awareness, Consideration).


   .. py:attribute:: goal
      :type:  str

      The primary goal or objective of this funnel stage.


   .. py:attribute:: categories
      :type:  list[FunnelCategory]

      A list of keyword categories within this funnel stage.


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

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


   A complete marketing funnel with multiple stages.


   .. py:attribute:: stages
      :type:  list[FunnelStage]


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

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


   A list of seed keywords for a particular funnel category.


   .. py:attribute:: seeds
      :type:  list[str]
      :value: None



.. py:function:: custom(sector, language, country = 'global', model = 'openai/gpt-4.1', funnel = FUNNEL)
   :async:


   "Customize a generic marketing funnel to a specific sector and market using an LLM.


.. py:function:: flatten_level(stage, category)

   Merge stage and category dictionaries into a single flat dictionary.


.. py:function:: paraphrase(phrase)
   :async:


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

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


   A class representing a marketing funnel with stages and categories.


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

      Brand or list of brands to contextualize the funnel.


   .. py:attribute:: sector
      :type:  str

      Sector to contextualize the funnel.


   .. py:attribute:: language
      :type:  str

      Language for keyword generation as 2-letter ISO code, e.g. 'en'.


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


      Country to contextualize the funnel as 2-letter ISO code, e.g. 'us'.


   .. py:attribute:: max_ideas_per_category
      :type:  int
      :value: 10000


      Maximum number of keyword ideas to generate per category.


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


      List of stage names to filter keyword generation. If None, all stages are processed.


   .. py:attribute:: funnel
      :type:  list[dict]

      List of funnel stages and their categories.


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


      Additional keywords to always include in the keyword generation.


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


      Whether to include the sector as a keyword seed.


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


      Whether to include the brand(s) as keyword seeds.


   .. py:method:: deep_copy_funnel(v)
      :classmethod:


      Deep copy the funnel to prevent mutation of the original.



   .. py:method:: __len__()

      Return the total number of categories across all stages in the funnel.



   .. py:method:: __iter__()

      Make the Funnel iterable over all stages and categories.



   .. py:method:: enumerate()

      Make the Funnel iterable over all stages and categories, yielding index and item.



   .. py:method:: get(state, category)

      Get funnel subcategory details by stage index or name and category name.



   .. py:method:: __getitem__(key)

      Get funnel subcategory details by stage index or name and category name.



   .. py:method:: to_pandas()

      Convert the funnel structure to a pandas DataFrame for analysis.



   .. py:method:: _seeds(level)
      :async:


      Generate initial keyword examples for a particular funnel stage and category



   .. py:method:: seed()
      :async:


      Generate initial keyword seeds for all funnel categories.



   .. py:method:: iter_seeds()

      Iterate over all funnel categories and their seed keywords.



   .. py:method:: explicit_seeds()
      :async:



   .. py:method:: keyword_ideas(seed, stage = None, category = None)

      Generate keyword ideas for a given seed keyword using Google Keyword Planner.



   .. py:method:: keywords()
      :async:


      Generate keyword ideas for all funnel categories using the seed keywords.



   .. py:method:: hierarchy()

      Return the funnel hierarchy as a nested dictionary.



   .. py:method:: categorize(keywords)
      :async:


      Categorize keywords into funnel stages and categories using an LLM.



   .. py:method:: run()
      :async:


      Customize the funnel and generate keyword ideas.