SUSI.AI

A powerful feature of SUSI is, that it can use external API’s to learn new skills. The generic syntax used here is:

Question string
!console:constant answer string + answer variable
{
 "url" : "API to be called",
 "path" : "path from where answer will be fetched"
}
eol

I will try to explain this syntax with the help of some useful examples. Let’s start with a very basic example:

I want SUSI to be able to answer questions like “What is the date today?”.

Let’s try to tackle this step by step. As we can infer from the above-written syntax, to teach SUSI a skill involving external API call, we need to be clear about five things namely:

1. Question string i.e. “What is the date today?” (in this case).
2. Constant answer string i.e. “The date today is ”
3. The API to be called i.e. “http://calapi.inadiutorium.cz/api/v0/en/calendars/default/today”
4. The path which contains our answer.

When we visit this API url, we get the result as follows:

{
  "date":"2017-05-16",
  "season":"easter",
  "season_week":5,
  "celebrations":[
    {
      "title":"",
      "colour":"white",
      "rank":"ferial",
      "rank_num":3.13
    }
  ],
  "weekday":"tuesday"
}

The whole JSON object is represented with the ‘$’ sign. As date is a property of this object, so date can be accessed with “$.date” – this string is referred to as the path.

5.  The last one is the answer variable.

We can see that the result of API url contains many “key:value” pairs. Answer variable is the value of the last key variable(i.e. date) referred in path string. This value is stored in a variable named $object$.

So our answer variable turns out to be $object$.   

Now, as we have all the five things ready with us, we can make our SUSI skill:

What is the date today?
!console:$object$
{
  “url”:“http://calapi.inadiutorium.cz/api/v0/en/calendars/default/today”,
  “path” : “$.date”
}
eol

Kudos! But where to feed this skill and check if SUSI chat bot is able to answer “What is the date today?” appropriately.

To test the working of a skill:

1. Open dream.asksusi.com, write whatever name you like for the pad and then click OK.
   
   
2. Replace the data written on your pad with the skill code you created. You don’t need to save it, it is saved automatically. Now your page should look something like this:
3. To check if this skill is working properly:

• Visit SUSI chat bot.
• In the textbox below, write dream followed by the name of your pad and then press Enter key. SUSI will reply with “dreaming enabled for YOUR-PAD-NAME”.
• Now write the question string i.e. What is the date today? and you should be shown today’s date!

For more clarity, refer to this image:

Great, that you made it! You can now contribute skills by making a PR to this repository and see those skills live on SUSI without enabling any dream! Just ask your question and get your own skilled answers.

Let’s learn more about skills by introducing some changes to this question. Let’s go through some variations of this question:

• We want SUSI to answer the same when we ask “What is the date today?” or “today’s date”. To achieve this we can use ‘|’ symbol when writing our question.

The new syntax of our skill will be:

What is the date today? | today’s date?
!console:$object$
{
“url” : “http://calapi.inadiutorium.cz/api/v0/en/calendars/default/today”,
“path” : “$.date”
}
eol

• We want SUSI to answer according to the question. To make it answer all the questions like today’s date?, tomorrow’s date? or yesterday’s date?

The new syntax of our skill will be:

*’s date?
!console:$object$
{
“url” : “http://calapi.inadiutorium.cz/api/v0/en/calendars/default/$1$”,
“path” : “$.date”
}
eol

Here * acts as a wildcard character. That means * will be “today” in “today’s date” and “tomorrow” in “tomorrow’s date”. $1$ is the variable which stores the value in *.

Let’s dive into more examples:

1. Sometimes we may need 2 wildcard characters in our question:

* plot of * | * summary of *
!console:$object$
{
  "url":"http://api.tvmaze.com/singlesearch/shows?q=$2$",
  "path":"$.summary"
}
eol   

The api used above is to tell the plot of a tv show. We need to query this API with the name of the show.

For questions like “Tell me the plot of Game of Thrones” or “What is the plot of Game of Thrones”, we want to ignore the string before “plot of” and store the string after it. This string stored can be used to query the API later.

The naming of the variables for storing the values in * is done number wise. The value of the first * in the question is stored in $1$, for the second * it is in $2$ and so on…

Now the above-written skill should make sense to everyone. Let’s see the skill in action:

2. What if we want two answers from the same API. Consider this question:
   We have a public API to check the details of a space agency. We need the abbreviation of the space agency and append that to the API.

For example, when we visit https://launchlibrary.net/1.2/agency/ISRO, we get the following as output:

We want SUSI to answer the full form of a space agency along with its country code.

The skill used for it:

what is the full form of * and its country code?
!console:Full form - $name$, Country code - $countryCode$
{
  "url":"https://launchlibrary.net/1.2/agency/$1$",
  "path":"$.agencies[0]"
}
eol

How this skill works?

Let’s breakdown the path variable and check what does it leads to. The ‘$’ will fetch the whole object.

Further, “$.agencies[0]” will fetch this -:

{
  "Id":31,
  "name":"Indian Space  Research Organization",
  "countryCode":"IND",
  "abbrev":"ISRO",
  "Type":1,
  "infoURL":"http:\/\/www.isro.org\/",
 "wikiURL":"http:\/\/en.wikipedia.org\/wiki\/Indian_Space_Research_Organiation",
  "infoURLs":["http:\/\/www.isro.org\/"]
}

To fetch values of any of the keys, we can use the key name enclosed in ‘$KEY_NAME$’. The  value of that key will be automatically stored in this variable i.e. $KEY_NAME$.

Hence we use $name$ and $countryCode$ in our skill, to get the required answer.

The skill in action:

The same way we can use other API’s and contribute new skills to SUSI. To help you get started, see the public API’s repository available here. As said before, you can contribute skills by making a PR to this repository and see those skills live in SUSI!