conversations SDK

eng/tox/allowed_pylint_failures.py

@@ -58,5 +58,6 @@
     "azure-messaging-nspkg",
     "azure-agrifood-farming",
     "azure-eventhub",
-    "azure-ai-language-questionanswering"
+    "azure-ai-language-questionanswering",
+    "azure-ai-language-conversations"
 ]

sdk/cognitivelanguage/azure-ai-language-conversations/README.md

@@ -1,6 +1,16 @@
 [![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/azure-sdk-for-python.client?branchName=main)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=main)
 
-# Azure Cognitive Language Services Conversations client library for Python
+# Azure Conversational Language Understanding client library for Python
+Conversational Language Understanding, aka **CLU** for short, is a cloud-based conversational AI service which is mainly used in bots to extract useful information from user utterance (natural language processing).
+The CLU **analyze api** encompasses two projects; deepstack, and workflow projects.
+You can use the "deepstack" project if you want to extract intents (intention behind a user utterance), and custom entities.
+You can also use the "workflow" project which orchestrates multiple language apps to get the best response (language apps like Qna Maker, Luis, and Deepstack).
+
+[Source code][conversationallanguage_client_src] | [Package (PyPI)][conversationallanguage_pypi_package] | [API reference documentation][conversationallanguage_refdocs] | [Product documentation][conversationallanguage_docs] | [Samples][conversationallanguage_samples]
+
+## _Disclaimer_
+
+_Azure SDK Python packages support for Python 2.7 is ending 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_
 
 
 ## Getting started
@@ -9,7 +19,7 @@
 
 * Python 2.7, or 3.6 or later is required to use this package.
 * An [Azure subscription][azure_subscription]
-
+* An existing CLU resource
 
 > Note: the new unified Cognitive Language Services are not currently available for deployment.
 
@@ -22,21 +32,44 @@ pip install azure-ai-language-conversations
 ```
 
 ### Authenticate the client
-
+In order to interact with the CLU service, you'll need to create an instance of the [ConversationAnalysisClient][conversationanalysis_client_class] class. You will need an **endpoint**, and an **API key** to instantiate a client object. For more information regarding authenticating with Cognitive Services, see [Authenticate requests to Azure Cognitive Services][cognitive_auth].
 
 #### Get an API key
+You can get the **endpoint** and an **API key** from the Cognitive Services resource or CLU resource in the [Azure Portal][azure_portal].
+
+Alternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Question Answering resource.
 
+```powershell
+az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
+```
 
 
 #### Create ConversationAnalysisClient
+Once you've determined your **endpoint** and **API key** you can instantiate a `ConversationAnalysisClient`:
+
+```python
+from azure.core.credentials import AzureKeyCredential
+from azure.ai.language.conversations import ConversationAnalysisClient
+
+endpoint = "https://<"my-account-name">.cognitiveservices.azure.com"
+credential = AzureKeyCredential("{api-key}")
+
+client = ConversationAnalysisClient(endpoint, credential)
+```
 
 
 ## Key concepts
 
 ### ConversationAnalysisClient
-
+The [ConversationAnalysisClient][conversationanalysis_client_class] is the primary interface used for extracting custom intents and entities from user utterance using your own CLU's pretrained models. For asynchronous operations, an async `ConversationAnalysisClient` is in the `azure.ai.language.conversation.aio` namespace.
 
 ## Examples
+The `azure-ai-language-conversation` client library provides both synchronous and asynchronous APIs.
+
+The following examples show common scenarios using the `client` [created above](#create-conversationanalysisclient).
+- [Test Deepstack](#ask-a-question)
+- [Test Workflow](#ask-a-follow-up-question)
+- [Test Workflow Direct](#asynchronous-operations)
 
 
 ## Optional Configuration
@@ -85,5 +118,11 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [azure_core_ref_docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.html
 [azure_core_readme]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
 [pip_link]:https://pypi.org/project/pip/
+[conversationallanguage_client_src]: https://github.com/Azure/azure-sdk-for-python/main/sdk/cognitivelanguage/azure-ai-language-conversations
+[conversationallanguage_pypi_package]: https://github.com/Azure/azure-sdk-for-python/main/sdk/cognitivelanguage/azure-ai-language-conversations
+[conversationallanguage_refdocs]: https://github.com/Azure/azure-sdk-for-python/main/sdk/cognitivelanguage/azure-ai-language-conversations
+[conversationallanguage_docs]: https://azure.microsoft.com/services/cognitive-services/language-understanding-intelligent-service/
+[conversationallanguage_samples]: https://github.com/Azure/azure-sdk-for-python/main/sdk/cognitivelanguage/azure-ai-language-conversations/samples/README.md
+[conversationanalysis_client_class]: https://github.com/Azure/azure-sdk-for-python/main/sdk/cognitivelanguage/azure-ai-language-conversations/azure/ai/language/conversations/_conversation_analysis_client.py
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Ftemplate%2Fazure-template%2FREADME.png)

sdk/cognitivelanguage/azure-ai-language-conversations/azure/ai/language/conversations/_conversation_analysis_client.py

@@ -60,15 +60,14 @@ def send_request(
         # type: (...) -> HttpResponse
         """Runs the network request through the client's chained policies.
 
-        We have helper methods to create requests specific to this service in `azure.ai.language.conversations.rest`.
-        Use these helper methods to create the request you pass to this method.
-
+        >>> from azure.core.rest import HttpRequest
+        >>> request = HttpRequest("GET", "https://www.example.org/")
+        <HttpRequest [GET], url: 'https://www.example.org/'>
+        >>> response = client.send_request(request)
+        <HttpResponse: 200 OK>
 
         For more information on this code flow, see https://aka.ms/azsdk/python/protocol/quickstart
 
-        For advanced cases, you can also create your own :class:`~azure.core.rest.HttpRequest`
-        and pass it in.
-
         :param request: The network request you want to make. Required.
         :type request: ~azure.core.rest.HttpRequest
         :keyword bool stream: Whether the response payload will be streamed. Defaults to False.

sdk/cognitivelanguage/azure-ai-language-conversations/azure/ai/language/conversations/aio/_conversation_analysis_client.py

@@ -53,15 +53,14 @@ def send_request(
     ) -> Awaitable[AsyncHttpResponse]:
         """Runs the network request through the client's chained policies.
 
-        We have helper methods to create requests specific to this service in `azure.ai.language.conversations.rest`.
-        Use these helper methods to create the request you pass to this method.
-
+        >>> from azure.core.rest import HttpRequest
+        >>> request = HttpRequest("GET", "https://www.example.org/")
+        <HttpRequest [GET], url: 'https://www.example.org/'>
+        >>> response = await client.send_request(request)
+        <AsyncHttpResponse: 200 OK>
 
         For more information on this code flow, see https://aka.ms/azsdk/python/protocol/quickstart
 
-        For advanced cases, you can also create your own :class:`~azure.core.rest.HttpRequest`
-        and pass it in.
-
         :param request: The network request you want to make. Required.
         :type request: ~azure.core.rest.HttpRequest
         :keyword bool stream: Whether the response payload will be streamed. Defaults to False.

sdk/cognitivelanguage/azure-ai-language-conversations/azure/ai/language/conversations/aio/operations/_operations.py

@@ -26,34 +26,34 @@ class ConversationAnalysisClientOperationsMixin:
     @distributed_trace_async
     async def analyze_conversations(
         self,
-        conversation_analysis_input: "_models.ConversationAnalysisInput",
+        analyze_conversation_options: "_models.AnalyzeConversationOptions",
         *,
         project_name: str,
         deployment_name: str,
         **kwargs: Any
-    ) -> "_models.ConversationAnalysisResult":
+    ) -> "_models.AnalyzeConversationResult":
         """Analyzes the input conversation utterance.
 
-        :param conversation_analysis_input: Post body of the request.
-        :type conversation_analysis_input:
-         ~azure.ai.language.conversations.models.ConversationAnalysisInput
-        :keyword project_name: The project name.
+        :param analyze_conversation_options: Post body of the request.
+        :type analyze_conversation_options:
+         ~azure.ai.language.conversations.models.AnalyzeConversationOptions
+        :keyword project_name: The name of the project to use.
         :paramtype project_name: str
-        :keyword deployment_name: The deployment name/deployed version.
+        :keyword deployment_name: The name of the specific deployment of the project to use.
         :paramtype deployment_name: str
-        :return: ConversationAnalysisResult
-        :rtype: ~azure.ai.language.conversations.models.ConversationAnalysisResult
+        :return: AnalyzeConversationResult
+        :rtype: ~azure.ai.language.conversations.models.AnalyzeConversationResult
         :raises: ~azure.core.exceptions.HttpResponseError
         """
-        cls = kwargs.pop('cls', None)  # type: ClsType["_models.ConversationAnalysisResult"]
+        cls = kwargs.pop('cls', None)  # type: ClsType["_models.AnalyzeConversationResult"]
         error_map = {
             401: ClientAuthenticationError, 404: ResourceNotFoundError, 409: ResourceExistsError
         }
         error_map.update(kwargs.pop('error_map', {}))
 
         content_type = kwargs.pop('content_type', "application/json")  # type: Optional[str]
 
-        json = self._serialize.body(conversation_analysis_input, 'ConversationAnalysisInput')
+        json = self._serialize.body(analyze_conversation_options, 'AnalyzeConversationOptions')
 
         request = build_analyze_conversations_request(
             content_type=content_type,
@@ -67,15 +67,15 @@ async def analyze_conversations(
         }
         request.url = self._client.format_url(request.url, **path_format_arguments)
 
-        pipeline_response = await self._client.send_request(request, stream=False, _return_pipeline_response=True, **kwargs)
+        pipeline_response = await self._client._pipeline.run(request, stream=False, **kwargs)
         response = pipeline_response.http_response
 
         if response.status_code not in [200]:
             map_error(status_code=response.status_code, response=response, error_map=error_map)
-            error = self._deserialize.failsafe_deserialize(_models.ErrorResponse, response)
+            error = self._deserialize.failsafe_deserialize(_models.ErrorResponse, pipeline_response)
             raise HttpResponseError(response=response, model=error)
 
-        deserialized = self._deserialize('ConversationAnalysisResult', pipeline_response)
+        deserialized = self._deserialize('AnalyzeConversationResult', pipeline_response)
 
         if cls:
             return cls(pipeline_response, deserialized, {})

sdk/cognitivelanguage/azure-ai-language-conversations/azure/ai/language/conversations/models/__init__.py

@@ -7,17 +7,19 @@
 # --------------------------------------------------------------------------
 
 try:
+    from ._models_py3 import AnalyzeConversationOptions
+    from ._models_py3 import AnalyzeConversationResult
     from ._models_py3 import AnalyzeParameters
     from ._models_py3 import BasePrediction
-    from ._models_py3 import ConversationAnalysisInput
-    from ._models_py3 import ConversationAnalysisResult
     from ._models_py3 import DSTargetIntentResult
+    from ._models_py3 import DeepStackEntityResolution
     from ._models_py3 import DeepstackCallingOptions
-    from ._models_py3 import DeepstackClassification
     from ._models_py3 import DeepstackEntity
+    from ._models_py3 import DeepstackIntent
     from ._models_py3 import DeepstackParameters
     from ._models_py3 import DeepstackPrediction
     from ._models_py3 import DeepstackResult
+    from ._models_py3 import DictionaryNormalizedValueResolution
     from ._models_py3 import Error
     from ._models_py3 import ErrorResponse
     from ._models_py3 import InnerErrorModel
@@ -29,17 +31,19 @@
     from ._models_py3 import TargetIntentResult
     from ._models_py3 import WorkflowPrediction
 except (SyntaxError, ImportError):
+    from ._models import AnalyzeConversationOptions  # type: ignore
+    from ._models import AnalyzeConversationResult  # type: ignore
     from ._models import AnalyzeParameters  # type: ignore
     from ._models import BasePrediction  # type: ignore
-    from ._models import ConversationAnalysisInput  # type: ignore
-    from ._models import ConversationAnalysisResult  # type: ignore
     from ._models import DSTargetIntentResult  # type: ignore
+    from ._models import DeepStackEntityResolution  # type: ignore
     from ._models import DeepstackCallingOptions  # type: ignore
-    from ._models import DeepstackClassification  # type: ignore
     from ._models import DeepstackEntity  # type: ignore
+    from ._models import DeepstackIntent  # type: ignore
     from ._models import DeepstackParameters  # type: ignore
     from ._models import DeepstackPrediction  # type: ignore
     from ._models import DeepstackResult  # type: ignore
+    from ._models import DictionaryNormalizedValueResolution  # type: ignore
     from ._models import Error  # type: ignore
     from ._models import ErrorResponse  # type: ignore
     from ._models import InnerErrorModel  # type: ignore
@@ -54,22 +58,25 @@
 from ._conversation_analysis_client_enums import (
     ErrorCode,
     InnerErrorCode,
-    ProjectType,
-    TargetType,
+    ProjectKind,
+    ResolutionKind,
+    TargetKind,
 )
 
 __all__ = [
+    'AnalyzeConversationOptions',
+    'AnalyzeConversationResult',
     'AnalyzeParameters',
     'BasePrediction',
-    'ConversationAnalysisInput',
-    'ConversationAnalysisResult',
     'DSTargetIntentResult',
+    'DeepStackEntityResolution',
     'DeepstackCallingOptions',
-    'DeepstackClassification',
     'DeepstackEntity',
+    'DeepstackIntent',
     'DeepstackParameters',
     'DeepstackPrediction',
     'DeepstackResult',
+    'DictionaryNormalizedValueResolution',
     'Error',
     'ErrorResponse',
     'InnerErrorModel',
@@ -82,6 +89,7 @@
     'WorkflowPrediction',
     'ErrorCode',
     'InnerErrorCode',
-    'ProjectType',
-    'TargetType',
+    'ProjectKind',
+    'ResolutionKind',
+    'TargetKind',
 ]

sdk/cognitivelanguage/azure-ai-language-conversations/azure/ai/language/conversations/models/_conversation_analysis_client_enums.py

@@ -35,14 +35,21 @@ class InnerErrorCode(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     AZURE_COGNITIVE_SEARCH_THROTTLING = "AzureCognitiveSearchThrottling"
     EXTRACTION_FAILURE = "ExtractionFailure"
 
-class ProjectType(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
+class ProjectKind(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """The type of the project.
     """
 
     CONVERSATION = "conversation"
     WORKFLOW = "workflow"
 
-class TargetType(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
+class ResolutionKind(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
+    """The type of an entity resolution.
+    """
+
+    #: Dictionary normalized entities.
+    DICTIONARY_NORMALIZED_VALUE = "DictionaryNormalizedValue"
+
+class TargetKind(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """The type of a target service.
     """