Package: azure-ai-language-conversations
Azure Conversational Language Understanding client library for PythonConversational Language Understanding - akaCLUfor short - is a cloud-based conversational AI service which provides many language understanding capabilities like:Conversation App: It's used in extracting intents and entities in conversationsWorkflow app: Acts like an orchestrator to select the best candidate to analyze conversations to get best response from apps like Qna, Luis, and Conversation AppConversational Summarization: Used to analyze conversations in the form of issues/resolution, chapter title, and narrative summarizationsSource code|Package (PyPI)|Package (Conda)|API reference documentation|Samples|Product documentation|REST API documentationGetting startedPrerequisitesPython 3.7 or later is required to use this package.AnAzure subscriptionALanguage service resourceInstall the packageInstall the Azure Conversations client library for Python withpip:pipinstallazure-ai-language-conversationsNote: This version of the client library defaults to the 2023-04-01 version of the serviceAuthenticate the clientIn order to interact with the CLU service, you'll need to create an instance of theConversationAnalysisClientclass, orConversationAuthoringClientclass. You will need anendpoint, and anAPI keyto instantiate a client object. For more information regarding authenticating with Cognitive Services, seeAuthenticate requests to Azure Cognitive Services.Get an API keyYou can get theendpointand anAPI keyfrom the Cognitive Services resource in theAzure Portal.Alternatively, use theAzure CLIcommand shown below to get the API key from the Cognitive Service resource.azcognitiveservicesaccountkeyslist--resource-group<resource-group-name>--name<resource-name>Create ConversationAnalysisClientOnce you've determined yourendpointandAPI keyyou can instantiate aConversationAnalysisClient:fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversationsimportConversationAnalysisClientendpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential=AzureKeyCredential("<api-key>")client=ConversationAnalysisClient(endpoint,credential)Create ConversationAuthoringClientOnce you've determined yourendpointandAPI keyyou can instantiate aConversationAuthoringClient:fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversations.authoringimportConversationAuthoringClientendpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential=AzureKeyCredential("<api-key>")client=ConversationAuthoringClient(endpoint,credential)Create a client with an Azure Active Directory CredentialTo use anAzure Active Directory (AAD) token credential,
provide an instance of the desired credential type obtained from theazure-identitylibrary.
Note that regional endpoints do not support AAD authentication. Create acustom subdomainname for your resource in order to use this type of authentication.Authentication with AAD requires some initial setup:Install azure-identityRegister a new AAD applicationGrant accessto the Language service by assigning the "Cognitive Services Language Reader" role to your service principal.After setup, you can choose which type ofcredentialfrom azure.identity to use.
As an example,DefaultAzureCredentialcan be used to authenticate the client:Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:AZURE_CLIENT_ID,AZURE_TENANT_ID,AZURE_CLIENT_SECRETUse the returned token credential to authenticate the client:fromazure.ai.language.conversationsimportConversationAnalysisClientfromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=ConversationAnalysisClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",credential=credential)Key conceptsConversationAnalysisClientTheConversationAnalysisClientis the primary interface for making predictions using your deployed Conversations models. For asynchronous operations, an asyncConversationAnalysisClientis in theazure.ai.language.conversation.aionamespace.ConversationAuthoringClientYou can use theConversationAuthoringClientto interface with theAzure Language Portalto carry out authoring operations on your language resource/project. For example, you can use it to create a project, populate with training data, train, test, and deploy. For asynchronous operations, an asyncConversationAuthoringClientis in theazure.ai.language.conversation.authoring.aionamespace.ExamplesTheazure-ai-language-conversationclient library provides both synchronous and asynchronous APIs.The following examples show common scenarios using theclientcreated above.Analyze Text with a Conversation AppIf you would like to extract custom intents and entities from a user utterance, you can call theclient.analyze_conversation()method with your conversation's project name as follows:# import librariesimportosfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversationsimportConversationAnalysisClient# get secretsclu_endpoint=os.environ["AZURE_CONVERSATIONS_ENDPOINT"]clu_key=os.environ["AZURE_CONVERSATIONS_KEY"]project_name=os.environ["AZURE_CONVERSATIONS_PROJECT_NAME"]deployment_name=os.environ["AZURE_CONVERSATIONS_DEPLOYMENT_NAME"]# analyze queyclient=ConversationAnalysisClient(clu_endpoint,AzureKeyCredential(clu_key))withclient:query="Send an email to Carol about the tomorrow's demo"result=client.analyze_conversation(task={"kind":"Conversation","analysisInput":{"conversationItem":{"participantId":"1","id":"1","modality":"text","language":"en","text":query},"isLoggingEnabled":False},"parameters":{"projectName":project_name,"deploymentName":deployment_name,"verbose":True}})# view resultprint("query:{}".format(result["result"]["query"]))print("project kind:{}\n".format(result["result"]["prediction"]["projectKind"]))print("top intent:{}".format(result["result"]["prediction"]["topIntent"]))print("category:{}".format(result["result"]["prediction"]["intents"][0]["category"]))print("confidence score:{}\n".format(result["result"]["prediction"]["intents"][0]["confidenceScore"]))print("entities:")forentityinresult["result"]["prediction"]["entities"]:print("\ncategory:{}".format(entity["category"]))print("text:{}".format(entity["text"]))print("confidence score:{}".format(entity["confidenceScore"]))if"resolutions"inentity:print("resolutions")forresolutioninentity["resolutions"]:print("kind:{}".format(resolution["resolutionKind"]))print("value:{}".format(resolution["value"]))if"extraInformation"inentity:print("extra info")fordatainentity["extraInformation"]:print("kind:{}".format(data["extraInformationKind"]))ifdata["extraInformationKind"]=="ListKey":print("key:{}".format(data["key"]))ifdata["extraInformationKind"]=="EntitySubtype":print("value:{}".format(data["value"]))Analyze Text with an Orchestration AppIf you would like to pass the user utterance to your orchestrator (worflow) app, you can call theclient.analyze_conversation()method with your orchestration's project name. The orchestrator project simply orchestrates the submitted user utterance between your language apps (Luis, Conversation, and Question Answering) to get the best response according to the user intent. See the next example:# import librariesimportosfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversationsimportConversationAnalysisClient# get secretsclu_endpoint=os.environ["AZURE_CONVERSATIONS_ENDPOINT"]clu_key=os.environ["AZURE_CONVERSATIONS_KEY"]project_name=os.environ["AZURE_CONVERSATIONS_WORKFLOW_PROJECT_NAME"]deployment_name=os.environ["AZURE_CONVERSATIONS_WORKFLOW_DEPLOYMENT_NAME"]# analyze queryclient=ConversationAnalysisClient(clu_endpoint,AzureKeyCredential(clu_key))withclient:query="Reserve a table for 2 at the Italian restaurant"result=client.analyze_conversation(task={"kind":"Conversation","analysisInput":{"conversationItem":{"participantId":"1","id":"1","modality":"text","language":"en","text":query},"isLoggingEnabled":False},"parameters":{"projectName":project_name,"deploymentName":deployment_name,"verbose":True}})# view resultprint("query:{}".format(result["result"]["query"]))print("project kind:{}\n".format(result["result"]["prediction"]["projectKind"]))# top intenttop_intent=result["result"]["prediction"]["topIntent"]print("top intent:{}".format(top_intent))top_intent_object=result["result"]["prediction"]["intents"][top_intent]print("confidence score:{}".format(top_intent_object["confidenceScore"]))print("project kind:{}".format(top_intent_object["targetProjectKind"]))iftop_intent_object["targetProjectKind"]=="Luis":print("\nluis response:")luis_response=top_intent_object["result"]["prediction"]print("top intent:{}".format(luis_response["topIntent"]))print("\nentities:")forentityinluis_response["entities"]:print("\n{}".format(entity))Conversational SummarizationYou can use this sample if you need to summarize a conversation in the form of an issue, and final resolution. For example, a dialog from tech support:# import librariesimportosfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversationsimportConversationAnalysisClient# get secretsendpoint=os.environ["AZURE_CONVERSATIONS_ENDPOINT"]key=os.environ["AZURE_CONVERSATIONS_KEY"]# analyze queryclient=ConversationAnalysisClient(endpoint,AzureKeyCredential(key))withclient:poller=client.begin_conversation_analysis(task={"displayName":"Analyze conversations from xxx","analysisInput":{"conversations":[{"conversationItems":[{"text":"Hello, how can I help you?","modality":"text","id":"1","participantId":"Agent"},{"text":"How to upgrade Office? I am getting error messages the whole day.","modality":"text","id":"2","participantId":"Customer"},{"text":"Press the upgrade button please. Then sign in and follow the instructions.","modality":"text","id":"3","participantId":"Agent"}],"modality":"text","id":"conversation1","language":"en"},]},"tasks":[{"taskName":"Issue task","kind":"ConversationalSummarizationTask","parameters":{"summaryAspects":["issue"]}},{"taskName":"Resolution task","kind":"ConversationalSummarizationTask","parameters":{"summaryAspects":["resolution"]}},]})# view resultresult=poller.result()task_results=result["tasks"]["items"]fortaskintask_results:print(f"\n{task['taskName']}status:{task['status']}")task_result=task["results"]iftask_result["errors"]:print("... errors occurred ...")forerrorintask_result["errors"]:print(error)else:conversation_result=task_result["conversations"][0]ifconversation_result["warnings"]:print("... view warnings ...")forwarninginconversation_result["warnings"]:print(warning)else:summaries=conversation_result["summaries"]print("... view task result ...")forsummaryinsummaries:print(f"{summary['aspect']}:{summary['text']}")Import a Conversation ProjectThis sample shows a common scenario for the authoring part of the SDKimportosfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversations.authoringimportConversationAuthoringClientclu_endpoint=os.environ["AZURE_CONVERSATIONS_ENDPOINT"]clu_key=os.environ["AZURE_CONVERSATIONS_KEY"]project_name="test_project"exported_project_assets={"projectKind":"Conversation","intents":[{"category":"Read"},{"category":"Delete"}],"entities":[{"category":"Sender"}],"utterances":[{"text":"Open Blake's email","dataset":"Train","intent":"Read","entities":[{"category":"Sender","offset":5,"length":5}],},{"text":"Delete last email","language":"en-gb","dataset":"Test","intent":"Delete","entities":[],},],}client=ConversationAuthoringClient(clu_endpoint,AzureKeyCredential(clu_key))poller=client.begin_import_project(project_name=project_name,project={"assets":exported_project_assets,"metadata":{"projectKind":"Conversation","settings":{"confidenceThreshold":0.7},"projectName":"EmailApp","multilingual":True,"description":"Trying out CLU","language":"en-us",},"projectFileVersion":"2022-05-01",},)response=poller.result()print(response)Optional ConfigurationOptional keyword arguments can be passed in at the client and per-operation level. The azure-corereference documentationdescribes available configurations for retries, logging, transport protocols, and more.TroubleshootingGeneralThe Conversations client will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.Detailed DEBUG level logging, including request/response bodies and unredacted
headers, can be enabled on a client with thelogging_enableargument.See full SDK logging documentation with exampleshere.importsysimportloggingfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.language.conversationsimportConversationAnalysisClient# Create a logger for the 'azure' SDKlogger=logging.getLogger('azure')logger.setLevel(logging.DEBUG)# Configure a console outputhandler=logging.StreamHandler(stream=sys.stdout)logger.addHandler(handler)endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential=AzureKeyCredential("<my-api-key>")# This client will log detailed information about its HTTP sessions, at DEBUG levelclient=ConversationAnalysisClient(endpoint,credential,logging_enable=True)result=client.analyze_conversation(...)Similarly,logging_enablecan enable detailed logging for a single operation, even when it isn't enabled for the client:result=client.analyze_conversation(...,logging_enable=True)Next stepsMore sample codeSee theSample READMEfor several code snippets illustrating common patterns used in the CLU Python API.ContributingSee theCONTRIBUTING.mdfor details on building, testing, and contributing to this library.This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visitcla.microsoft.com.When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.Release History1.1.0 (2023-06-13)Features AddedAdded support for service version 2023-04-01.Breaking ChangesNote: The following changes are only breaking from the previous beta. They are not breaking since version 1.0.0 when those types and members did not exist.Removed support for service version 2022-05-15-preview.Removed support for service version 2022-10-01-preview.Removed support for "ConversationalPIITask" analysis withConversationAnalysisClient.Removed support for "ConversationalSentimentTask" withConversationAnalysisClient.Removed the following methods fromConversationAuthoringClient:begin_assign_deployment_resourcesget_assign_deployment_resources_statusbegin_unassign_deployment_resourcesget_unassign_deployment_resources_statusbegin_delete_deployment_from_resourcesget_deployment_delete_from_resources_statuslist_assigned_resource_deploymentslist_deployment_resources1.1.0b3 (2022-11-10)Features AddedAdded support for the "ConversationalSentimentTask" kind withbegin_conversation_analysis.Added support for "chapterTitle" and "narrative"summaryAspectsoptions for ConversationalSummarizationTasks.Added methods to theConversationAuthoringClientto manage deployment resources:begin_assign_deployment_resourcesget_assign_deployment_resources_statusbegin_unassign_deployment_resourcesget_unassign_deployment_resources_statusbegin_delete_deployment_from_resourcesget_deployment_delete_from_resources_statusbegin_load_snapshotget_load_snapshot_statuslist_assigned_resource_deploymentslist_deployment_resourcesAdded optionaltrained_model_labelkeyword argument tobegin_export_project.Other ChangesThis version and all future versions will require Python 3.7+. Python 3.6 is no longer supported.1.1.0b2 (2022-07-01)Features AddedAdded Azure Active Directory (AAD) authentication supportAdded support for authoring operations withConversationAuthoringClientunder theazure.ai.language.conversations.authoringnamespace.1.0.0 (2022-06-27)Features AddedAdded Azure Active Directory (AAD) authentication supportAdded more resolution types for entitiesAdded support for authoring operations withConversationAuthoringClientunder theazure.ai.language.conversations.authoringnamespace.Breaking ChangesClient now uses python dictionaries for method parameters and results instead of classes.1.1.0b1 (2022-05-26)Features AddedConversation summarization task (Long-running operation)Conversation PII extraction task (Long-running operation)Breaking ChangesClient now uses python dictionaries for method parameters and results instead of classes.Many input and result parameter name changes inanalyze_conversation()method1.0.0b3 (2022-04-19)Features AddedEntity resolutionsExtra featuresBreaking ChangesTheConversationAnalysisOptionsmodel used as input to theanalyze_conversationoperation is now wrapped in aCustomConversationalTaskwhich combines the analysis options with the project parameters into a single model.Thequerywithin theConversationAnalysisOptionsis now further qualified as aTextConversationItemwith additional properties.The outputAnalyzeConversationResultis now wrapped in aCustomConversationalTaskResultaccording to the input model.Other ChangesPython 2.7 is no longer supported. Please use Python version 3.6 or later.1.0.0b1 (2021-11-03)Features AddedInitial release