azure.ai.language.conversations.aio package

class azure.ai.language.conversations.aio.ConversationAnalysisClient(endpoint: str, credential: azure.core.credentials.AzureKeyCredential, **kwargs: Any)[source]

The language service conversations API is a suite of natural language processing (NLP) skills that can be used to analyze structured conversations (textual or spoken). The synchronous API in this suite accepts a request and mediates among multiple language projects, such as LUIS Generally Available, Question Answering, Conversational Language Understanding, and then calls the best candidate service to handle the request. At last, it returns a response with the candidate service’s response as a payload.

In some cases, this API needs to forward requests and responses between the caller and an

upstream service. The asynchronous APIs in this suite enable tasks like Conversation Summarization and Conversational PII detection.

Parameters

  • endpoint (str) – Supported Cognitive Services endpoint (e.g., https://<resource-name>.api.cognitiveservices.azure.com).

  • credential (AzureKeyCredential) – Credential needed for the client to connect to Azure.

Keyword Arguments

  • api_version (str) – Api Version. Default value is “2022-05-15-preview”. Note that overriding this default value may result in unsupported behavior.

  • polling_interval (int) – Default waiting time between two polls for LRO operations if no Retry-After header is present.

analyze_conversation(task: MutableMapping[str, Any], **kwargs: Any) → MutableMapping[str, Any]

Analyzes the input conversation utterance.

Parameters

task (JSON) – A single conversational task to execute.

Returns

JSON object

Return type

JSON

Raises

~azure.core.exceptions.HttpResponseError

Example

# JSON input template you can fill out and use as your body input.
task = {
    "kind": "str", # Required. Enumeration of supported Conversation tasks. Known values are: "Conversation",
    "analysisInput": {
        "conversationItem": {
            "id": "str", # Required. The ID of a conversation item.,
            "participantId": "str", # Required. The participant ID of a conversation item.,
            "role": "str", # Optional. The role of the participant. Known values are: "agent", "cutomer", and "generic".
            "modality": "string", # Required, Enumeration of supported conversational modalities. Known values are: "text", and "transcript".,
            "language": "str", # Optional. The override language of a conversation item in BCP 47 language representation.,
            "text": "str", # Required. The text input.
        }
    },
    "parameters": {
        "projectName": "str", # Required. The name of the project to use.,
        "deploymentName": "str", # Required. The name of the deployment to use.,
        "verbose": "bool", # Optional. If true, the service will return more detailed information in the response.,
        "isLoggingEnabled": "bool", # Optional. If true, the service will keep the query for further review.,
        "directTarget": "str", # Optional. The name of a target project to forward the request to.
    }
}

# response body for status code(s): 200
response.json() == {
    "kind": "str", # Required. Enumeration of supported conversational task results. Known values are: "ConversationResult",
    "result": {
        "query": "str", # Required. The conversation utterance given by the caller.,
        "detectedLanguage": "str", # Optional. The system detected language for the query in BCP 47 language representation.,
        "prediction": {
            "topIntent": "str", # Required. The intent with the highest score.,
            "projectKind": "str", # Required. The type of the project. Known values are: "Conversation", and "Orchestration",
        }
    }
}
async begin_conversation_analysis(task: collections.abc.MutableMapping[str, Any], **kwargs: Any) → azure.core.polling._async_poller.AsyncLROPoller[collections.abc.MutableMapping[str, Any]]

Submit analysis job for conversations.

Submit a collection of conversations for analysis. Specify one or more unique tasks to be executed.

Parameters

task (JSON) – The collection of conversations to analyze and one or more tasks to execute.

Keyword Arguments

  • continuation_token (str) – A continuation token to restart a poller from a saved state.

  • polling (bool or AsyncPollingMethod) – By default, your polling method will be AsyncLROBasePolling. Pass in False for this operation to not poll, or pass in your own initialized polling object for a personal polling strategy.

  • polling_interval (int) – Default waiting time between two polls for LRO operations if no Retry-After header is present.

Returns

An instance of AsyncLROPoller that returns JSON object

Return type

AsyncLROPoller[JSON]

Raises

~azure.core.exceptions.HttpResponseError

Example

# JSON input template you can fill out and use as your body input.
task = {
    "analysisInput": {
        "conversations": [
            {
                "domain": "str",  # Optional. Enumeration of
                  supported conversational domains. Known values are: "finance",
                  "healthcare", "generic".
                "id": "str",  # Required. Unique identifier for the
                  conversation.
                "language": "str",  # Required. The language of the
                  conversation item in BCP-47 format.
                modality: modality
            }
        ]
    },
    "displayName": "str",  # Optional. Optional display name for the analysis
      job.
    "tasks": [
        {
            "taskName": "str",  # Optional. Required. The set of tasks to
              execute on the input conversation.
            kind: AnalyzeConversationLROTask
        }
    ]
}

# response body for status code(s): 200
response.json() == {
    "createdDateTime": "2020-02-20 00:00:00",  # Required.
    "displayName": "str",  # Optional.
    "errors": [
        {
            "code": "str",  # Required. One of a server-defined set of
              error codes. Known values are: "InvalidRequest", "InvalidArgument",
              "Unauthorized", "Forbidden", "NotFound", "ProjectNotFound",
              "OperationNotFound", "AzureCognitiveSearchNotFound",
              "AzureCognitiveSearchIndexNotFound", "TooManyRequests",
              "AzureCognitiveSearchThrottling",
              "AzureCognitiveSearchIndexLimitReached", "InternalServerError",
              "ServiceUnavailable", "Timeout", "QuotaExceeded", "Conflict", "Warning".
            "details": [
                ...
            ],
            "innererror": {
                "code": "str",  # Required. One of a server-defined
                  set of error codes. Known values are: "InvalidRequest",
                  "InvalidParameterValue", "KnowledgeBaseNotFound",
                  "AzureCognitiveSearchNotFound", "AzureCognitiveSearchThrottling",
                  "ExtractionFailure", "InvalidRequestBodyFormat", "EmptyRequest",
                  "MissingInputDocuments", "InvalidDocument", "ModelVersionIncorrect",
                  "InvalidDocumentBatch", "UnsupportedLanguageCode",
                  "InvalidCountryHint".
                "details": {
                    "str": "str"  # Optional. Error details.
                },
                "innererror": ...,
                "message": "str",  # Required. Error message.
                "target": "str"  # Optional. Error target.
            },
            "message": "str",  # Required. A human-readable
              representation of the error.
            "target": "str"  # Optional. The target of the error.
        }
    ],
    "expirationDateTime": "2020-02-20 00:00:00",  # Optional.
    "jobId": "str",  # Required.
    "lastUpdatedDateTime": "2020-02-20 00:00:00",  # Required.
    "nextLink": "str",  # Optional.
    "statistics": {
        "conversationsCount": 0,  # Required. Number of conversations
          submitted in the request.
        "erroneousConversationsCount": 0,  # Required. Number of invalid
          documents. This includes empty, over-size limit or non-supported languages
          documents.
        "transactionsCount": 0.0,  # Required. Number of transactions for the
          request.
        "validConversationsCount": 0  # Required. Number of conversations
          documents. This excludes empty, over-size limit or non-supported languages
          documents.
    },
    "status": "str",  # Required. Known values are: "notStarted", "running",
      "succeeded", "partiallyCompleted", "failed", "cancelled", "cancelling".
    "tasks": {
        "completed": 0,  # Required. Count of tasks completed successfully.
        "failed": 0,  # Required. Count of tasks that failed.
        "inProgress": 0,  # Required. Count of tasks in progress currently.
        "items": [
            {
                "lastUpdateDateTime": "2020-02-20 00:00:00",  #
                  Required. The last updated time in UTC for the task.
                "status": "str",  # Required. The status of the task
                  at the mentioned last update time. Known values are: "notStarted",
                  "running", "succeeded", "failed", "cancelled", "cancelling".
                "taskName": "str",  # Optional. List of results from
                  tasks (if available).
                kind: AnalyzeConversationJobResult
            }
        ],
        "total": 0  # Required. Total count of tasks submitted as part of the
          job.
    }
}
async close() → None[source]
send_request(request: azure.core.rest._rest_py3.HttpRequest, **kwargs: Any) → Awaitable[azure.core.rest._rest_py3.AsyncHttpResponse][source]

Runs the network request through the client’s chained policies.

>>> 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

Parameters

request (HttpRequest) – The network request you want to make. Required.

Keyword Arguments

stream (bool) – Whether the response payload will be streamed. Defaults to False.

Returns

The response of your network call. Does not do error handling on your response.

Return type

AsyncHttpResponse