Quickstart: Language Understanding (LUIS) authoring client library for Python

Get started with the Language Understanding (LUIS) authoring client library for python. Follow these steps to install the package and try out the example code for basic tasks. Language Understanding (LUIS) enables you to apply custom machine-learning intelligence to a user's conversational, natural language text to predict overall meaning, and pull out relevant, detailed information.

Use the Language Understanding (LUIS) authoring client library for Python to:

  • Create an app.
  • Add intents, entities, and example utterances.
  • Add features, such as a phrase list.
  • Train and publish an app.

Reference documentation | Library source code | Authoring Package (Pypi) | Samples

Prerequisites

Setting up

Get your Language Understanding (LUIS) starter key

Get your starter key, and create an environment variable for the key, named LUIS_AUTHORING_KEY and an environment variable for the region of the key, LUIS_REGION.

Install the Python library for LUIS

Within the application directory, install the Language Understanding (LUIS) authoring client library for python with the following command:

pip install azure-cognitiveservices-language-luis

Object model

The Language Understanding (LUIS) authoring client is a LUISAuthoringClient object that authenticates to Azure, which contains your authoring key.

Once the client is created, use this client to access functionality including:

Code examples

These code snippets show you how to do the following with the Language Understanding (LUIS) authoring client library for python:

Create a new python application

Create a new Python application in your preferred editor or IDE. Then import the following libraries.

from azure.cognitiveservices.language.luis.authoring import LUISAuthoringClient
from msrest.authentication import CognitiveServicesCredentials

import datetime, json, os, time

Create variables for your resource's Azure endpoint and key. If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable.

key_var_name = 'LUIS_AUTHORING_KEY'
if not key_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(key_var_name))
authoring_key = os.environ[key_var_name]

region_var_name = 'LUIS_REGION'
if not region_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(region_var_name))
region = os.environ[region_var_name]
endpoint = "https://{}.api.cognitive.microsoft.com".format(region)

Authenticate the client

Create an CognitiveServicesCredentials object with your key, and use it with your endpoint to create an LUISAuthoringClient object.

# Instantiate a LUIS client
client = LUISAuthoringClient(endpoint, CognitiveServicesCredentials(authoring_key))

Create a LUIS app

  1. Create a LUIS app to contain the natural language processing (NLP) model holding intents, entities, and example utterances.

  2. Create a AppsOperation object's add method to create the app. The name and language culture are required properties.

    def create_app():
        # Create a new LUIS app
        app_name    = "Contoso {}".format(datetime.datetime.now())
        app_desc    = "Flight booking app built with LUIS Python SDK."
        app_version = "0.1"
        app_locale  = "en-us"
    
        app_id = client.apps.add(dict(name=app_name,
                                        initial_version_id=app_version,
                                        description=app_desc,
                                        culture=app_locale))
    
        print("Created LUIS app {}\n    with ID {}".format(app_name, app_id))
        return app_id, app_version
    

Create intent for the app

The primary object in a LUIS app's model is the intent. The intent aligns's with a grouping of user utterance intentions. A user may ask a question, or make a statement looking for a particular intended response from a bot (or other client application). Examples of intentions are booking a flight, asking about weather in a destination city, and asking about contact information for customer service.

Use the model.add_intent method with the name of the unique intent then pass the app ID, version ID, and new intent name.

def add_intents(app_id, app_version):
    intentId = client.model.add_intent(app_id, app_version, "FindFlights")

    print("Intent FindFlights {} added.".format(intentId))

Create entities for the app

While entities are not required, they are found in most apps. The entity extracts information from the user utterance, necessary to fullfil the user's intention. There are several types of prebuilt and custom entities, each with their own data transformation object (DTO) models. Common prebuilt entities to add to your app include number, datetimeV2, geographyV2, ordinal.

This add_entities method created a Location simple entity with two roles, a Class simple entity, a Flight composite entity and adds several prebuilt entities.

It is important to know that entities are not marked with an intent. They can and usually do apply to many intents. Only example user utterances are marked for a specific, single intent.

Creation methods for entities are part of the ModelOperations class. Each entity type has its own data transformation object (DTO) model.

def add_entities(app_id, app_version):

    locationEntityId = client.model.add_entity(app_id, app_version, "Location")
    print("locationEntityId {} added.".format(locationEntityId)) 

    originRoleId = client.model.create_entity_role(app_id, app_version, locationEntityId, "Origin")
    print("originRoleId {} added.".format(originRoleId)) 

    destinationRoleId = client.model.create_entity_role(app_id, app_version, locationEntityId, "Destination")
    print("destinationRoleId {} added.".format(destinationRoleId)) 

    classEntityId = client.model.add_entity(app_id, app_version, name="Class")
    print("classEntityId {} added.".format(classEntityId)) 

    client.model.add_prebuilt(app_id, app_version, prebuilt_extractor_names=["number", "datetimeV2", "geographyV2", "ordinal"])

    compositeEntityId = client.model.add_composite_entity(app_id, app_version, name="Flight",
                                      children=["Location", "Class", "number", "datetimeV2", "geographyV2", "ordinal"])
    print("compositeEntityId {} added.".format(compositeEntityId)) 

Add example utterance to intent

In order to determine an utterance's intention and extract entities, the app needs examples of utterances. The examples need to target a specific, single intent and should mark all custom entities. Prebuilt entities do not need to be marked.

Add example utterances by creating a list of ExampleLabelObject objects, one object for each example utterance. Each example should mark all entities with a dictionary of name/value pairs of entity name and entity value. The entity value should be exactly as it appears in the text of the example utterance.

Call examples.batch with the app ID, version ID, and the list of examples. The call responds with a list of results. You need to check each example's result to make sure it was successfully added to the model.

def add_utterances(app_id, app_version):
    # Now define the utterances
    utterances = [create_utterance("FindFlights", "find flights in economy to Madrid",
                            ("Flight", "economy to Madrid"),
                            ("Location", "Madrid"),
                            ("Class", "economy")),

                  create_utterance("FindFlights", "find flights to London in first class",
                            ("Flight", "London in first class"),
                            ("Location", "London"),
                            ("Class", "first")),

                  create_utterance("FindFlights", "find flights from seattle to London in first class",
                            ("Flight", "flights from seattle to London in first class"),
                            ("Location", "London"),
                            ("Location", "Seattle"),
                            ("Class", "first"))]

    # Add the utterances in batch. You may add any number of example utterances
    # for any number of intents in one call.
    client.examples.batch(app_id, app_version, utterances)
    print("{} example utterance(s) added.".format(len(utterances)))

Train the app

Once the model is created, the LUIS app needs to be trained for this version of the model. A trained model can be used in a container, or published to the staging or product slots.

The train.train_version method needs the app ID and the version ID.

A very small model, such as this quickstart shows, will train very quickly. For production-level applications, training the app should include a polling call to the get_status method to determine when or if the training succeeded. The response is a list of ModelTrainingInfo objects with a separate status for each object. All objects must be successful for the training to be considered complete.

def train_app(app_id, app_version):
    response = client.train.train_version(app_id, app_version)
    waiting = True
    while waiting:
        info = client.train.get_status(app_id, app_version)

        # get_status returns a list of training statuses, one for each model. Loop through them and make sure all are done.
        waiting = any(map(lambda x: 'Queued' == x.details.status or 'InProgress' == x.details.status, info))
        if waiting:
            print ("Waiting 10 seconds for training to complete...")
            time.sleep(10)

Publish a Language Understanding app

Publish the LUIS app using the app.publish method. This publishes the current trained version to the specified slot at the endpoint. Your client application uses this endpoint to send user utterances for prediction of intent and entity extraction.

def publish_app(app_id, app_version):
    response = client.apps.publish(app_id, app_version, is_staging=True)
    print("Application published. Endpoint URL: " + response.endpoint_url)

Run the application

Run the application with the python command on your quickstart file.

python quickstart-file.py

Clean up resources

If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

Next steps