Codeq NLP API Tutorial

Part 6. Speech Acts, Questions & Tasks

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:

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,
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:

  • KEY: speechact

Output Labels

  • Statement: Utterances that simply convey information and/or opinions.
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:

  • KEY: question

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.
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.

More information about the Task Classifier can be found here:

  • KEY: task

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
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.

Senior Computational Linguist at Codeq