[TextAnalytics] Implemented ExtractiveSummarization input (#22791)

Co-authored-by: Mariana Rios Flores <[email protected]>

sdk/textanalytics/Azure.AI.TextAnalytics/api/Azure.AI.TextAnalytics.netstandard2.0.cs

@@ -250,6 +250,13 @@ internal ExtractKeyPhrasesResultCollection() : base (default(System.Collections.
         public string ModelVersion { get { throw null; } }
         public Azure.AI.TextAnalytics.TextDocumentBatchStatistics Statistics { get { throw null; } }
     }
+    public partial class ExtractSummaryAction
+    {
+        public ExtractSummaryAction() { }
+        public int? MaxSentenceCount { get { throw null; } set { } }
+        public string ModelVersion { get { throw null; } set { } }
+        public Azure.AI.TextAnalytics.SummarySentencesOrder? OrderBy { get { throw null; } set { } }
+    }
     public partial class HealthcareEntity
     {
         internal HealthcareEntity() { }
@@ -711,6 +718,11 @@ internal SentimentConfidenceScores() { }
         public double Neutral { get { throw null; } }
         public double Positive { get { throw null; } }
     }
+    public enum SummarySentencesOrder
+    {
+        Offset = 0,
+        Rank = 1,
+    }
     [System.Runtime.InteropServices.StructLayoutAttribute(System.Runtime.InteropServices.LayoutKind.Sequential)]
     public readonly partial struct TargetSentiment
     {
@@ -735,6 +747,7 @@ public TextAnalyticsActions() { }
         public System.Collections.Generic.IReadOnlyCollection<Azure.AI.TextAnalytics.AnalyzeSentimentAction> AnalyzeSentimentActions { get { throw null; } set { } }
         public string DisplayName { get { throw null; } set { } }
         public System.Collections.Generic.IReadOnlyCollection<Azure.AI.TextAnalytics.ExtractKeyPhrasesAction> ExtractKeyPhrasesActions { get { throw null; } set { } }
+        public System.Collections.Generic.IReadOnlyCollection<Azure.AI.TextAnalytics.ExtractSummaryAction> ExtractSummaryActions { get { throw null; } set { } }
         public System.Collections.Generic.IReadOnlyCollection<Azure.AI.TextAnalytics.RecognizeEntitiesAction> RecognizeEntitiesActions { get { throw null; } set { } }
         public System.Collections.Generic.IReadOnlyCollection<Azure.AI.TextAnalytics.RecognizeLinkedEntitiesAction> RecognizeLinkedEntitiesActions { get { throw null; } set { } }
         public System.Collections.Generic.IReadOnlyCollection<Azure.AI.TextAnalytics.RecognizePiiEntitiesAction> RecognizePiiEntitiesActions { get { throw null; } set { } }
@@ -811,13 +824,14 @@ public TextAnalyticsClient(System.Uri endpoint, Azure.Core.TokenCredential crede
     }
     public partial class TextAnalyticsClientOptions : Azure.Core.ClientOptions
     {
-        public TextAnalyticsClientOptions(Azure.AI.TextAnalytics.TextAnalyticsClientOptions.ServiceVersion version = Azure.AI.TextAnalytics.TextAnalyticsClientOptions.ServiceVersion.V3_1) { }
+        public TextAnalyticsClientOptions(Azure.AI.TextAnalytics.TextAnalyticsClientOptions.ServiceVersion version = Azure.AI.TextAnalytics.TextAnalyticsClientOptions.ServiceVersion.V3_2_Preview_1) { }
         public string DefaultCountryHint { get { throw null; } set { } }
         public string DefaultLanguage { get { throw null; } set { } }
         public enum ServiceVersion
         {
             V3_0 = 1,
             V3_1 = 2,
+            V3_2_Preview_1 = 3,
         }
     }
     [System.Runtime.InteropServices.StructLayoutAttribute(System.Runtime.InteropServices.LayoutKind.Sequential)]

sdk/textanalytics/Azure.AI.TextAnalytics/src/ExtractSummaryAction.cs

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Azure.AI.TextAnalytics
+{
+    /// <summary>
+    /// Configurations that allow callers to specify details about how to execute
+    /// an Extractive Text Summarization action in a set of documents.
+    /// For example, set the model version, specify the order in which extracted
+    /// sentences are returned, and more.
+    /// </summary>
+    public class ExtractSummaryAction
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ExtractSummaryAction"/>
+        /// class which allows callers to specify details about how to execute
+        /// an Extractive Text Summarization action in a set of documents.
+        /// For example, set the model version, specify the order in which extracted
+        /// sentences are returned, and more.
+        /// </summary>
+        public ExtractSummaryAction()
+        {
+        }
+
+        /// <summary>
+        /// Gets or sets a value that, if set, indicates the version of the text
+        /// analytics model that will be used to generate the result.  For supported
+        /// model versions, see operation-specific documentation, for example:
+        /// <see href="https://docs.microsoft.com/azure/cognitive-services/text-analytics/concepts/model-versioning#available-versions"/>.
+        /// </summary>
+        public string ModelVersion { get; set; }
+
+        /// <summary>
+        /// If set, specifies the maximum limit of sentences returned in the result. Defaults to 3.
+        /// </summary>
+        public int? MaxSentenceCount { get; set; }
+
+        /// <summary>
+        /// If set, specifies the order in which the extracted sentences will be returned in the result. Use
+        /// <see cref="SummarySentencesOrder.Offset"/> to keep the original order in which the sentences appear
+        /// in the input. Use <see cref="SummarySentencesOrder.Rank"/> to order them according to their relevance
+        /// to the document input, as decided by the service. Defaults to <see cref="SummarySentencesOrder.Offset"/>.
+        /// </summary>
+        public SummarySentencesOrder? OrderBy { get; set; }
+    }
+}

sdk/textanalytics/Azure.AI.TextAnalytics/src/SummarySentencesOrder.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Azure.Core;
+
+namespace Azure.AI.TextAnalytics
+{
+    /// <summary>
+    /// The order in which extracted sentences will be returned on extractive text summarization.
+    /// </summary>
+    [CodeGenModel("ExtractiveSummarizationTaskParametersSortBy")]
+    public enum SummarySentencesOrder
+    {
+        /// <summary>
+        /// Keeps the original order in which the sentences appear in the input.
+        /// </summary>
+        Offset,
+
+        /// <summary>
+        /// Orders sentences according to their relevance to the document input, as decided by the service.
+        /// </summary>
+        Rank
+    }
+}

sdk/textanalytics/Azure.AI.TextAnalytics/src/TextAnalyticsActions.cs

@@ -51,5 +51,14 @@ public TextAnalyticsActions()
         /// Note that currently only one <see cref="AnalyzeSentimentAction"/> is supported.
         /// </summary>
         public IReadOnlyCollection<AnalyzeSentimentAction> AnalyzeSentimentActions { get; set; }
+
+        /// <summary>
+        /// The set of <see cref="ExtractSummaryAction"/> that will get executed on the input documents.
+        /// Note that currently only one <see cref="ExtractSummaryAction"/> is supported.
+        /// </summary>
+        /// <remarks>
+        /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_2_Preview_1"/> and up.
+        /// </remarks>
+        public IReadOnlyCollection<ExtractSummaryAction> ExtractSummaryActions { get; set; }
     }
 }

sdk/textanalytics/Azure.AI.TextAnalytics/src/TextAnalyticsClient.cs

@@ -2470,6 +2470,10 @@ private static JobManifestTasks CreateTasks(TextAnalyticsActions actions)
             {
                 tasks.SentimentAnalysisTasks = Transforms.ConvertFromAnalyzeSentimentActionsToTasks(actions.AnalyzeSentimentActions);
             }
+            if (actions.ExtractSummaryActions != null)
+            {
+                tasks.ExtractiveSummarizationTasks = Transforms.ConvertFromExtractSummaryActionsToTasks(actions.ExtractSummaryActions);
+            }
             return tasks;
         }
 
@@ -2479,7 +2483,8 @@ private static void ValidateActions(TextAnalyticsActions actions)
                 actions.RecognizeEntitiesActions?.Count > 1 ||
                 actions.RecognizeLinkedEntitiesActions?.Count > 1 ||
                 actions.ExtractKeyPhrasesActions?.Count > 1 ||
-                actions.AnalyzeSentimentActions?.Count > 1)
+                actions.AnalyzeSentimentActions?.Count > 1 ||
+                actions.ExtractSummaryActions?.Count > 1)
             {
                 throw new ArgumentException("Multiple of the same action is not currently supported.");
             }

sdk/textanalytics/Azure.AI.TextAnalytics/src/TextAnalyticsClientOptions.cs

@@ -16,7 +16,7 @@ public class TextAnalyticsClientOptions : ClientOptions
         /// <summary>
         /// The latest service version supported by this client library.
         /// </summary>
-        internal const ServiceVersion LatestVersion = ServiceVersion.V3_1;
+        internal const ServiceVersion LatestVersion = ServiceVersion.V3_2_Preview_1;
 
         /// <summary>
         /// The versions of the Text Analytics service supported by this client library.
@@ -33,6 +33,11 @@ public enum ServiceVersion
             /// Version 3.1
             /// </summary>
             V3_1 = 2,
+
+            /// <summary>
+            /// Version 3.2-preview.1
+            /// </summary>
+            V3_2_Preview_1 = 3
 #pragma warning restore CA1707 // Identifiers should not contain underscores
         }
 
@@ -75,6 +80,7 @@ internal static string GetVersionString(ServiceVersion version)
             {
                 ServiceVersion.V3_0 => "v3.0",
                 ServiceVersion.V3_1 => "v3.1",
+                ServiceVersion.V3_2_Preview_1 => "v3.1",
 
                 _ => throw new ArgumentException($"Version {version} not supported."),
             };

sdk/textanalytics/Azure.AI.TextAnalytics/src/Transforms.cs

@@ -393,6 +393,20 @@ internal static SentimentAnalysisTask ConvertToSentimentAnalysisTask(AnalyzeSent
             };
         }
 
+        internal static ExtractiveSummarizationTask ConvertToExtractiveSummarizationTask(ExtractSummaryAction action)
+        {
+            return new ExtractiveSummarizationTask()
+            {
+                Parameters = new ExtractiveSummarizationTaskParameters()
+                {
+                    ModelVersion = action.ModelVersion,
+                    StringIndexType = Constants.DefaultStringIndexType,
+                    SentenceCount = action.MaxSentenceCount,
+                    SortBy = action.OrderBy
+                }
+            };
+        }
+
         internal static IList<EntityLinkingTask> ConvertFromRecognizeLinkedEntitiesActionsToTasks(IReadOnlyCollection<RecognizeLinkedEntitiesAction> recognizeLinkedEntitiesActions)
         {
             List<EntityLinkingTask> list = new List<EntityLinkingTask>();
@@ -453,6 +467,18 @@ internal static IList<SentimentAnalysisTask> ConvertFromAnalyzeSentimentActionsT
             return list;
         }
 
+        internal static IList<ExtractiveSummarizationTask> ConvertFromExtractSummaryActionsToTasks(IReadOnlyCollection<ExtractSummaryAction> extractSummaryActions)
+        {
+            List<ExtractiveSummarizationTask> list = new List<ExtractiveSummarizationTask>();
+
+            foreach (ExtractSummaryAction action in extractSummaryActions)
+            {
+                list.Add(ConvertToExtractiveSummarizationTask(action));
+            }
+
+            return list;
+        }
+
         private static string[] parseActionErrorTarget(string targetReference)
         {
             if (string.IsNullOrEmpty(targetReference))

sdk/textanalytics/Azure.AI.TextAnalytics/tests/AnalyzeOperationMockTests.cs

@@ -707,6 +707,40 @@ public void AnalyzeOperationAnalyzeSentimentWithTwoActions()
 
         #endregion Analyze sentiment
 
+        #region Extract summary
+
+        [Test]
+        public void AnalyzeOperationExtractsSummaryWithTwoActions()
+        {
+            var mockResponse = new MockResponse(202);
+            mockResponse.AddHeader(new HttpHeader("Operation-Location", "something/jobs/2a96a91f-7edf-4931-a880-3fdee1d56f15"));
+
+            var mockTransport = new MockTransport(new[] { mockResponse, mockResponse });
+            var client = CreateTestClient(mockTransport);
+
+            var documents = new List<string>
+            {
+                "Elon Musk is the CEO of SpaceX and Tesla."
+            };
+
+            TextAnalyticsActions batchActions = new()
+            {
+                ExtractSummaryActions = new List<ExtractSummaryAction>()
+                {
+                    new ExtractSummaryAction(),
+                    new ExtractSummaryAction()
+                    {
+                        ModelVersion = "InvalidVersion"
+                    }
+                },
+            };
+
+            ArgumentException ex = Assert.ThrowsAsync<ArgumentException>(async () => await client.StartAnalyzeActionsAsync(documents, batchActions));
+            Assert.AreEqual("Multiple of the same action is not currently supported.", ex.Message);
+        }
+
+        #endregion Extract summary
+
         [Test]
         public async Task AnalyzeOperationWithActionsError()
         {