SDK and command line interface for Watson Assistant

wcs-ocaml is a source development kit in OCaml and command line interface for Watson Assistant (formerly Watson Conversation Service, or WCS). It allows to program chat bots in OCaml.

• wcs-lib provides a framework to write WCS programs, called workspaces. It also offers an OCaml binding to the service API and a generic client application.
• wcs is a command line tool that interact with the service.

The documentation of the package is defined in the interface of the modules and available online:

• wcs-lib

The wcs command line tool allows to do operations like listing the workspaces, uploading or updating workspaces. The full documentation if avaible with the command wcs -help or online.

Quick install with Opam

The easiest way to install wcs-ocaml is through the Opam package manager for OCaml. Instructions to install Opam on you system can be found on the website: http://opam.ocaml.org/doc/Install.html.

Then you can install wcs-ocaml with the following command:

opam install wcs

This will install the following packages:

• wcs-lib
• wcs

Alternatively, you can only install the WCS SDK:

opam install wcs-lib

Tutorial

In order to illustrate the use of wcs-ocaml, we are going to program a bot that tells a knock knock joke. It is going to use the wcs-lib package:

open Wcs_lib

Let’s start with a dialog node that says "Knock knock":

let knock =
  Wcs.dialog_node "Knock"
    ~conditions: "true"
    ~text: "Knock knock"
    ()

The function Wcs.dialog_node creates a value of type Wcs_t.dialog_node that corresponds to a JSON object of type DialogNode in WCS.

The user is expected to ask who is there?. To capture this intent without looking for an exact match, we can define a WCS intent using multiple examples to train the NLU:

let who_intent =
  Wcs.intent "Who"
    ~examples: [
      "Who's there?";
      "Who is there?";
      "Who are you?";
    ]
    ()

We can now define the next step of the dialog, answering the question who is there?:

let whoisthere =
  Wcs.dialog_node "WhoIsThere"
    ~conditions_spel: (Spel.intent who_intent)
    ~text: "Broken Pencil"
    ~parent: knock
    ()

The condition is not a string but an expression written using the embedding of the Spel expression language (used by WCS) in OCaml.

We now expect the user to repeat the name of the character mentioned by the bot. To test that the user input matches the same character, we define an entity char_entity containing the name and a list of synonyms.

let char_entity =
  Wcs.entity "Character"
    ~values: [ "Broken Pencil", ["Damaged Pen"; "Fractured Pencil"] ]
    ()

The bot terminates the joke if the input given by the user matches the name of the character. Setting a return field in the context triggers the termination of the bot.

let answer =
  Wcs.dialog_node "Answer"
    ~conditions_spel: (Spel.entity char_entity ())
    ~text: "Never mind it's pointless"
    ~parent: whoisthere
    ~context: (Context.return (Json.bool true))
    ()

If the user doesn’t gives the name of the character, the bot can help with a generic answer using a fallback node:

let fallback =
  Wcs.dialog_node "Fallback"
    ~conditions_spel: Spel.anything_else
    ~text: "You should repeat my name!"
    ~previous_sibling: answer
    ~next_step: (whoisthere, Wcs_t.Goto_body)
    ()

We can now build the entire workspace containing all the dialog nodes, entities, and intents:

let ws_knockknock =
  Wcs.workspace "Knock Knock"
    ~entities: [ char_entity ]
    ~intents: [ who_intent ]
    ~dialog_nodes: [ knock; whoisthere; answer; fallback; ]
    ()

It is possible to print this workspace:

let () = print_endline (Wcs_pretty.workspace ws_knockknock)

It is also possible to directly deploy the workspace on WCS. The deployment requires the service credentials:

let wcs_cred = Wcs_bot.get_credential None

The function Wcs_bot.get_credential retrieves the path stored in the environment variable WCS_CRED to find a file containing the service credentials in the following format:

{
  "url": "https://gateway.watsonplatform.net/conversation/api",
  "password": "PASSWORD",
  "username": "USERNAME"
}

We can now deploy the workspace on WCS:

let create_rsp = Wcs_call.create_workspace wcs_cred ws_knockknock

Finally, we can try the bot with the function Wcs_bot.exec providing the credentials and the workspace identifier that has just been created:

let _ =
  begin match create_rsp with
  | { Wcs_t.crea_rsp_workspace_id = Some id } ->
    Wcs_bot.exec wcs_cred id Json.null ""
  | _  -> failwith "Deployment error"
  end

To compile this program, we need to link the wcs-lib. Using ocamlfind the command is:

ocamlfind ocamlc -linkpkg -package wcs-lib knockknock.ml