BaseChatbotReaction


level_3


What is it

A BaseChatbotReaction is an abstract class that is the parent class of all custom ChatbotReaction implementations. This class must be inherited to implement the effective reactions needed when your own Chatbot has to execute its replies or autonomous reactions.

See also API doc: BaseChatbotReaction.

How to use it

Create a class that inherits BaseChatbotReaction and implements the required methods, runWith and stop.

  • runWith is aimed at executing the reaction. It is only run if the chat engine chooses this reaction after it has been replied by your chatbot implementation.
  • stop may be called by the chat engine during the execution of runWith if this answer has to be stopped for any reason (lost focus, interruption by an AutonomousReaction whose priority is higher, etc.).

Instances of this custom class will then be passed as first parameter when constructing either StandardReplyReaction or StandardAutonomousReaction objects. For further details, see: StandardReplyReaction and StandardAutonomousReaction.

Implementing constructors

The only obligation of the BaseChatbotReaction heirs constructors is to provide their parent constructor with the current QiContext, which can be obtained as parameter of these constructors.

An additional parameter of the constructor may typically be the text to be uttered as an answer.

class MyChatbotReaction(context: QiContext, answer: String) : BaseChatbotReaction(context) {

}
public class MyChatbotReaction extends BaseChatbotReaction {

    private String answer;

    protected MyChatbotReaction(QiContext context, String answer) {
        super(context);
        this.answer = answer;
    }

}

However, this pattern is not mandatory: for example the heard phrase may be passed instead if your custom BaseChatbotReaction is itself in charge of choosing an answer according to the heard phrase.

Implementing runWith

This method gathers all the actions that make up the effective reaction that will be executed upon chat engine decision. The typical implementation is the execution of a Say action, but alternative or additional actions may be used. For example, an Animation may be executed along with a Say, or alone for a mute answer.

Important

Any Say action that is run in this method must be created by using the SpeechEngine provided as parameter. Actions created via SayBuilder.with(qiContext) cannot be executed here. Use SayBuilder.with(speechEngine) instead.

In order to make your BaseChatbotReaction interruptible by the chat engine, the method should:

  • execute the actions asynchronously,
  • store the references of the Future instances that hold the asynchronous executions of the actions, in dedicated fields of your custom BaseChatbotReaction.

These futures will then be accessible to the stop method (see below). Despite the fact that actions are run asynchronously, the runWith method must wait its running actions before leaving.

Important

The runWith method should not return before all of its actions are terminated. The execution must wait for the futures to be done.

See stop.

override fun runWith(speechEngine: SpeechEngine) {

    // Build the Say action
    val say: Say = SayBuilder.with(speechEngine)
                        .withText(answer)
                        .build()

    // Run asynchronously the action and keep a reference to the future in a field
    fSay = say.async().run()

    // Do not leave the method before the actions are done
    try {
        fSay?.get()
    } catch (e: ExecutionException) {
        Log.e(TAG, "Error during Say", e)
    } catch (e: CancellationException) {
        Log.i(TAG, "Interruption during Say")
    }
}
@Override
public void runWith(SpeechEngine speechEngine) {

    // Build the Say action
    Say say = SayBuilder.with(speechEngine)
                        .withText(answer)
                        .build();

    // Run asynchronously the action and keep a reference to the future in a field
    fSay = say.async().run();

    // Do not leave the method before the actions are done
    try {
        fSay.get();
    } catch (ExecutionException e) {
        Log.e(TAG, "Error during Say", e);
    } catch (CancellationException e) {
        Log.i(TAG, "Interruption during Say");
    }
}

Implementing stop

This is the ChatbotReaction’s duty to cleanly cancel its actions upon request by the chat engine. The stop method is in charge of stopping these actions.

As stated earlier, it is important to keep references on the Future objects that hold the actions being executed, in order to make them available here.

The implementation of this method will mainly request the cancellation of these futures.

override fun stop() {
    fSay?.cancel(true)
}
@Override
public void stop() {
    if (fSay != null) {
        fSay.cancel(true);
    }
}

StandardReplyReaction

A StandardReplyReaction is the standard implementation of ReplyReaction. It defines the reaction of a chatbot when the chat has heard something and it asks its chatbots to return a reply.

The StandardReplyReaction is basically aimed at aggregating both a BaseChatbotReaction (the effective answer to be implemented) and the priority level of this reaction.

How to use it

A StandardReplyReaction must be returned by any heir class of BaseChatbot via its replyTo method. It is constructed by providing it with a BaseChatbotReaction instance along with a ReplyPriority.

  • The BaseChatbotReaction parameter, in fact a heir of this abstract class, contains the effective behavior of the reply (such as a Say or an Animation, or a combination of any actions).
  • The ReplyPriority is an enum value that qualifies the type of the reply as either NORMAL or FALLBACK. Fallback replies have a lower priority than a normal reply.
return StandardReplyReaction(
                MyChatbotReaction(qiContext, "Hi"),
                ReplyPriority.NORMAL)
return new StandardReplyReaction(
                new MyChatbotReaction(getQiContext(), "Hi"),
                ReplyPriority.NORMAL);

See also API doc: StandardReplyReaction.

StandardAutonomousReaction

A StandardAutonomousReaction is the standard implementation of AutonomousReaction.

As opposed to the ReplyReaction, the AutonomousReaction is not a reply that is requested as a reaction to an input but a “reaction” that is spontaneously emitted by the chatbot upon its willingness, whenever it wants.

How to use it

When needed, a StandardAutonomousReaction instance must be created by providing it with a BaseChatbotReaction instance along with an AutonomousReactionImportance and an AutonomousReactionValidity.

  • The BaseChatbotReaction parameter, in fact a heir of this abstract class, contains the effective behavior of the autonomous reaction (such as a Say or an Animation, or a combination of any actions).
  • The AutonomousReactionImportance is an enum value that qualifies the importance of the reply as either HIGH or LOW.
  • The AutonomousReactionValidity is an enum value that qualifies the time validity of the reply as either IMMEDIATE or DELAYABLE.

A delayable autonomous reaction can be enqueued if it is chosen by the chat whereas the immediate autonomous reaction will be discarded if it cannot be run immediately.

The autonomous reaction will be taken into account by the chat engine, by setting it on the chatbot instance.

// Create an BaseChatbotReaction heir instance
val myAutonomousChatbotReaction: MyAutonomousChatbotReaction = MyAutonomousChatbotReaction(qiContext)

// Create the AutonomousReaction
val autonomousReaction: StandardAutonomousReaction = StandardAutonomousReaction(
                                                    myAutonomousChatbotReaction,
                                                    AutonomousReactionImportance.LOW,
                                                    AutonomousReactionValidity.DELAYABLE)

// Assign the AutonomousReaction
myChatbot.setAutonomousReaction(autonomousReaction)
// Create an BaseChatbotReaction heir instance
MyAutonomousChatbotReaction myAutonomousChatbotReaction = new MyAutonomousChatbotReaction(getQiContext());

// Create the AutonomousReaction
StandardAutonomousReaction autonomousReaction = new StandardAutonomousReaction(
                                                        myAutonomousChatbotReaction,
                                                        AutonomousReactionImportance.LOW,
                                                        AutonomousReactionValidity.DELAYABLE);

// Assign the AutonomousReaction
myChatbot.setAutonomousReaction(autonomousReaction);

See also API doc: StandardAutonomousReaction.