Lookup Entities

---

If you have a finite list of things you want to extract from a given piece of text, e.g., list of languages, location landmarks, company departments, etc. you can use lookup entities. These are essentially a list of words or phrases that you want to extract from a given text.

Prerequisites

Make sure to log in using API and have your authorization token in a variable called AUTHORIZATION_TOKEN before running this API.

Create a Lookup Entity

Using this API you can create an entity and add multiple regular expressions to it. If any of these match some part of a given text, it is tagged as this entity.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entity":"office_departments",
    "examples":[
        "marketing",
        "human resources",
        "it services"
    ],
    "language":"en",
    "entityType":"lookup"
}'

Attribute	Required	Type	Limits	Description
entity	true	str	30 characters	Name of the entity that you are creating
examples	true	list		A list of regular expressions as string.
language	true	str		one of the supported languages
entityType	true	str	One of lookup, regex, synonym	The type of entity this is.

note

Lookup Entities are case sensitive.

List Lookup Entities

Use our API to access all available lookup entities.

Filter by entity type

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/list/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw "{
    \"filter\":{
        \"entityType\":\"lookup\"
    },
    \"search\": \"\",
    \"pageNumber\": 1,
    \"pageSize\": 10
}"

You can filter all entities by passing an entityType attribute in the filter. This is a pagination API, hence, pageSize determines how many projects to retrieve and pageNumber determines which page to fetch.

Filter by language

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/list/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw "{
    \"filter\":{
        \"entityType\":\"lookup\",
        \"language\":\"en\"
    },
    \"search\": \"\",
    \"pageNumber\": 1,
    \"pageSize\": 10
}"

This will show all pre-trained entities in Hindi (en)

Add Examples to a Lookup Entity

To add an example to an existing entity you will need the entityId of that entity. In this case lets add another department called operations.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/add/examples/entity' \
--header 'Accept: application/json, text/plain, */*' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityId":"YOUR-ENTITY-ID",
    "examples": ["operations"]
}'

note

While updating an existing entity you can add multiple examples at once.

Delete Examples from a Lookup Entity

To delete an example from an existing entity you will also need the entityId of that entity. In this case lets delete the human resources department that we had added in the previous section.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/remove/examples/entity' \
--header 'Accept: application/json, text/plain, */*' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityId":"YOUR-ENTITY-ID",
    "examples": ["human resources"]
}'

note

You can delete multiple examples at once. Add all examples you want to delete in the list attribute examples to do so.

Delete Lookup Entity

Using this API you can delete a lookup entity. You will need the entityId for this.

curl --location --request DELETE 'https://platform.neuralspace.ai/api/nlu/v1/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityId":"YOUR-ENTITY-ID"
}'

warning

Once deleted an entity cannot be recovered.

Lookup Entities in NLU Models

To use a lookup entity in NLU you need to create one first.

Create a PNR regex entity

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entity":"office_departments",
    "examples":[
        "marketing",
        "human resources",
        "it services"
    ],
    "language":"en",
    "entityType":"lookup"
}'

Once you successfully create an entity you can add it to your NLU training examples.

To use lookup entities in your NLU models you will have to tag at least one training example with it. Additionally, you will have to set the entityType attribute of the entity to lookup.

Sample training example

{
    "projectId": "YOUR-PROJECT-ID",
    "language": "en",
    "example": {
        "intent": "file_complaint",
        "text": "I have a problem with how our marketing team",
        "type": "train",
        "entities": [
            {
                "entity": "office_departments",
                "value": "marketing",
                "start": 30,
                "end": 39,
                "entityType": "lookup"
            }
        ]
    }
}

If a lookup entity with the name office_departments does not exist then it will be created and marketing will be added as an example.