Entities

Usage

The entities addin usage is detailed in the Addin section of the documentation.

Predefined entities

[[deprecated]]

Amount of money

  • entity type: amount_of_money
  • properties:
    • value: number
    • unit: the currency
? EXTRACT AMOUNT OF MONEY
    - How much did you pay for that?
        ???
            -: @entities.extract("amount_of_money")
            - %amount_of_money.value %amount_of_money.unit

City

  • entity type: city
  • no properties
? EXTRACT CITY
    - What's the city name?
        ???
            -: @entities.extract("city")
            - Your are located in %city

Note : the city name should be coherent with the agent’s language, ie “London” will be recognised for an english-configured agent, but not for a french one (use “Londres” instead)

Datetime

  • entity type: datetime
  • properties:
    • value: string representing the datetime is an iso format
    • input: the substring of the user input that matched a datetime
? EXTRACT DATETIME
    - What's your date of birth?
        ???
            -: @entities.extract("datetime")
            - %datetime.value

Distance

  • entity type: distance
  • properties:
    • value: number
    • unit: distance unit
? EXTRACT DISTANCE
    - What's the distance?
        ???
            -: @entities.extract("distance")
            - %distance.value %distance.unit

Duration

  • entity type: duration
  • properties:
    • value: number
    • unit: duration unit
? EXTRACT DURATION
    - What's the duration?
        ???
            -: @entities.extract("duration")
            - %duration.value %duration.unit

Email

  • entity type: email
  • no properties
? EXTRACT EMAIL
    - What is your email address?
        ???
            -: @entities.extract("email")
            - Your email is : %email

Interval

  • entity type: interval
  • properties
    • from: the lower bound string representing the datetime is an iso format
    • to: the upper bound string representing the datetime is an iso format (The system will take the upper bound for the to property)
    • input: the substring of the user input that matched a datetime
? EXTRACT INTERVAL
    - What is the time interval?
        ???
            -: @entities.extract("interval")
            - from %interval.from.value to %interval.to.value

Number

  • entity type: number
  • no properties
? EXTRACT NUMBER
    - Please give me a number
        ???
            -: @entities.extract("number")
            - The number is : %number

Ordinal

  • entity type: ordinal
  • no properties
? EXTRACT ORDINAL
    - Please give me an ordinal number
        ???
            -: @entities.extract("ordinal")
            - The ordinal is : %ordinal

Phone number

  • entity type: phone_number
  • no properties
? EXTRACT PHONE NUMBER
    - Please give me the phone number
        ???
            -: @entities.extract("phone_number")
            - The phone number is : %phone_number

Quantity

  • entity type: quantity
  • properties:
    • value: number
    • unit: quantity unit
? EXTRACT QUANTITY
    - Please give me the quantity
        ???
            -: @entities.extract("quantity")
            - The quantity is : %quantity.value %quantity.unit

Temperature

  • entity type: temperature
  • properties:
    • value: number
    • unit: temperature unit
? EXTRACT TEMPERATURE
    - Please give me the temperature
        ???
            -: @entities.extract("temperature")
            - The temperature is : %temperature.value %temperature.unit

Url

  • entity type: temperature
  • no properties
? EXTRACT URL
    - What is the URL?
        ???
            -: @entities.extract("url")
            - The url is : %url

Volume

  • entity type: volume
  • properties:
    • value: number
    • unit: volume unit
? EXTRACT VOLUME
    - Please give me the volume
        ???
            -: @entities.extract("volume")
            - The volume is : %volume.value %volume.unit

Phone numbers

You can extract US phone numbers :

?! Phone
    -: @entities.extract("phone_us")
    - Your number is : %phone_us

and FR phone numbers :

?! Phone
    -: @entities.extract("phone_fr")
    - Your number is : %phone_fr

Other properties :

  • array : contains all phone parts
{
    "text":"0607080910",
    "array":[
        "06",
        "07",
        "08",
        "09",
        "10"
    ]
}

You can use those properties like this :

? MON NUMERO DE TELEPHONE EST LE
?% phone_fr
    - Format like : {CONCAT_PHONE("%phone_fr.array")} or %phone_fr.array[0]%phone_fr.array[1]%phone_fr.array[2]%phone_fr.array[3]%phone_fr.array[4]

[CONCAT_PHONE(%part, %last)]
    - %part-
    -| "%last"=="true"
    - %part

Date

The date extraction allows you to extract simple and complex date times, in english and french

Because of that, date value in athena is an object :

{
  "Input": "date 12 février 2012", // user text
  "Start": {
    "Value": "2012-02-12T00:00:00",// datetime
    "Text": "12 février 2012" // which part of text was used for extraction
  },// The datetime found
  "End": null, // If it's a time range, this one will be filled
  "Error": null
}

You can use it like this in Athena :


?! Date
    -: @entities.extract("date")
    - this is the full date object : %date
    -| %date.Start.exists
    -| %date.End.exists
    - from %date.Start.Value to %date.End.Value
    -| %date.Start.exists
    - from %date.Start

External entities

You can import your own entities using a file upload system

Uploading files

Currently the extractor only support xlsx files.

The files have to respect a per defined format:

|    Id    |    Name    |
|----------|------------|
| entityId | entityName |
  • Ids are used in athena code to understand what subtype of entity has been extracted.
  • Name are the synonyms of this entity

Exemple :

| Id    | Name    |
|-------|---------|
| auto  | car     |
| auto  | truck   |
| cycle | bicycle |
| cycle | bike    |

To upload the file, use the upload service you were given by your Satisfaction administrator.

Defining the extractor in athena

If it does not exists, create a file with a “extractor” directive with this content:

[

]

Extractor V1

Add the corresponding extractor:

{
    "extractorType": "excel",
    "entityType": "vehicle",
    "url": "https://file_upload_service.satisfaction.ai/my_file.xlsx"
}

Extractor V2

Add the corresponding extractor:

{
    "extractorType": "nlpipe-resource",
    "resourceType": "excel",
    "entityType": "vehicle",
    "url": "https://file_upload_service.satisfaction.ai/my_file.xlsx"
}

Here we have defined an extractor of type “vehicle”, and given the content of this file, we have two sub types: auto and cycle

Usage in Athena

? EXTRACT VEHICLE
    - What kind of vehicle do you have?
        ???
            -: @entities.extract("vehicle")
            - no vehicle detected
            -| @contextScenario.has("vehicle")
            - you have a %vehicle.Id

In the above sample, we’re extracting a vehicle, checking if the extraction worked, and display the id of the entity

? EXTRACT VEHICLE
    - What kind of vehicle do you have?
        ???
            -: @entities.extract("vehicle")
            - no vehicle detected
            -| @contextScenario.has("vehicle.auto")
            - this is the kind of auto you use: %vehicle.Name
            -| @contextScenario.has("vehicle.cycle")
            - this is the kind of cycle you use: %vehicle.Name

In the example above, we’re checking the value of the sub type.

Multi field extractor

Very similar to excel extractor, but you can extract entities based on several fields:

| id | make       | model      |
|----|------------|------------|
| 1  | ford       | mustang    |
| 2  | ford       | focus      |
| 3  | ford       | gt         |
| 4  | dodge      | challenger |
| 5  | dodge      | charger    |
| 6  | dodge      | viper      |
| 7  | chevrolet  | camaro     |
| 8  | chevrolet  | corvette   |
| 9  | nissan     | gtr        |

the extractor is defined in the extractor knowledge file:

{
    "extractorType": "excel-multi-fields",
    "entityType": "make_model",
    "extractFields": ["make", "model"],
    "url": "https://file_upload_service.satisfaction.ai/my_file.xlsx"
}

usage in athena:

? EXTRACT VEHICLE
    - What kind of vehicle do you have?
        ???
            -: @entities.extract("make_model")
            - no vehicle found
            -| @core.exists("make_model", "$.fields.[?(@ === 'make')]")
            - I found the make %make_model.text now we need to ask for the model
            -| @core.exists("make_model", "$.fields.[?(@ === 'model')]")
            - I found the make %make_model.text now we need to ask for the make
            -| @core.exists("make_model", "$.fields.[?(@ === 'model')]")
            -| @core.exists("make_model", "$.fields.[?(@ === 'make')]")
            - both make and model has been found, but multiple match, we need to find the good one.
            -| %make_model.entities.length == 1
            -| @core.exists("make_model", "$.fields.[?(@ === 'model')]")
            -| @core.exists("make_model", "$.fields.[?(@ === 'make')]")
            - seems I found the vehicle %make_model.entities[0]

make_model is a multi field response object:

{
    "fields":[
        ""
    ],
    "entities":[

    ],
    "text":""
}
  • fields contains the list of fields that matched the user input
  • entities contains the list of entities found, object are json object based on all fields
  • text user input that matched

Exemples:

user input : I own a 1970 ford mustang

{
    "fields":["make", "model"],
    "entities":[
        {
            "Id":"1",
            "make":"ford",
            "model":"mustang"
        }
    ],
    "text": "ford mustang"
}

user input : I own a 1970 mustang

{
    "fields":["model"],
    "entities":[
        {
            "Id":"1",
            "make":"ford",
            "model":"mustang"
        }
    ],
    "text": "mustang"
}