Release Conversations Language Understanding SDK 1.1.0-beta.1

sdk/cognitivelanguage/Azure.AI.Language.Conversations/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### Features Added
 
+- Added conversation summarization and personally identifiable information (PII) extraction methods to `ConversationAnalysisClient`:
+  - `AnalyzeConversation` and `AnalyzeConversationAsync`
+  - `CancelAnalyzeConversationJob` and `CancelAnalyzeConversationJobAsync`
+  - `GetAnalyzeConversationJobStatus` and `GetAnalyzeConversationJobStatusAsync`
+- Added support for service version 2022-05-15-preview.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md

@@ -304,6 +304,184 @@ if (targetIntentResult.GetProperty("targetProjectKind").GetString() == "Question
 }
 ```
 
+#### Conversational summarization
+
+To summarize a conversation, you can use the `AnalyzeConversation` method overload that returns an `Operation<BinaryData>`:
+
+```C# Snippet:AnalyzeConversation_ConversationSummarization
+var data = new
+{
+    analysisInput = new
+    {
+        conversations = new[]
+        {
+            new
+            {
+                conversationItems = new[]
+                {
+                    new
+                    {
+                        text = "Hello, how can I help you?",
+                        id = "1",
+                        participantId = "Agent",
+                    },
+                    new
+                    {
+                        text = "How to upgrade Office? I am getting error messages the whole day.",
+                        id = "2",
+                        participantId = "Customer",
+                    },
+                    new
+                    {
+                        text = "Press the upgrade button please. Then sign in and follow the instructions.",
+                        id = "3",
+                        participantId = "Agent",
+                    },
+                },
+                id = "1",
+                language = "en",
+                modality = "text",
+            },
+        }
+    },
+    tasks = new[]
+    {
+        new
+        {
+            parameters = new
+            {
+                summaryAspects = new[]
+                {
+                    "issue",
+                    "resolution",
+                }
+            },
+            kind = "ConversationalSummarizationTask",
+            taskName = "1",
+        },
+    },
+};
+
+Operation<BinaryData> analyzeConversationOperation = client.AnalyzeConversation(WaitUntil.Started, RequestContent.Create(data));
+analyzeConversationOperation.WaitForCompletion();
+
+using JsonDocument result = JsonDocument.Parse(analyzeConversationOperation.Value.ToStream());
+JsonElement jobResults = result.RootElement;
+foreach (JsonElement task in jobResults.GetProperty("tasks").GetProperty("items").EnumerateArray())
+{
+    JsonElement results = task.GetProperty("results");
+
+    Console.WriteLine("Conversations:");
+    foreach (JsonElement conversation in results.GetProperty("conversations").EnumerateArray())
+    {
+        Console.WriteLine($"Conversation: #{conversation.GetProperty("id").GetString()}");
+        Console.WriteLine("Summaries:");
+        foreach (JsonElement summary in conversation.GetProperty("summaries").EnumerateArray())
+        {
+            Console.WriteLine($"Text: {summary.GetProperty("text").GetString()}");
+            Console.WriteLine($"Aspect: {summary.GetProperty("aspect").GetString()}");
+        }
+        Console.WriteLine();
+    }
+}
+```
+
+#### Conversational PII
+
+To extract and redact personally-identifiable information (PII) from text, you can use the `AnalyzeConversation` method overload that returns an `Operation<BinaryData>`:
+
+```C# Snippet:AnalyzeConversation_ConversationPII_Text
+var data = new
+{
+    analysisInput = new
+    {
+        conversations = new[]
+        {
+            new
+            {
+                conversationItems = new[]
+                {
+                    new
+                    {
+                        text = "Hi, I am John Doe.",
+                        id = "1",
+                        participantId = "0",
+                    },
+                    new
+                    {
+                        text = "Hi John, how are you doing today?",
+                        id = "2",
+                        participantId = "1",
+                    },
+                    new
+                    {
+                        text = "Pretty good.",
+                        id = "3",
+                        participantId = "0",
+                    },
+                },
+                id = "1",
+                language = "en",
+                modality = "text",
+            },
+        }
+    },
+    tasks = new[]
+    {
+        new
+        {
+            parameters = new
+            {
+                piiCategories = new[]
+                {
+                    "All",
+                },
+                includeAudioRedaction = false,
+                modelVersion = "2022-05-15-preview",
+                loggingOptOut = false,
+            },
+            kind = "ConversationalPIITask",
+            taskName = "analyze",
+        },
+    },
+};
+
+Operation<BinaryData> analyzeConversationOperation = client.AnalyzeConversation(WaitUntil.Started, RequestContent.Create(data));
+analyzeConversationOperation.WaitForCompletion();
+
+using JsonDocument result = JsonDocument.Parse(analyzeConversationOperation.Value.ToStream());
+JsonElement jobResults = result.RootElement;
+foreach (JsonElement task in jobResults.GetProperty("tasks").GetProperty("items").EnumerateArray())
+{
+    JsonElement results = task.GetProperty("results");
+
+    Console.WriteLine("Conversations:");
+    foreach (JsonElement conversation in results.GetProperty("conversations").EnumerateArray())
+    {
+        Console.WriteLine($"Conversation: #{conversation.GetProperty("id").GetString()}");
+        Console.WriteLine("Conversation Items:");
+        foreach (JsonElement conversationItem in conversation.GetProperty("conversationItems").EnumerateArray())
+        {
+            Console.WriteLine($"Conversation Item: #{conversationItem.GetProperty("id").GetString()}");
+
+            Console.WriteLine($"Redacted Text: {conversationItem.GetProperty("redactedContent").GetProperty("text").GetString()}");
+
+            Console.WriteLine("Entities:");
+            foreach (JsonElement entity in conversationItem.GetProperty("entities").EnumerateArray())
+            {
+                Console.WriteLine($"Text: {entity.GetProperty("text").GetString()}");
+                Console.WriteLine($"Offset: {entity.GetProperty("offset").GetInt32()}");
+                Console.WriteLine($"Category: {entity.GetProperty("category").GetString()}");
+                Console.WriteLine($"Confidence Score: {entity.GetProperty("confidenceScore").GetSingle()}");
+                Console.WriteLine($"Length: {entity.GetProperty("length").GetInt32()}");
+                Console.WriteLine();
+            }
+        }
+        Console.WriteLine();
+    }
+}
+```
+
 ### Additional samples
 
 Browser our [samples][conversationanalysis_samples] for more examples of how to analyze conversations.

sdk/cognitivelanguage/Azure.AI.Language.Conversations/api/Azure.AI.Language.Conversations.netstandard2.0.cs

@@ -10,14 +10,21 @@ public ConversationAnalysisClient(System.Uri endpoint, Azure.Core.TokenCredentia
         public virtual System.Uri Endpoint { get { throw null; } }
         public virtual Azure.Core.Pipeline.HttpPipeline Pipeline { get { throw null; } }
         public virtual Azure.Response AnalyzeConversation(Azure.Core.RequestContent content, Azure.RequestContext context = null) { throw null; }
+        public virtual Azure.Operation<System.BinaryData> AnalyzeConversation(Azure.WaitUntil waitUntil, Azure.Core.RequestContent content, Azure.RequestContext context = null) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Response> AnalyzeConversationAsync(Azure.Core.RequestContent content, Azure.RequestContext context = null) { throw null; }
+        public virtual System.Threading.Tasks.Task<Azure.Operation<System.BinaryData>> AnalyzeConversationAsync(Azure.WaitUntil waitUntil, Azure.Core.RequestContent content, Azure.RequestContext context = null) { throw null; }
+        public virtual Azure.Operation CancelAnalyzeConversationJob(Azure.WaitUntil waitUntil, System.Guid jobId, Azure.RequestContext context = null) { throw null; }
+        public virtual System.Threading.Tasks.Task<Azure.Operation> CancelAnalyzeConversationJobAsync(Azure.WaitUntil waitUntil, System.Guid jobId, Azure.RequestContext context = null) { throw null; }
+        public virtual Azure.Response GetAnalyzeConversationJobStatus(System.Guid jobId, bool? showStats = default(bool?), Azure.RequestContext context = null) { throw null; }
+        public virtual System.Threading.Tasks.Task<Azure.Response> GetAnalyzeConversationJobStatusAsync(System.Guid jobId, bool? showStats = default(bool?), Azure.RequestContext context = null) { throw null; }
     }
     public partial class ConversationsClientOptions : Azure.Core.ClientOptions
     {
-        public ConversationsClientOptions(Azure.AI.Language.Conversations.ConversationsClientOptions.ServiceVersion version = Azure.AI.Language.Conversations.ConversationsClientOptions.ServiceVersion.V2022_05_01) { }
+        public ConversationsClientOptions(Azure.AI.Language.Conversations.ConversationsClientOptions.ServiceVersion version = Azure.AI.Language.Conversations.ConversationsClientOptions.ServiceVersion.V2022_05_15_Preview) { }
         public enum ServiceVersion
         {
             V2022_05_01 = 1,
+            V2022_05_15_Preview = 2,
         }
     }
 }

sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/README.md

@@ -19,3 +19,6 @@ Conversation Analysis is a cloud-based conversational AI service that applies cu
 - [Analyze an utterance in a different language](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample3_AnalyzeConversationWithLanguage.md)
 - [Analyze an utterance using extra options](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample4_AnalyzeConversationWithOptions.md)
 - [Import a project](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample5_ImportProject.md)
+- [Analyze a conversation with Conversation Summarization](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample6_AnalyzeConversation_ConversationSummarization.md)
+- [Analyze a conversation with Conversation PII using text input](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample7_AnalyzeConversation_ConversationPII_Text.md)
+- [Analyze a conversation with Conversation PII using transcript input](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample8_AnalyzeConversation_ConversationPII_Transcript.md)

sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample6_AnalyzeConversation_ConversationSummarization.md

@@ -0,0 +1,103 @@
+# Analyze a conversation
+
+This sample demonstrates how to analyze a conversation with Conversation Summarization. To get started, you'll need to create a Cognitive Language service endpoint and an API key. See the [README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md) for links and instructions.
+
+To analyze an utterance, you need to first create a `ConversationAnalysisClient` using an endpoint and API key. These can be stored in an environment variable, configuration setting, or any way that works for your application.
+
+```C# Snippet:ConversationAnalysisClient_Create
+Uri endpoint = new Uri("https://myaccount.cognitive.microsoft.com");
+AzureKeyCredential credential = new AzureKeyCredential("{api-key}");
+
+ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);
+```
+
+Once you have created a client, you can call synchronous or asynchronous methods.
+
+## Synchronous
+
+```C# Snippet:AnalyzeConversation_ConversationSummarization
+var data = new
+{
+    analysisInput = new
+    {
+        conversations = new[]
+        {
+            new
+            {
+                conversationItems = new[]
+                {
+                    new
+                    {
+                        text = "Hello, how can I help you?",
+                        id = "1",
+                        participantId = "Agent",
+                    },
+                    new
+                    {
+                        text = "How to upgrade Office? I am getting error messages the whole day.",
+                        id = "2",
+                        participantId = "Customer",
+                    },
+                    new
+                    {
+                        text = "Press the upgrade button please. Then sign in and follow the instructions.",
+                        id = "3",
+                        participantId = "Agent",
+                    },
+                },
+                id = "1",
+                language = "en",
+                modality = "text",
+            },
+        }
+    },
+    tasks = new[]
+    {
+        new
+        {
+            parameters = new
+            {
+                summaryAspects = new[]
+                {
+                    "issue",
+                    "resolution",
+                }
+            },
+            kind = "ConversationalSummarizationTask",
+            taskName = "1",
+        },
+    },
+};
+
+Operation<BinaryData> analyzeConversationOperation = client.AnalyzeConversation(WaitUntil.Started, RequestContent.Create(data));
+analyzeConversationOperation.WaitForCompletion();
+
+using JsonDocument result = JsonDocument.Parse(analyzeConversationOperation.Value.ToStream());
+JsonElement jobResults = result.RootElement;
+foreach (JsonElement task in jobResults.GetProperty("tasks").GetProperty("items").EnumerateArray())
+{
+    JsonElement results = task.GetProperty("results");
+
+    Console.WriteLine("Conversations:");
+    foreach (JsonElement conversation in results.GetProperty("conversations").EnumerateArray())
+    {
+        Console.WriteLine($"Conversation: #{conversation.GetProperty("id").GetString()}");
+        Console.WriteLine("Summaries:");
+        foreach (JsonElement summary in conversation.GetProperty("summaries").EnumerateArray())
+        {
+            Console.WriteLine($"Text: {summary.GetProperty("text").GetString()}");
+            Console.WriteLine($"Aspect: {summary.GetProperty("aspect").GetString()}");
+        }
+        Console.WriteLine();
+    }
+}
+```
+
+## Asynchronous
+
+Using the same `data` definition above, you can make an asynchronous request by calling `AnalyzeConversationAsync`:
+
+```C# Snippet:AnalyzeConversationAsync_ConversationSummarization
+Operation<BinaryData> analyzeConversationOperation = await client.AnalyzeConversationAsync(WaitUntil.Started, RequestContent.Create(data));
+await analyzeConversationOperation.WaitForCompletionAsync();
+```