Chat Editor

You must install the Pepper SDK to make the Chat Editor available in Android Studio. It is an extension of Android Studio’s text editor to help editing chat topic files.

What is a Chat Topic

A chat topic allows you to give your robot conversational skills by using a list of dialog rules that describe how to reply to what the user says. The topic and its rules are written using the QiChat language.

Creating a Chat Topic

In Android Studio, with the Pepper SDK, you can directly create a chat topic under File > New > Chat Topic.

Enter a file name and select a language.

image59

Click the Create button.

The file will be named /res/raw-<Language Code>.top.

See Supported Languages if needed.

When you open the file, the Chat Editor will be automatically used to edit it, and you can start writing QiChat script.

image60

See also Playing a Chat Topic.

QiChat

Rules

Dialog uses a list of written rules in order to manage the flow of the conversation between the human and the robot.

These rules are of two types: User rules and Proposal rules

  • A User rule links a specific user input to possible robot output.

    u: (Hello Pepper! How are you today?) Hello human! I am fine, thank you. And you?
    
  • A Proposal rule triggers a specific robot output without any user output beforehand.

    proposal: Have you seen that guy on the TV yesterday?

    u1: (yes) He was crazy, no?

    u1: (no) Really, I need to tell you.

Topics

In order to properly manage the conversation between the human and the robot, the rules are grouped by Topics.

topic: ~greetings

language: enu

u: (Hello Pepper! How are you today?) Hello human! I am fine, thank you. And you?

u: ({"Good morning"} {Pepper} did you sleep \* well) Damn no! You forgot to switch me off!

proposal: human, are you going well ?

u1: (yes) I'm so happy!

u1: (no) I'm so sad

Syntax Overview

Header keywords

Syntax For further details, see ... Comments
topic: ~name () topic  
language: en language  
concept:(conceptName) [word1 word2 wordn] concept  

Rules

Syntax For further details, see ...
u:( human_input ) robot_answer User rule
proposal: robot_input Proposal

u1:( human_input ) robot_answer

u2:( human_input ) robot_answer

u3:( human_input ) robot_answer

User subrule

Delimiters

Syntax For further details, see ... Comments
phrase Phrase delimiter: ” “  
[ word1 word2 wordN ] Choice: [ ] Partial support (for concepts only)

Special characters

Syntax For further details, see ... Comments
# Comments: #  
% Tag: %  
~ Concept call: ~ Partial support (topic calls only)

Rule functions

To ... See ... Comment
Jump to rules in the same topic

^sameProposal

^previousProposal

^nextProposal

^goto

 

QiChat Detailed Syntax

Header keywords

concept

Syntax

concept:(name) [word1 word2 "word3 word4"]

Where:

  • word1 and word2 are isolated words,
  • “word3 word4” is a phrase, i.e. a group of several words,
  • name is the name of the static concept gathering all the items in an ordered list.

Note: a static concept can contain choices and concepts.

Usage

Defines a static list of items (words and/or phrases).

Warning

Phrase means a group of word, not a sentence, be aware that any punctuation character will be automatically removed.

Static concepts are global, in other words, they are usable in different Topics.

To use a concept in a rule, see: Concept call: ~.

Example

topic: ~introduction ()
language:enu

concept:(greetings) ^rand[hi hello "hey there"]

concept:(juice) [orange apple] juice
concept:(drink) [soda ~juice]

u:(~greetings) ~greetings
u:(I want to drink something) do you want ~drink?

Execution

> hey there
hello
> I want to drink something
do you want orange juice?
> I want to drink something
do you want soda?

pronunciation

Syntax

pronunciation:(word) wordPronunciation

Changes the default speech recognition way to pronounce a word. For example “I” should be pronounced “capitalize i”.

Note: Following words pronunciation are automatically managed by dialog engine: “I” in English and “à” in French.

topic: ~play()
language: enu

pronunciation:(I) [i]
u:(I want to play) let's play

language

Syntax

language: enu

Usage

Defines the language of the topic.

A topic can have the same name in different languages. For example in English “cars” topic and cars topic in French. In a language, a topic mush have a unique name.

For further details see: Supported Languages.

topic

Syntax

topic: ~name ()

Usage

Defines the name to the topic. A topic must have one name and can have only one.

The name of a topic must be unique in a given language.

Related functions

None.

Rules

User rule

Syntax

u:(Input) Answer
u:(Input)
  Answer

Where:

  • Input is the human input,
  • Answer is the robot output.

Indentation and blank lines are ignored.

Usage

Makes the robot say or do the Answer when he hears the Input.

Effect

If the human input matches, then the topic that contains the rule takes the focus.

Conditions

The topic containing the user rules must be active to answer.

Example

topic: ~introduction ()
language:enu

u:(hello) hello human
u:(how are you) I feel tired, my batteries are low

Execution

> hello
hello human
> how are you
I feel tired, my batteries are low

Related functions

User subrule

Syntax

u:(input1) answer
   u1:(input2) answer
   u1:(input3) answer
     u2:(input4) answer
        u3:(input5) answer
     u2:(input6) answer

proposal: sentence
   u1:(input7) answer
   u1:(input8) answer

Where u1:, u2: and u3: are user subrules.

The indentation underlines the relationship between a rule and its subrules.

Usage

Allows creating several conversational contexts, making some rules active if and only if a main User rule or Proposal has previously matched.

Activation / deactivation

At first, the User rules and Proposal are activated while subrules are deactivated.

  • If a User rule matches and if it has a scope, its subrules (u1:) are active; the other User rule remain active.
  • If one of the u1: subrule matches, then its own subrules (u2:) are active, and the first-level rules (u1:) are deactivated.
  • At anytime, if another User rule matches, then the previous subrules are deactivated.
Scope

The subrules of a rule are called the scope of the rule.

_images/dialog_scope.png

Example

topic: ~introduction ()
language:enu

u:(talk about animals) do you have a cat or a dog?
   u1:(dog) is it a big dog?
     u2:(yes) make sure he has enough space to run
     u2:(no) it is so cute
   u1:(cat) do you live in the countryside?
     u2:(yes) does your cat goes outside?
        u3:(yes) does he hunt mouses?
     u2:(no) i hope your flat is big enough
   u1:(none) neither do I

u:(talk about sport) what a good idea

proposal: Do you want to talk about sport?
   u1:(yes) Cool
   u1:(no) OK

Execution

> talk about animals
do you have a cat or a dog?
> I have a cat
do you live in the countryside?
> no
I hope your flat is big enough
> Now I want to talk about sport
what a good idea

Related functions

None.

Proposal

Syntax

proposal: sentence

Where:

  • sentence is a robot output.

Usage

While rules are triggered by a human input, to be said, a Proposal needs to be triggered with one of the topic progression functions:

Activation/deactivation

When a proposal is said, it cannot be said again during the chat topic run.

Conditions

The topic that contains the user rules must be active.

Example

topic: ~introduction ()
language: enu

proposal: take a cup and fill it with milk
proposal: add 3 strawberries
proposal: add some vanilla ice cream
proposal: close the cup with the lid and shake it
proposal: you did it! you can enjoy your milkshake

u:(I want a milkshake)
    ok, let's do it.
    follow my instruction and say next when you are ready for the next step.

u:(next) ^nextProposal

Execution

> I want a milkshake
ok, let's do it.
follow my instruction and say next when you are ready for the next step.
>next
take a cup and fill it with milk
>next
add 3 strawberries
>next
add some vanilla ice cream
>next
close the cup with the lid and shake it
>next
you did it! you can enjoy your milkshake
>next
(no answer)

Related functions

Delimiters

Choice: [ ]

Syntax

u:([word1 word2 wordn]) answer
u:(input) [word1 word2 wordn]
u:([word1 word2 wordn]) [word1 word2 wordn] human

Where:

  • word1 to wordn are words that could substitute with each other.

Warning

Never write [{xxx}] the dialog engine will accept it but this rule will always match, whatever you write inside.

Usage

  • In a human input: creates one rule accepting variations.
  • In a robot output: if the rule is triggered several times, the words will be used sequentially in order to create varying responses.

Example

topic: ~introduction ()
language:enu

u:([hi hello]) [hello hi] human

The human input can be ‘hello’ or ‘hi’. The robot output can be ‘hello human’ or ‘hi human’. By default answers are in a sequential order.

Execution

> hello
hello human
> hello
hi human
> hi
hello human

Related functions

None.


Phrase delimiter: ” “

Syntax

u:([word1 "phrase 1"]) ["phrase 2" "phrase 3"]

Where:

  • word1 is a word that could substitute with phrase 1.
  • phrase 2 and phrase 3 are phrases used sequentially in order to create varying responses.

Usage

Allows you to use a phrase instead of a single word in a choice []. Example

topic: ~introduction ()
language:enu

u:(["hello how are you" "hello are you OK"]) ["I am fine" "I am OK"]

Execution

> hello are you OK
I am fine
> hello how are you
I am OK

Special characters

Comments: #

Syntax

# comment

Comment is defined by character #. All the characters following # in the same line will be ignored.


Tag: %

Syntax

proposal: %tag sentence
u:(input) %tag answer

Usage

Allows you to identify one or several proposal(s) or rule(s) by a tag. Tags can be active or inactive. If a tag is inactive, then the sentence is false and won’t be said.

Example

topic: ~introduction ()
language:enu

proposal: %weather what is the weather like today?
u:(tell me a story) %story ok, I'll tell you the story of the three bears

Related functions


Concept call: ~

Syntax

u:(~conceptName) answer
u:(input) answer ~conceptName

Usage

A Concept can be used in both human input and robot output to replace a list of item previously declared.

  • In human input, the rule will match if any of the items of the list is recognized.
  • In robot output, one item of the list will be said. Each call of the rule will sequentially call another item of the list.

Conditions

the Concept must be previously defined.

To define a concept, see: concept.

Example

topic: ~introduction ()
language:enu

   concept:(want) [want need desire like]
   concept:(soda) [lemonade "ginger beer"]
   concept:(other-drink [juice milk]
   concept:(drink) [~soda ~other-drink]

   u: (what do you do) I can help people with drinks

   u:(I ~want to drink) what you ~want to drink?
        u1:(* _~drink) do you want me to go get you some?

Execution

> what do you do
I can help people with drinks
> I need to drink
what do you want to drink?
> I want ginger beer
do you want me to go get you some?

Related functions

None.


Forbidden characters

Forbidden characters in human input

  • Do not use any punctuation mark.
  • Type only the words to be recognized.
  • like all Special characters, $ is a reserved word, type dollar instead.
  • Apostrophe ( ‘ ) is allowed but not the typographic apostrophe ( ’ ).
  • Japanese only: speech recognition does not support Fullwidth numbers [0 1 2 3 4 5 6 7 8 9]. Use Halfwidth numbers [0 1 2 3 4 5 6 7 8 9] instead.

Example

topic: ~introduction ()
language:enu

u:(Have you got a dollar for me?) No, sorry, I have no pocket!
u:(I'm rich) Good for you. Are you happy?

Forbidden characters in robot output

  • like all Special characters, $ is a reserved word, type dollar instead.
  • Apostrophe ( ‘ ) is allowed but not the typographic apostrophe ( ’ ).

Example

topic: ~introduction ()
language:enu

u:(Have you got a dollar for me?) No, sorry, I have no pocket!
u:(I'm rich) Good for you. Are you happy?

Rule functions and properties

^goto

Syntax

u:(input1) %tag Answer
u:(input2) ^goto(tag)

Usage

The ^goto function allows you to jump to a robot output (in a user rule or an active proposal) that contains a specific tag.

That means that if two human inputs are equivalent, you can use goto to jump to a common robot output.

Example

topic: ~introduction ()
language:enu

u:(Hello, how are you?) hello ^goto(how)
u:(How you are?) %how I'm fine

Execution

> how are you
I'm fine
> hello how are you
hello I'm fine

Related functions


^nextProposal

Syntax

u:(input) answer ^nextProposal

Usage

The function ^nextProposal indicates which active proposal gets the focus first, among all active proposals in the chat topic.

Example

topic: ~introduction ()
language: enu

u:(hi) hello ^nextProposal

proposal: how are you?
  u1:(I'm fine) cool!
  u1:(I'm tired) oh, you should take a nap

proposal: again!

Execution

> hi
hello how are you?
> I'm tired
oh, you should take a nap
> hi
hello again!

Related functions


^previousProposal

Syntax

u:(input) answer ^previousProposal

Usage

The function ^previousProposal repeats the second-last Proposal that was previously output.

Example

topic: ~introduction ()
language: enu

u:(hi) hello ^nextProposal

proposal: how are you?
  u1:(I'm fine) cool!
  u1:(I'm tired) oh ^nextProposal

proposal: do you want some tea?
   u1:(yes) I'm bringing you a cup of tea.
   u1:(no) okay, ^nextProposal

proposal: what about some coffee?
   u1:(yes) I'm bringing you a cup of coffee.
   u1:(no) okay, maybe you should just take a nap.

u:(what did you say before) ^previousProposal

Execution

> hi
hello how are you?
> I'm tired
do you want some tea?
> no
OK, what about coffee?
> what did you say before
do you want some tea?

Related functions


^sameProposal

Syntax

u:(input) answer ^sameProposal

Usage

The function ^sameProposal repeats the last proposal said in the same topic.

Best practices

When using ^sameProposal, always make the robot say something like ‘OK I’ll repeat’, ‘No problem,’ so that the user knows what to expect. It also makes the repetition clearer.

Example

topic: ~introduction ()
language: enu

u:(hi) hello ^nextProposal

proposal: how are you?
  u1:(I'm fine) cool!
  u1:(I'm tired) oh ^nextProposal

proposal: do you want some coffee?
   u1:(yes) I'm bringing you a cup of coffee.
   u1:(no) okay, maybe you should just take a nap.
   u1:(can you repeat please) Ok I'll repeat. ^sameProposal

Execution

> hi
hello how are you?
> I'm tired
do you want some coffee?
> can you repeat please
Ok I'll repeat. Do you want some coffee?
> yes
I'm bringing you a cup of coffee.

Related functions


Playing a Chat Topic

The Pepper SDK already sets everything up for you to be able to play chat topics in your Android project, including importing the required library. Please note that you can :ref`setup your project manually<qichat_player_setup>` too.

  1. Supposing you have the following topic file: res/raw-en/baseball.top
  2. It is recommended to store a QiChatPlayer instance in your Activity:
public class TestActivity extends Activity
{
    QiChatPlayer qiChatPlayer = null;
    ...
}
  1. Instantiate the QiChatPlayer using your activity as a Context. You will need a QiChatPlayerListener to be called back when the QiChat service is connected to. Only then you can load the topic file into the player.
protected void onStart(Intent intent) {
    // Instantiate a QiChatPlayer
    qiChatPlayer = new QiChatPlayer(this);

    // Register QiChatPlayer listener.
    qiChatPlayer.init(new QiChatPlayerListener() {

        /**
         * Complete to connected to QiChatPlayerService
         */
        @Override
        public void onQiChatPlayerServiceConnected() {
            // Load the topic file.
            qiChatPlayer.loadTopicFile("baseball");
        }

        /**
         * Complete to load the topic file.
         */
        @Override
        public void onLoadCompleted() {
           // The player is ready to play!
           qiChatPlayer.startTalk();
        }

        /**
         * Error handler
         * @param error Error code
         */
        @Override
        public void onError(int error) {
            ...
        }
    });
}

protected void onPause() {
    super.onPause();
    qiChatPlayer.stopTalk();
}

@Override
protected void onDestroy() {
    super.onDestroy();
    qiChatPlayer.destroy();
}

Note

You can have only one instance of QiChatPlayer per Application.

Setting up your project manually

Add the following maven repository http://android.aldebaran.com/sdk/maven and add the library to your build.gradle file:

dependencies {
    compile 'com.aldebaran:qichatplayer:1.0.1'
}