Introduction

The target gives to the service the description of the different interactions available.

This description appeals to serveral concepts, in particular :

  • Keywords
  • Verbose
to which several references will be made by the documentation.
We present here their operation.

Describing an interaction

For each action, the service needs :

  • Some keywords describing it ("descriptor"),
  • A verbal sentence to describe it ("verbose"),
  • The parameter list it can support ("parameters") : there can be only one.

Keywords

Keywords are used to identify the intention behind the request.

For example :
If the action consists in buying train tickets, we will have the keywords : "travel", "ticket", "go"

Note :
There is no need to put the different variation of a keyword (conjugasons, gender, number, etc.)


Verbose

It is a sentence describing the interaction.
It gives indications to the user about a possible missing information.

Example when booking a train ticket :
If the verbose is "take the train",
And the user asks "train tomorrow",
The service will answer "To take the train, I need to know the destination city.

Note:
The absence of verboses does not prevent the service from running.


Describing a parameter

An interaction ofter needs additional informations.

For example :
To book a train ticket, the target needs to know the departure city and the destination city.

The information can either be a text, a number, or something more specific.
Therefore, a set of parameters archétypes are provided.
An archetype is a way to describe a needed information.

In console mode, those archetypes are defined in your library.


Tip:
Keywords (of the interaction or its arguments) are allowing the service to make the right choices. However, an interaction can be identified without any keyword relating to the interaction itself, if its arguments are allowing it to be deduced.

For example :
"rouen tomorrow"
The prensence of a city and a date will lead to the deduction that the user wants to book a train ticket.


Keywords

In any case, this parameter needs keywords.

For example :
"city", "destination"

Note:
What is the use of those keywords ?

The information can be identified by its nature only :
We have no trouble identifying a unique number in a request for example. ("A coffee with two sugars")
Archetypes keywords résolvent ambiguities when several informations are valid :

For example :
"go to Bordeaux June 6th, return the 14th."

We have here two possible dates.
Assigning different keywords to the departure date archetype and the return date archetype allows the service to differentiate them.

For example :
Date of departure - Keyword "go"
Return date - Keyworf "return"


Verbose


The parameter's verbose has the same function as the interaction verbose.
When the user request is incomplete, it allows the nomination of the parameter.

However, unlike the interaction verbose, this one has to be a nominal groupe (no verbs).

For example :
If the interaction verbose is "take the train",
And the verbose of the city parameter is "destination city",
And the user asks fo "train tomorrow",
The service will answer "To take the train, I need to know the destination citye".

Note:
Please notice the presence of the article in the parameter verbose : "the destination city"


API connection address :

TCP : golem.ai:3003
Web Socket : golem.ai:3004/ws
Web Socket Sécurisé (WSS) : golem.ai:3005/ws
HTTP : golem.ai:3004/http
HTTPS : golem.ai:3005/http