cuery.tools.abs
===============

.. py:module:: cuery.tools.abs

.. autoapi-nested-parse::

   Higher-level API for extracting entities from texts using one-shot prompts.

   Some examples of LLM-based methods:

   - Evaluating Zero-Shot Multilingual Aspect-Based Sentiment Analysis with Large Language Models
     https://arxiv.org/abs/2412.12564
   - Structured Sentiment Analysis with Large Language Models: A Winning Solution for RuOpinionNE-2024
     https://dialogue-conf.org/wp-content/uploads/2025/04/VatolinA.104.pdf
   - https://simmering.dev/blog/absa-with-dspy/
     https://github.com/psimm/website/blob/master/blog/absa-with-dspy/configs/manual_prompt.json



Attributes
----------

.. autoapisummary::

   cuery.tools.abs.ABS_PROMPT_SYSTEM
   cuery.tools.abs.ABS_PROMPT_USER


Classes
-------

.. autoapisummary::

   cuery.tools.abs.AspectEntity
   cuery.tools.abs.AspectEntities
   cuery.tools.abs.AspectSentimentExtractor


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

.. py:data:: ABS_PROMPT_SYSTEM
   :value: ''


.. py:data:: ABS_PROMPT_USER
   :value: ''


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

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


   Represents an aspect with its sentiment and qualified phrase.


   .. py:attribute:: entity
      :type:  str

      The specific, normalized aspect being evaluated (e.g., 'ride queues', 'food prices').


   .. py:attribute:: sentiment
      :type:  Literal['positive', 'negative']

      The sentiment associated with the aspect (positive or negative).


   .. py:attribute:: reason
      :type:  str

      '<standardized_adjective> <entity>' (e.g., 'long ride queues').

      :type: The normalized aspect phrase


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


      Optional category the entity belongs to (e.g., 'food', 'service', 'pricing').


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

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


   Represents a collection of entities with their sentiments and reasons for assignment.


   .. py:attribute:: entities
      :type:  list[AspectEntity]

      A list of entities with their sentiments and reasons.


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

   Bases: :py:obj:`cuery.Tool`


   Extract entities with sentiments from texts.


   .. py:attribute:: texts
      :type:  collections.abc.Iterable[str | float | None]

      The texts to extract entities from.


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


      Further instructions from the user for the entity extraction task.


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


      Optional list of aspect categories to map entities to (e.g., ['food', 'service', 'pricing']).


   .. py:attribute:: response_model
      :type:  ClassVar[cuery.ResponseClass]

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


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


      Convert pandas NA/NaN values to None so Pydantic accepts them.



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


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


   .. py:property:: context
      :type: cuery.AnyContext