cuery.tools.flex.topics
=======================

.. py:module:: cuery.tools.flex.topics

.. autoapi-nested-parse::

   Tools that work with flexible input contexts.

   I.e. these tools accept context objects that have arbitrary numbers and types of fields.
   The Jinja prompt templates auto-convert these fields into the appropriate format for LLMs.



Attributes
----------

.. autoapisummary::

   cuery.tools.flex.topics.TOPICS_PROMPT
   cuery.tools.flex.topics.LABEL_PROMPT_SYSTEM
   cuery.tools.flex.topics.LABEL_PROMPT_USER
   cuery.tools.flex.topics.MULTI_LABEL_PROMPT_SYSTEM
   cuery.tools.flex.topics.MULTI_LABEL_PROMPT_USER


Classes
-------

.. autoapisummary::

   cuery.tools.flex.topics.TopicExtractor
   cuery.tools.flex.topics.TopicAssigner
   cuery.tools.flex.topics.MultiTopicAssigner


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

.. py:data:: TOPICS_PROMPT
   :value: ''


.. py:data:: LABEL_PROMPT_SYSTEM
   :value: ''


.. py:data:: LABEL_PROMPT_USER
   :value: ''


.. py:data:: MULTI_LABEL_PROMPT_SYSTEM
   :value: ''


.. py:data:: MULTI_LABEL_PROMPT_USER
   :value: ''


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

   Bases: :py:obj:`cuery.tools.flex.base.FlexTool`


   Extract topics from records with arbitrary attributes.


   .. py:attribute:: n_topics
      :type:  int
      :value: None


      Approximate number of top-level topics to extract (maximum 20).


   .. py:attribute:: n_subtopics
      :type:  int
      :value: None


      Approximate number of subtopics per top-level topic (At least 2, maximum 10).


   .. py:attribute:: instructions
      :type:  str
      :value: ''


      Additional use-case specific instructions or context for the topic extraction.


   .. py:attribute:: min_ldist
      :type:  int
      :value: None


      Minimum Levenshtein distance between topic labels.


   .. py:attribute:: max_samples
      :type:  int
      :value: 500


      Maximum number of samples to use for topic extraction.


   .. py:attribute:: record_format
      :type:  Literal['attr_wise', 'rec_wise']
      :value: 'attr_wise'


      Format of the records in the prompt.


   .. py:property:: response_model
      :type: cuery.ResponseClass


      Defines the response model for this tool (ClassVar or property).


   .. py:property:: prompt
      :type: cuery.Prompt


      Defines the prompt for this tool (ClassVar or property).


   .. py:property:: context
      :type: dict


      Override FlexTool base implementation.

      This tool is different because it doesn't iterate over records,
      but rather processes them all at once to extract topics.


   .. py:method:: __call__(**kwargs)
      :async:


      Normalize the nested input records back into individual columns in output.



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

   Bases: :py:obj:`cuery.tools.flex.base.FlexTool`


   Assign topics to records with arbitrary attributes.


   .. py:attribute:: topics
      :type:  cuery.tools.topics.Topics

      Topics and subtopics to use for assignment, either as a Topics object or a dict.


   .. py:attribute:: instructions
      :type:  str
      :value: ''


      Additional use-case specific instructions or context for the topic extraction.


   .. py:attribute:: SYSTEM_PROMPT
      :type:  ClassVar[str]
      :value: ''



   .. py:attribute:: USER_PROMPT
      :type:  ClassVar[str]
      :value: ''



   .. py:method:: validate_topics(topics)
      :classmethod:



   .. py:property:: prompt
      :type: cuery.Prompt


      Defines the prompt for this tool (ClassVar or property).


   .. py:property:: response_model
      :type: cuery.ResponseClass


      Defines the response model for this tool (ClassVar or property).


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

   Bases: :py:obj:`TopicAssigner`


   Enforce correct multi-topic-subtopic assignment via a Pydantic model.


   .. py:attribute:: SYSTEM_PROMPT
      :type:  ClassVar[str]
      :value: ''



   .. py:attribute:: USER_PROMPT
      :type:  ClassVar[str]
      :value: ''



   .. py:property:: response_model
      :type: cuery.ResponseClass


      Defines the response model for this tool (ClassVar or property).