AISDK-197: Add sentiment analysis client (#91)

Author: Kyle Bridburg

HISTORY.rst

@@ -97,6 +97,7 @@ History
 
 2.16.0
 ------------------
+* Add sentiment analysis client
 * Add source_config and notification_config job options to support customer provided urls with authentication headers
 * Deprecate media_url option, replace with source_config
 * Deprecate callback_url option, replace with notification_config

examples/sentiment_analysis_example.py

@@ -0,0 +1,99 @@
+"""Copyright 2022 REV
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import time
+from rev_ai import sentiment_analysis_client, apiclient
+from rev_ai.models import SentimentValue
+
+
+# String containing your access token
+access_token = "<your_access_token>"
+
+# Create your api client
+client = sentiment_analysis_client.SentimentAnalysisClient(access_token)
+
+# Submit a job with whatever text you want by changing this input
+text = "An umbrella or parasol is a folding canopy supported by wooden or metal ribs that is  \
+    usually mounted on a wooden, metal, or plastic pole. It is designed to protect a person \
+    against rain or sunlight. The term umbrella is traditionally used when protecting oneself from \
+    rain, with parasol used when protecting oneself from sunlight, though the terms continue to be \
+    used interchangeably. Often the difference is the material used for the canopy; some parasols \
+    are not waterproof, and some umbrellas are transparent. Umbrella canopies may be made of \
+    fabric or flexible plastic. There are also combinations of parasol and umbrella that are \
+    called en-tout-cas (French for 'in any case')."
+job = client.submit_job_from_text(text,
+                                  metadata=None,
+                                  callback_url=None,
+                                  delete_after_seconds=None,
+                                  language=None,
+                                  notification_config=None)
+
+# If you'd like to submit the transcript of an existing transcription job you can do so by
+# uncommenting the lines below
+#
+# async_job_id = "your_job_id"
+# async_api_client = apiclient.RevAiAPIClient(access_token)
+# transcript = async_api_client.get_transcript_object(async_job_id)
+# transcript_json = transcript
+# job = client.submit_job_from_transcript(transcript_json,
+#                                         metadata=None,
+#                                         callback_url=None,
+#                                         delete_after_seconds=None,
+#                                         language=None,
+#                                         notification_config=None)
+
+print("Submitted Job")
+
+while True:
+    # Obtains details of a job in json format
+    job_details = client.get_job_details(job.id)
+    status = job_details.status.name
+
+    print("Job Status : {}".format(status))
+
+    # Checks if the job has been completed. Please note that this is not the recommended way
+    # of getting job status in a real application. For recommended methods of getting job status
+    # please see our documentation on callback_urls here:
+    # https://docs.rev.ai/resources/tutorials/get-started-api-webhooks/
+    if status == "IN_PROGRESS":
+        time.sleep(2)
+        continue
+
+    elif status == "FAILED":
+        print("Job Failed : {}".format(job_details.failure_detail))
+        break
+
+    if status == "COMPLETED":
+        # Getting a list of current sentiment analysis jobs connected with your account
+        # The optional parameters limits the length of the list.
+        # starting_after is a job id which causes the removal of
+        # all jobs from the list which were created before that job
+        list_of_jobs = client.get_list_of_jobs(limit=None, starting_after=None)
+
+        # obtain a list of topics and their scores for the job
+        result = client.get_result_object(job.id, filter_for=None)
+        remove_none_elements = lambda dictionary: {k: v for k, v in dictionary.items() if v}
+        print([remove_none_elements(message.__dict__) for message in result.messages])
+
+        break
+
+# Use the objects however you please
+# Once you are done with the job, you can delete it.
+# NOTE : This will PERMANENTLY DELETE all data related to a job. Exercise only
+# if you're sure you want to delete the job.
+#
+# client.delete_job(job.id)
+
+print("Job Submission and Collection Finished.")

examples/topic_extraction_example.py

@@ -24,7 +24,14 @@
 client = topic_extraction_client.TopicExtractionClient(access_token)
 
 # Submit a job with whatever text you want by changing this input
-text = "<input_text>"
+text = "An umbrella or parasol is a folding canopy supported by wooden or metal ribs that is  \
+    usually mounted on a wooden, metal, or plastic pole. It is designed to protect a person \
+    against rain or sunlight. The term umbrella is traditionally used when protecting oneself from \
+    rain, with parasol used when protecting oneself from sunlight, though the terms continue to be \
+    used interchangeably. Often the difference is the material used for the canopy; some parasols \
+    are not waterproof, and some umbrellas are transparent. Umbrella canopies may be made of \
+    fabric or flexible plastic. There are also combinations of parasol and umbrella that are \
+    called en-tout-cas (French for 'in any case')."
 job = client.submit_job_from_text(text,
                                   metadata=None,
                                   delete_after_seconds=None,
@@ -41,7 +48,8 @@
 # job = client.submit_job_from_transcript(transcript_json,
 #                                         metadata=None,
 #                                         delete_after_seconds=None,
-#                                         language=None)
+#                                         language=None,
+#                                         notification_config=None)
 
 print("Submitted Job")
 

src/rev_ai/__init__.py

@@ -5,4 +5,5 @@
 
 from .models import Job, JobStatus, Account, Transcript, Monologue, Element, MediaConfig, \
     CaptionType, CustomVocabulary, TopicExtractionJob, TopicExtractionResult, Topic, Informant, \
-    SpeakerName, LanguageIdentificationJob, LanguageIdentificationResult, LanguageConfidence
+    SpeakerName, LanguageIdentificationJob, LanguageIdentificationResult, LanguageConfidence, \
+    SentimentAnalysisResult, SentimentValue, SentimentMessage, SentimentAnalysisJob, CustomerUrlData

src/rev_ai/models/__init__.py

@@ -5,5 +5,7 @@
 from .streaming import MediaConfig
 from .asynchronous import Job, JobStatus, Account, Transcript, Monologue, Element, CaptionType, \
     SpeakerName
-from .insights import TopicExtractionJob, TopicExtractionResult, Topic, Informant
+from .insights import TopicExtractionJob, TopicExtractionResult, Topic, Informant, \
+    SentimentAnalysisResult, SentimentValue, SentimentMessage, SentimentAnalysisJob
 from .language_id import LanguageIdentificationJob, LanguageIdentificationResult, LanguageConfidence
+from .customer_url_data import CustomerUrlData

src/rev_ai/models/insights/__init__.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
 """Insights Models"""
 
-from .topic_extraction import TopicExtractionJob, TopicExtractionResult, Topic, Informant
+from .sentiment_analysis import SentimentAnalysisResult, SentimentValue, SentimentMessage, \
+    SentimentAnalysisJob
+from .topic_extraction import TopicExtractionResult, Topic, Informant, TopicExtractionJob

src/rev_ai/models/insights/sentiment_analysis/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""Sentiment Analysis Models"""
+
+from .sentiment_analysis_job import SentimentAnalysisJob
+from .sentiment_analysis_result import SentimentAnalysisResult, SentimentMessage
+from .sentiment_value import SentimentValue

src/rev_ai/models/insights/sentiment_analysis/sentiment_analysis_job.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""Job model"""
+
+from ...asynchronous.job_status import JobStatus
+
+
+class SentimentAnalysisJob:
+    def __init__(
+            self, id_, created_on, status,
+            completed_on=None,
+            callback_url=None,
+            metadata=None,
+            failure=None,
+            failure_detail=None,
+            word_count=None,
+            delete_after_seconds=None):
+        """
+        :param id_: unique id of job
+        :param created_on: date and time at which this job was started
+        :param status: current job status 'IN_PROGRESS', 'COMPLETED',
+                       or 'FAILED'
+        :param completed_on: date and time at which this job finished
+                             being processed
+        :param callback_url: callback_url if provided
+        :param metadata: metadata if provided
+        :param failure: type of failure if job has failed
+        :param failure_detail: more detailed failure message if job has failed
+        :param word_count: count of words in job
+        :param delete_after_seconds: seconds before deletion if provided
+        """
+
+        self.id = id_
+        self.created_on = created_on
+        self.status = status
+        self.completed_on = completed_on
+        self.callback_url = callback_url,
+        self.metadata = metadata
+        self.failure = failure
+        self.failure_detail = failure_detail
+        self.delete_after_seconds = delete_after_seconds
+        self.word_count = word_count
+
+    def __eq__(self, other):
+        """Override default equality operator"""
+        if isinstance(other, self.__class__):
+            return self.__dict__ == other.__dict__
+        return False
+
+    @classmethod
+    def from_json(cls, json):
+        """Alternate constructor used for parsing json"""
+        return cls(
+            json['id'],
+            json['created_on'],
+            JobStatus.from_string(json['status']),
+            completed_on=json.get('completed_on'),
+            callback_url=json.get('callback_url'),
+            metadata=json.get('metadata'),
+            failure=json.get('failure'),
+            failure_detail=json.get('failure_detail'),
+            word_count=json.get('word_count'),
+            delete_after_seconds=json.get('delete_after_seconds'),
+        )

src/rev_ai/models/insights/sentiment_analysis/sentiment_analysis_result.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""Sentiment analysis result model"""
+
+from .sentiment_value import SentimentValue
+
+
+class SentimentAnalysisResult:
+    def __init__(self, messages):
+        """
+        :param messages: list of sentimented statements from the input in order of how they appeared
+                         in the input.
+        """
+        self.messages = messages
+
+    def __eq__(self, other):
+        """Override default equality operator"""
+        if isinstance(other, self.__class__):
+            return all(a == b for a, b in zip(self.messages, other.messages))
+        return False
+
+    @classmethod
+    def from_json(cls, json):
+        """Alternate constructor used for parsing json"""
+        return cls([SentimentMessage.from_json(message) for message in json.get('messages', [])])
+
+
+class SentimentMessage:
+    def __init__(self, content, score, sentiment, timestamp=None, end_timestamp=None,
+                 offset=None, length=None):
+        """
+        :param content: content of the informant, pulled from input
+        :param score: Sentimental “score” of the content. Numbers less than 0 indicate a negative
+                      (sad, angry) sentiment. Numbers above 0 indicate positive (joyful, happy)
+                      sentiment
+        :param: sentiment: Overall detected sentiment of the content, based off of score
+        :param timestamp: time at which this element starts if input was json
+        :param end_timestamp: time at which this element ends if input was json
+        :param offset: Character index at which the content started in the source transcript,
+                       excludes invisible characters
+        :param length: Length of the content in characters, excludes invisible characters
+        """
+        self.content = content
+        self.score = score
+        self.sentiment = sentiment
+        self.timestamp = timestamp
+        self.end_timestamp = end_timestamp
+        self.offset = offset
+        self.length = length
+
+    def __eq__(self, other):
+        """Override default equality operator"""
+        if isinstance(other, self.__class__):
+            return self.__dict__ == other.__dict__
+        return False
+
+    @classmethod
+    def from_json(cls, json):
+        """Alternate constructor used for parsing json"""
+        return cls(
+            json['content'],
+            json['score'],
+            SentimentValue.from_string(json['sentiment']),
+            json.get('ts'),
+            json.get('end_ts'),
+            json.get('offset'),
+            json.get('length'))

src/rev_ai/models/insights/sentiment_analysis/sentiment_value.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""Enum for possible sentiments"""
+
+from enum import Enum
+
+
+class SentimentValue(Enum):
+    POSITIVE = 1
+    NEGATIVE = 2
+    NEUTRAL = 3
+
+    def __str__(self):
+        return self.name.lower()
+
+    @classmethod
+    def from_string(cls, status):
+        return cls[status.upper()]