Friday, September 4, 2015

Create a siri-like AI with Hutoma Deep Learning APIs

Eliminating complexity in the User Interface its critical. It’s why many people love Apple products. And Machine Learning is the next natural evolution in reducing UI complexity. You are already seeing Machine Learning show up in lots of consumer interfaces - especially in smartphone applications. You’ll also see it in lots of next-generation consumer hardware, where the UI options are limited but the consumer use cases may be quite varied. 

The Hutoma API makes super easy to create and deploy siri-like interfaces on your web/mobile app, connected device, smart device or hardware project. If you have questions or need support, email

An "Hello World" AI
In this section, we will lead you through creating a simple AI all using our RESTful API. You will need to make HTTP requests using either the curl command line tool or a REST client. 

Step 1) Preparing the training data 
Hutoma AIs use supervised learning to infer the right answer from training data. The training data consist of two text files: one containing a set of input phrases, and another containing the desired output phrases. For our hello world ai, create a source.txt and a target.txt file and add the training phrases shown in the table below (or download the sample files)

source.txt (download)target.txt (download)
how are you
what color is the sky
hello world!
i am fine, how are you?
the sky is blue!

Step 2) Create a new AI
To create a new AI make the following REST call:
curl "" --request POST -H'user_key: YOUR_DEV_KEY'

Remember to replace YOUR_DEV_KEY with the dev key you get when you sign up with our API . The JSON response will contain a "AIID" field. Take a note of that ID.

Step 3) Start training your AI
Before we kick off the training process, you need to first upload the source.txt and target.txt files you created in Step 1. You can do this with the following two REST calls. 
curl -X POST '{aiid}/training/'  -H'user_key: YOUR_DEV_KEY' -F 'file=@source.txt'

Remember to replace the string {aiid} in the URL above with the ID you got in Step 2.  Now upload the target.txt file:
curl -X POST '{aiid}/training/'  -H'user_key: YOUR_DEV_KEY' -F 'file=@target.txt'

Once the ulpoad is completed, kick off the training process with this call: 
curl '{aiid}/training?action=start' --request PUT -H'user_key: YOUR_DEV_KEY'

Step 4) Monitor the training process
The time required to train your network greatly depends on the data you will feed to it, as well as your position in the training queue. For a simple network like the one we are building it should not take more than few minutes to complete. You can monitor the status of your training process with the following call:
curl -X GET "{aiid}-H'user_key: YOUR_DEV_KEY'

Periodically ping the server to check your training status. After few minutes your JSON response will contain the following: 

trainingStatusA numerical value indicating the status of the training process:

  • 0 - request queued
  • 1 - training in process
  • 2 - training completed
  • 3 - stopping
  • 4 - stopped
  • 5 - max training time reached
  • trainingStatusDetailsDetails about the trainingStatus code
    runtimeStatusA numerical value indicating the runtime status of your network. 0 means the network (i.e. the bot) is not running. 1 means the network is running and can be queried.
    sampleThe sample field provides a qualitative metric to help you asses how well the network is learning your sample data. At each learning iteration, the API will send a random phrase (marked as "input" in the JSON response), will check the target output phrase (marked as "target" in the JSON response) and will store the answer it will receive back (marked as "current output").
    scoreThe score field provides a quantitative metric to help you assess how well the network is learning your sample data. At each learning iteration, the API will compute a training error function that tells you how far your bot is from completely learning the training data. The training process will automatically stop once this function reaches 0 (or you reached your allocated traning time). The score field also contains useful information about the number of training iteration, how long your network has been in training etc.
    compileError (AIML)If you supply AIML files, this field will tell you if your files correctly compile.
    runtimeStatus (AIML)A numerical value indicating the runtime status of your aiml interpreter. 0 means the interpreter (i.e. the bot) is not running. 1 means the aiml interpreter is running and can be queried.
    trainingStatusDetails (AIML)Details about the runtimeStatus code

    Note that you can start chatting with your bot while the training is in process.

    Step 5) Speaking to your AI
    Once your AI is ready, you can interact with it via text or speech. Use the following REST call to talk to your AI and hear a response

    curl -X GET --header "Accept: application/json" "{aiid}/speak?voice=0" -H'user_key: YOUR_DEV_KEY' -F 'file=@PATH_TO_UTTERANCE_FILE'

    To text to your AI use the following REST call
    curl "{aiid}/chat?uid=1&q=what%20color%20is%20the%20sky" -H'user_key: YOUR_DEV_KEY'