[text analytics] opinion mining support

sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## 1.0.1 (Unreleased)
 
+**New features**
+
+- Adding support for the service's v3.1-preview.1 API. The default API version is v3.0, but pass in "v3.1-preview.1" as the value for `api_version` when creating your client.
+- We now have added support for aspect based sentiment analysis. To use this feature, you need to make sure you are using the service's
+v3.1-preview.1 API. To get this support pass `show_aspects` as True when calling the `analyze_sentiment` endpoint
 
 ## 1.0.0 (2020-06-09)
 

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/__init__.py

@@ -25,7 +25,9 @@
     LinkedEntityMatch,
     TextDocumentBatchStatistics,
     SentenceSentiment,
-    SentimentConfidenceScores
+    SentimentConfidenceScores,
+    AspectSentiment,
+    OpinionSentiment
 )
 
 __all__ = [
@@ -48,7 +50,9 @@
     'LinkedEntityMatch',
     'TextDocumentBatchStatistics',
     'SentenceSentiment',
-    'SentimentConfidenceScores'
+    'SentimentConfidenceScores',
+    'AspectSentiment',
+    'OpinionSentiment'
 ]
 
 __version__ = VERSION

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_base_client.py

@@ -8,7 +8,7 @@
 from azure.core.credentials import AzureKeyCredential
 from ._policies import TextAnalyticsResponseHookPolicy
 from ._user_agent import USER_AGENT
-from ._multiapi import load_generated_api
+from ._multiapi import load_generated_api, ApiVersion
 
 def _authentication_policy(credential):
     authentication_policy = None
@@ -26,8 +26,8 @@ def _authentication_policy(credential):
 
 class TextAnalyticsClientBase(object):
     def __init__(self, endpoint, credential, **kwargs):
-        api_version = kwargs.pop("api_version", None)
-        _TextAnalyticsClient = load_generated_api(api_version)
+        self._api_version = kwargs.pop("api_version", ApiVersion.V3_0)
+        _TextAnalyticsClient = load_generated_api(self._api_version)
         self._client = _TextAnalyticsClient(
             endpoint=endpoint,
             credential=credential,

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_models.py

@@ -3,9 +3,11 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-
-from ._generated.v3_0.models._models import LanguageInput
-from ._generated.v3_0.models._models import MultiLanguageInput
+import re
+from ._generated.v3_0.models._models import (
+    LanguageInput,
+    MultiLanguageInput
+)
 
 
 class DictMixin(object):
@@ -635,19 +637,31 @@ class SentenceSentiment(DictMixin):
         and 1 for the sentence for all labels.
     :vartype confidence_scores:
         ~azure.ai.textanalytics.SentimentConfidenceScores
+    :ivar aspects: The list of aspects in this sentence. An aspect is a
+        key attribute of a product or a service. For example in
+        "The food at Hotel Foo is good", "food" is an aspect of
+        "Hotel Foo". This property is only returned if `show_aspects` is
+        set to True in the call to `analyze_sentiment`
+    :vartype aspects:
+        list[~azure.ai.textanalytics.AspectSentiment]
     """
 
     def __init__(self, **kwargs):
         self.text = kwargs.get("text", None)
         self.sentiment = kwargs.get("sentiment", None)
         self.confidence_scores = kwargs.get("confidence_scores", None)
+        self.aspects = kwargs.get("aspects", None)
 
     @classmethod
-    def _from_generated(cls, sentence):
+    def _from_generated(cls, sentence, results):
         return cls(
             text=sentence.text,
             sentiment=sentence.sentiment,
             confidence_scores=SentimentConfidenceScores._from_generated(sentence.confidence_scores),  # pylint: disable=protected-access
+            aspects=(
+                [AspectSentiment._from_generated(aspect, results) for aspect in sentence.aspects]  # pylint: disable=protected-access
+                if hasattr(sentence, "aspects") else None
+            )
         )
 
     def __repr__(self):
@@ -658,6 +672,126 @@ def __repr__(self):
         )[:1024]
 
 
+class AspectSentiment(DictMixin):
+    """AspectSentiment contains the related opinions, predicted sentiment,
+    confidence scores and other information about an aspect of a product.
+    An aspect of a product/service is a key component of that product/service.
+    For example in "The food at Hotel Foo is good", "food" is an aspect of
+    "Hotel Foo".
+
+    :ivar str text: The aspect text.
+    :ivar str sentiment: The predicted Sentiment for the aspect. Possible values
+        include 'positive', 'mixed', and 'negative'.
+    :ivar confidence_scores: The sentiment confidence score between 0
+        and 1 for the aspect for 'positive' and 'negative' labels. It's score
+        for 'neutral' will always be 0
+    :vartype confidence_scores:
+        ~azure.ai.textanalytics.SentimentConfidenceScores
+    :ivar opinions: All of the opinions related to this aspect.
+    :vartype opinions: list[~azure.ai.textanalytics.OpinionSentiment]
+    :ivar int offset: The aspect offset from the start of the sentence.
+    :ivar int length: The length of the aspect.
+    """
+
+    def __init__(self, **kwargs):
+        self.text = kwargs.get("text", None)
+        self.sentiment = kwargs.get("sentiment", None)
+        self.confidence_scores = kwargs.get("confidence_scores", None)
+        self.opinions = kwargs.get("opinions", None)
+        self.offset = kwargs.get("offset", None)
+        self.length = kwargs.get("length", None)
+
+    @staticmethod
+    def _get_opinions(relations, results):
+        if not relations:
+            return []
+        opinion_relations = [r.ref for r in relations if r.relation_type == "opinion"]
+        opinions = []
+        for opinion_relation in opinion_relations:
+            nums = [int(s) for s in re.findall(r"\d+", opinion_relation)]
+            document_index = nums[0]
+            sentence_index = nums[1]
+            opinion_index = nums[2]
+            opinions.append(
+                results[document_index].sentences[sentence_index].opinions[opinion_index]
+            )
+        return opinions
+
+
+    @classmethod
+    def _from_generated(cls, aspect, results):
+        return cls(
+            text=aspect.text,
+            sentiment=aspect.sentiment,
+            confidence_scores=SentimentConfidenceScores._from_generated(aspect.confidence_scores),  # pylint: disable=protected-access
+            opinions=[
+                OpinionSentiment._from_generated(opinion) for opinion in cls._get_opinions(aspect.relations, results)  # pylint: disable=protected-access
+            ],
+            offset=aspect.offset,
+            length=aspect.length
+        )
+
+    def __repr__(self):
+        return "AspectSentiment(text={}, sentiment={}, confidence_scores={}, opinions={}, offset={}, length={})".format(
+            self.text,
+            self.sentiment,
+            repr(self.confidence_scores),
+            repr(self.opinions),
+            self.offset,
+            self.length
+        )[:1024]
+
+
+class OpinionSentiment(DictMixin):
+    """OpinionSentiment contains the predicted sentiment,
+    confidence scores and other information about an opinion of an aspect.
+    For example, in the sentence "The food is good", the opinion of the
+    aspect 'food' is 'good'.
+
+    :ivar str text: The opinion text.
+    :ivar str sentiment: The predicted Sentiment for the opinion. Possible values
+        include 'positive', 'mixed', and 'negative'.
+    :ivar confidence_scores: The sentiment confidence score between 0
+        and 1 for the opinion for 'positive' and 'negative' labels. It's score
+        for 'neutral' will always be 0
+    :vartype confidence_scores:
+        ~azure.ai.textanalytics.SentimentConfidenceScores
+    :ivar int offset: The opinion offset from the start of the sentence.
+    :ivar int length: The length of the opinion.
+    :ivar bool is_negated: Whether the opinion is negated. For example, in
+        "The food is not good", the opinion "good" is negated.
+    """
+
+    def __init__(self, **kwargs):
+        self.text = kwargs.get("text", None)
+        self.sentiment = kwargs.get("sentiment", None)
+        self.confidence_scores = kwargs.get("confidence_scores", None)
+        self.offset = kwargs.get("offset", None)
+        self.length = kwargs.get("length", None)
+        self.is_negated = kwargs.get("is_negated", None)
+
+    @classmethod
+    def _from_generated(cls, opinion):
+        return cls(
+            text=opinion.text,
+            sentiment=opinion.sentiment,
+            confidence_scores=SentimentConfidenceScores._from_generated(opinion.confidence_scores),  # pylint: disable=protected-access
+            offset=opinion.offset,
+            length=opinion.length,
+            is_negated=opinion.is_negated
+        )
+
+    def __repr__(self):
+        return "OpinionSentiment(text={}, sentiment={}, confidence_scores={}, offset={}, length={}, is_negated={})".format(
+            self.text,
+            self.sentiment,
+            repr(self.confidence_scores),
+            self.offset,
+            self.length,
+            self.is_negated
+        )[:1024]
+
+
 class SentimentConfidenceScores(DictMixin):
     """The confidence scores (Softmax scores) between 0 and 1.
     Higher values indicate higher confidence.
@@ -671,15 +805,15 @@ class SentimentConfidenceScores(DictMixin):
     """
 
     def __init__(self, **kwargs):
-        self.positive = kwargs.get('positive', None)
-        self.neutral = kwargs.get('neutral', None)
-        self.negative = kwargs.get('negative', None)
+        self.positive = kwargs.get('positive', 0.0)
+        self.neutral = kwargs.get('neutral', 0.0)
+        self.negative = kwargs.get('negative', 0.0)
 
     @classmethod
     def _from_generated(cls, score):
         return cls(
             positive=score.positive,
-            neutral=score.neutral,
+            neutral=score.neutral if hasattr(score, "netural") else 0.0,
             negative=score.negative
         )
 

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_multiapi.py

@@ -13,15 +13,11 @@ class ApiVersion(str, Enum):
     """Text Analytics API versions supported by this package"""
 
     #: this is the default version
-    V3_1_preview_1 = "v3.1-preview.1"
+    V3_1_PREVIEW_1 = "v3.1-preview.1"
     V3_0 = "v3.0"
 
 
-DEFAULT_VERSION = ApiVersion.V3_0
-
-
 def load_generated_api(api_version, aio=False):
-    api_version = api_version or DEFAULT_VERSION
     try:
         # api_version could be a string; map it to an instance of ApiVersion
         # (this is a no-op if it's already an instance of ApiVersion)
@@ -33,7 +29,7 @@ def load_generated_api(api_version, aio=False):
             + "Supported versions: {}".format(", ".join(v.value for v in ApiVersion))
         )
 
-    if api_version == ApiVersion.V3_1_preview_1:
+    if api_version == ApiVersion.V3_1_PREVIEW_1:
         if aio:
             from ._generated.v3_1_preview_1.aio import TextAnalyticsClient
         else:

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_response_handlers.py

@@ -106,14 +106,14 @@ def wrapper(response, obj, response_headers):  # pylint: disable=unused-argument
             if hasattr(item, "error"):
                 results[idx] = DocumentError(id=item.id, error=TextAnalyticsError._from_generated(item.error))  # pylint: disable=protected-access
             else:
-                results[idx] = func(item)
+                results[idx] = func(item, results)
         return results
 
     return wrapper
 
 
 @prepare_result
-def language_result(language):
+def language_result(language, results):  # pylint: disable=unused-argument
     return DetectLanguageResult(
         id=language.id,
         primary_language=DetectedLanguage._from_generated(language.detected_language),  # pylint: disable=protected-access
@@ -123,7 +123,7 @@ def language_result(language):
 
 
 @prepare_result
-def entities_result(entity):
+def entities_result(entity, results):  # pylint: disable=unused-argument
     return RecognizeEntitiesResult(
         id=entity.id,
         entities=[CategorizedEntity._from_generated(e) for e in entity.entities],  # pylint: disable=protected-access
@@ -133,7 +133,7 @@ def entities_result(entity):
 
 
 @prepare_result
-def linked_entities_result(entity):
+def linked_entities_result(entity, results):  # pylint: disable=unused-argument
     return RecognizeLinkedEntitiesResult(
         id=entity.id,
         entities=[LinkedEntity._from_generated(e) for e in entity.entities],  # pylint: disable=protected-access
@@ -143,7 +143,7 @@ def linked_entities_result(entity):
 
 
 @prepare_result
-def key_phrases_result(phrases):
+def key_phrases_result(phrases, results):  # pylint: disable=unused-argument
     return ExtractKeyPhrasesResult(
         id=phrases.id,
         key_phrases=phrases.key_phrases,
@@ -153,12 +153,12 @@ def key_phrases_result(phrases):
 
 
 @prepare_result
-def sentiment_result(sentiment):
+def sentiment_result(sentiment, results):
     return AnalyzeSentimentResult(
         id=sentiment.id,
         sentiment=sentiment.sentiment,
         warnings=[TextAnalyticsWarning._from_generated(w) for w in sentiment.warnings],  # pylint: disable=protected-access
         statistics=TextDocumentStatistics._from_generated(sentiment.statistics),  # pylint: disable=protected-access
         confidence_scores=SentimentConfidenceScores._from_generated(sentiment.confidence_scores),  # pylint: disable=protected-access
-        sentences=[SentenceSentiment._from_generated(s) for s in sentiment.sentences],  # pylint: disable=protected-access
+        sentences=[SentenceSentiment._from_generated(s, results) for s in sentiment.sentences],  # pylint: disable=protected-access
     )

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_text_analytics_client.py

@@ -378,6 +378,12 @@ def analyze_sentiment(  # type: ignore
         :type documents:
             list[str] or list[~azure.ai.textanalytics.TextDocumentInput] or
             list[dict[str, str]]
+        :keyword bool show_aspects: Whether to conduct more granular analysis around the aspects of
+            a product or service (also known as aspect-based sentiment analysis). For example,
+            in the review "The food at Hotel Foo is good", "food" is an aspect of "Hotel Foo", and
+            setting `show_aspects` to True will go into the sentiment and opinions of "food".
+            If set to true, the returned :class:`~azure.ai.textanalytics.SentenceSentiment` objects
+            will have property `aspects` containing the result of this analysis.
         :keyword str language: The 2 letter ISO 639-1 representation of language for the
             entire batch. For example, use "en" for English; "es" for Spanish etc.
             If not set, uses "en" for English as default. Per-document language will
@@ -408,6 +414,15 @@ def analyze_sentiment(  # type: ignore
         docs = _validate_batch_input(documents, "language", language)
         model_version = kwargs.pop("model_version", None)
         show_stats = kwargs.pop("show_stats", False)
+        show_aspects = kwargs.pop("show_aspects", None)
+
+        if show_aspects is not None:
+            if self._api_version == "v3.0":
+                raise TypeError(
+                    "Parameter 'show_aspects' is only added for API version v3.1-preview.1 and up"
+                )
+            if self._api_version == "v3.1-preview.1":
+                kwargs.update({"opinion_mining": show_aspects})
         try:
             return self._client.sentiment(
                 documents=docs,

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/aio/_base_client_async.py

@@ -8,7 +8,7 @@
 from azure.core.pipeline.policies import AzureKeyCredentialPolicy
 from ._policies_async import AsyncTextAnalyticsResponseHookPolicy
 from .._user_agent import USER_AGENT
-from .._multiapi import load_generated_api
+from .._multiapi import load_generated_api, ApiVersion
 
 
 def _authentication_policy(credential):
@@ -27,8 +27,8 @@ def _authentication_policy(credential):
 
 class AsyncTextAnalyticsClientBase(object):
     def __init__(self, endpoint, credential, **kwargs):
-        api_version = kwargs.pop("api_version", None)
-        _TextAnalyticsClient = load_generated_api(api_version, aio=True)
+        self._api_version = kwargs.pop("api_version", ApiVersion.V3_0)
+        _TextAnalyticsClient = load_generated_api(self._api_version, aio=True)
         self._client = _TextAnalyticsClient(
             endpoint=endpoint,
             credential=credential,