Codeq NLP API Tutorial

Part 6. Speech Acts, Questions & Tasks

7 min readDec 1, 2020

In this tutorial we will detail modules from Codeq’s NLP API that can be used to classify speech acts and questions, and detect tasks from texts.

Previous content of this series of tutorials can be found here:

The complete list of modules in the Codeq NLP API can be found here:

Codeq NLP API Documentation

The first thing you need to do before start using Codeq’s NLP API is to sign up to generate a User ID and User Key…

api.codeq.com

Define a NLP pipeline and analyze a text

The workflow to call the NLP API includes creating an instance of the Codeq Client using your API credentials, defining a pipeline with some NLP annotators and using the client to analyze a text. The output is a Document object containing a list of Sentences with the analysis of the annotarors. As usual, to print a quick overview of the results, you can use the method document.pretty_print(). For each annotator we will detail:

the keyword (KEY) used to call the annotator,
the attribute (ATTR) where the output is stored,
the Output Labels of the annotators.

from codeq_nlp_api import CodeqClientclient = CodeqClient(user_id="USER_ID", user_key="USER_KEY")pipe = [
    "speechact", "question", "task",
]
text = "I have an urgent meeting this morning with the risk mitigations guys. Could you please send me the report you showed me yesterday about our emerging markets positions as soon as possible? Also, could you please tell Katie to come by my office this afternoon? I'd like to get her take on how next year's estimates are looking right now. By the way and before I forget, I promise I'll let you know about the birthday party this weekend asap."

document = client.analyze(text, pipeline=pipe)

print(document.pretty_print())

Speech Act Classifier

The goal of the Speech Act Classifier is to analyze and classify sentences from a pragmatic point of view and according to their illocutionary force, that is, their intention, purpose or effect within human conversations.

You can learn more about Codeq’s Speech Act Classifier here:

Courier’s Speech Act Classifier: Modeling Intent

As pointed out in a previous post, conversational emails are defined as text-based asynchronous conversations. Drawing…

medium.com

KEY: speechact
ATTR: sentence.speech_acts

Output Labels

Statement: Utterances that simply convey information and/or opinions.
Command/Request: Utterances that compel someone to perform an action.
Desire/Need: Utterances that convey a desire or need that an agent has.
Commitment: Utterances that express the commitment to perform an action by an agent.
Question: Utterances that ask for information and/or opinion.
Other: Any other utterance that doesn’t fit in the previously defined classes.

pipe = [
    "speechact"
]text = "I have an urgent meeting this morning with the risk mitigations guys. Could you please send me the report you showed me yesterday about our emerging markets positions as soon as possible? Also, could you please tell Katie to come by my office this afternoon? I'd like to get her take on how next year's estimates are looking right now. By the way and before I forget, I promise I'll let you know about the birthday party this weekend asap."document = client.analyze(text, pipeline=pipe)

for sentence in document.sentences:
    speech_acts = sentence.speech_acts
    print(sentence.raw_sentence)
    print("speech_acts: %s\n" % speech_acts)# Output:
# 
# I have an urgent meeting this morning with the risk mitigations guys.
# speech_acts: ['Statement']
# 
# Could you please send me the report you showed me yesterday about our emerging markets positions as soon as possible?
# speech_acts: ['Command/Request']
# 
# Also, could you please tell Katie to come by my office this afternoon?
# speech_acts: ['Command/Request']
# 
# I'd like to get her take on how next year's estimates are looking right now.
# speech_acts: ['Desire/Need']
# 
# By the way and before I forget, I promise I'll let you know about the birthday party this weekend asap.
# speech_acts: ['Commitment']

Question Classifier

This annotator extends the output of the Speech Act Classifier by providing finer-grained information about sentences that were previously classified as questions.

Here you can find more details about the Question Classifier:

Courier’s Question Classifier

As an extension to our speech act classifier that we introduced in a previous blog post, in Courier we have implemented…

medium.com

KEY: question
ATTR: sentence.question_types

Output Labels

Yes/No question. Sentences that contain the pragmatic, syntactic and prosodic markings of a yes-no question, i.e. subject-inversion, question intonation.
Wh question. Sentences that contain interrogative questions with subject-inversion.
Open-ended question. Questions without any syntactic constraint on the form of the answer (for example, as opposed to Yes/No questions.)
Or question. Questions that employ the conjunction “or” to offer two or more choices as answers.
Declarative question. Sentences that function pragmatically as questions but that do not have a “question form” and/or subject-verb inversion.
Tag question. These questions consists of a statement and a ‘tag’ which seeks confirmation of the statement.
Rhetorical question. Sentences that are syntactically expressed as questions but are not questions from a pragmatic or semantic point of view.
Task question. Questions sentences that were previously classified as Command/Request by the Speech Act Classifier.

pipe = [
    "speechact", "question"
]text = "Hi, how are you? Do you think you can finish the project today? If so, could you please send me the results?"

document = client.analyze(text, pipeline=pipe)

for sentence in document.sentences:
    print()
    print(sentence.raw_sentence)
    speech_acts = sentence.speech_acts
    if 'Question' in speech_acts or 'Command/Request' in speech_acts:
        print(sentence.speech_acts)
        print(sentence.question_types)# Output:
# 
# Hi, how are you?
# speech_acts: ['Question']
# question_types: ['Open-ended question']
# 
# Do you think you can finish the project today?
# speech_acts: ['Question']
# question_types: ['Yes/No question']
#
# If so, could you please send me the results?
# speech_acts: ['Command/Request']
# question_types: ['Task question']

Task Classifier

The Task Classifier annotator can be used to identify requests that place an obligation on a recipient, usually within the context of textual conversations. The workflow of the Task Classifier includes three substeps:

Task Classification: detect if a sentence is a task or not.
Task Sub-classification: if a sentence is detected as a task, a subclassifier is applied to detect a list of possible actions predicted as necessary to address a request (for example writing back an email, making a call or opening your calendar).
Task Priority: if a sentence is detected as a task, a set of heuristics is applied to detect the priority of the task, inferred from resolved dates or urgency patterns found in the sentence.

More information about the Task Classifier can be found here:

Courier’s Task Extraction

An hybrid NLP approach for detecting requests in emails

rodrigo-alarcon.medium.com

KEY: task
ATTR: sentence.is_task
ATTR: sentence.task_subclassification
ATTR: sentence.task_actions

The attribute sentence.is_task is a boolean indicating if the sentence is classified as task or not.

The attribute sentence.task_subclassification is a list of labels indicating the possible actions predicted as necessary to address a task.

The attribute sentence.task_actions is a dictionary that extends the task_subclassification by providing information about deadlines, priority status, priority patterns and resolved task dates.

Output labels (sentence.task_subclassification):

email
call
open_attachment
open_browser
text
deadline
open_calendar

pipe = [
    "speechact", "question", "task"
]text = "I have an urgent meeting this morning with the risk mitigations guys. Could you please send me the report you showed me yesterday about our emerging markets positions as soon as possible? Also, could you please tell Katie to come by my office this afternoon? I'd like to get her take on how next year's estimates are looking right now. By the way and before I forget, I promise I'll let you know about the birthday party this weekend asap."

document = client.analyze(text, pipeline=pipe)for sentence in document.sentences:
    print()
    print(sentence.raw_sentence)
    is_task = sentence.is_task
    print("- is_task: %s" % is_task)
    if is_task:
        task_subclassification = sentence.task_subclassification
        task_actions = sentence.task_actions
        print("- subclassification: %s" % task_subclassification)
        if task_actions:
            print(">>", task_actions.keys())
            has_deadline = task_actions['has_deadline']
            priority = task_actions['priority']
            task_dates = task_actions['task_dates']
            print("- has_deadline: %s" % has_deadline)
            print("- priority: %s" % priority)
            if task_dates:
                for date in task_dates:
                    print("- task_date:")
                    date_pattern = date['ne_term']
                    resolved_date = date['resolved_date']
                    remaining_days = date['remaining_days']
                    print("- - date_pattern: %s" % date_pattern)
                    print("- - resolved_date: %s" % resolved_date)
                    print("- - remaining_days: %s" % remaining_days)# Output:
#
# I have an urgent meeting this morning with the risk mitigations guys.
# - is_task: 0
# 
# Could you please send me the report you showed me yesterday about our emerging markets positions as soon as possible?
# - is_task: 1
# - task_labels: ['email', 'deadline']
# - has_deadline: 1
# - priority: urgent
# 
# Also, could you please tell Katie to come by my office this afternoon?
# - is_task: 1
# - task_labels: ['call']
# - has_deadline: 0
# - priority: urgent
# - task_date:
# - - date_pattern: afternoon
# - - resolved_date: 2020-11-16T15:00:00
# - - remaining_days: 0
# 
# I'd like to get her take on how next year's estimates are looking right now.
# - is_task: 0
# 
# By the way and before I forget, I promise I'll let you know about the birthday party this weekend asap.
# - is_task: 0

Wrap up

In this tutorial we described three annotators of the Codeq NLP API: Speech Act Classifier, Question Classifier and Task Classifier. The code below summarizes the pipeline names to call each annotator and the variables used to store their output:

Take a look at our documentation to learn more about the NLP tools we provide.
Do you need inspiration? Go to our use case demos and see how you can integrate different tools.
In our NLP demos section you can also try our tools and find examples of the output of each module.