Introduce set of built-in Enrichers

src/Libraries/Microsoft.Extensions.DataIngestion/Microsoft.Extensions.DataIngestion.csproj

@@ -18,6 +18,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="System.Collections.Immutable" Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'" />
     <PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" />
   </ItemGroup>
 

src/Libraries/Microsoft.Extensions.DataIngestion/Processors/ClassificationEnricher.cs

@@ -0,0 +1,132 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Frozen;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.DataIngestion;
+
+/// <summary>
+/// Enriches document chunks with a classification label based on their content.
+/// </summary>
+/// <remarks>This class uses a chat-based language model to analyze the content of document chunks and assign a
+/// single, most relevant classification label. The classification is performed using a predefined set of classes, with
+/// an optional fallback class for cases where no suitable classification can be determined.</remarks>
+public sealed class ClassificationEnricher : IngestionChunkProcessor<string>
+{
+    private readonly IChatClient _chatClient;
+    private readonly ChatOptions? _chatOptions;
+    private readonly FrozenSet<string> _predefinedClasses;
+    private readonly ChatMessage _systemPrompt;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ClassificationEnricher"/> class.
+    /// </summary>
+    /// <param name="chatClient">The chat client used for classification.</param>
+    /// <param name="predefinedClasses">The set of predefined classification classes.</param>
+    /// <param name="chatOptions">Options for the chat client.</param>
+    /// <param name="fallbackClass">The fallback class to use when no suitable classification is found. When not provided, it defaults to "Unknown".</param>
+    public ClassificationEnricher(IChatClient chatClient, ReadOnlySpan<string> predefinedClasses,
+        ChatOptions? chatOptions = null, string? fallbackClass = null)
+    {
+        _chatClient = Throw.IfNull(chatClient);
+        _chatOptions = chatOptions;
+        if (string.IsNullOrWhiteSpace(fallbackClass))
+        {
+            fallbackClass = "Unknown";
+        }
+
+        _predefinedClasses = CreatePredefinedSet(predefinedClasses, fallbackClass!);
+        _systemPrompt = CreateSystemPrompt(predefinedClasses, fallbackClass!);
+    }
+
+    /// <summary>
+    /// Gets the metadata key used to store the classification.
+    /// </summary>
+    public static string MetadataKey => "classification";
+
+    /// <inheritdoc />
+    public override async IAsyncEnumerable<IngestionChunk<string>> ProcessAsync(IAsyncEnumerable<IngestionChunk<string>> chunks,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(chunks);
+
+        await foreach (IngestionChunk<string> chunk in chunks.WithCancellation(cancellationToken))
+        {
+            var response = await _chatClient.GetResponseAsync(
+            [
+                _systemPrompt,
+                new(ChatRole.User, chunk.Content)
+            ], _chatOptions, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+            chunk.Metadata[MetadataKey] = _predefinedClasses.Contains(response.Text)
+                ? response.Text
+                : throw new InvalidOperationException($"Classification returned an unexpected class: '{response.Text}'.");
+
+            yield return chunk;
+        }
+    }
+
+    private static FrozenSet<string> CreatePredefinedSet(ReadOnlySpan<string> predefinedClasses, string fallbackClass)
+    {
+        if (predefinedClasses.Length == 0)
+        {
+            Throw.ArgumentException(nameof(predefinedClasses), "Predefined classes must be provided.");
+        }
+
+        HashSet<string> predefinedClassesSet = new(StringComparer.Ordinal) { fallbackClass };
+        foreach (string predefinedClass in predefinedClasses)
+        {
+#if NET
+            if (predefinedClass.Contains(',', StringComparison.Ordinal))
+#else
+            if (predefinedClass.IndexOf(',') >= 0)
+#endif
+            {
+                Throw.ArgumentException(nameof(predefinedClasses), $"Predefined class '{predefinedClass}' must not contain ',' character.");
+            }
+
+            if (!predefinedClassesSet.Add(predefinedClass))
+            {
+                if (predefinedClass.Equals(fallbackClass, StringComparison.Ordinal))
+                {
+                    Throw.ArgumentException(nameof(predefinedClasses), $"Fallback class '{fallbackClass}' must not be one of the predefined classes.");
+                }
+
+                Throw.ArgumentException(nameof(predefinedClasses), $"Duplicate class found: '{predefinedClass}'.");
+            }
+        }
+
+        return predefinedClassesSet.ToFrozenSet();
+    }
+
+    private static ChatMessage CreateSystemPrompt(ReadOnlySpan<string> predefinedClasses, string fallbackClass)
+    {
+        StringBuilder sb = new("You are a classification expert. Analyze the given text and assign a single, most relevant class. Use only the following predefined classes: ");
+
+#if NET9_0_OR_GREATER
+        sb.AppendJoin(", ", predefinedClasses!);
+#else
+#pragma warning disable IDE0058 // Expression value is never used
+        for (int i = 0; i < predefinedClasses.Length; i++)
+        {
+            sb.Append(predefinedClasses[i]);
+            if (i < predefinedClasses.Length - 1)
+            {
+                sb.Append(", ");
+            }
+        }
+#endif
+        sb.Append(" and return ").Append(fallbackClass).Append(" when unable to classify.");
+#pragma warning restore IDE0058 // Expression value is never used
+
+        return new(ChatRole.System, sb.ToString());
+    }
+}

src/Libraries/Microsoft.Extensions.DataIngestion/Processors/ImageAlternativeTextEnricher.cs

@@ -0,0 +1,74 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.DataIngestion;
+
+/// <summary>
+/// Enriches <see cref="IngestionDocumentImage"/> elements with alternative text using an AI service,
+/// so the generated embeddings can include the image content information.
+/// </summary>
+public sealed class ImageAlternativeTextEnricher : IngestionDocumentProcessor
+{
+    private readonly IChatClient _chatClient;
+    private readonly ChatOptions? _chatOptions;
+    private readonly ChatMessage _systemPrompt;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ImageAlternativeTextEnricher"/> class.
+    /// </summary>
+    /// <param name="chatClient">The chat client used to get responses for generating alternative text.</param>
+    /// <param name="chatOptions">Options for the chat client.</param>
+    public ImageAlternativeTextEnricher(IChatClient chatClient, ChatOptions? chatOptions = null)
+    {
+        _chatClient = Throw.IfNull(chatClient);
+        _chatOptions = chatOptions;
+        _systemPrompt = new(ChatRole.System, "Write a detailed alternative text for this image with less than 50 words.");
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IngestionDocument> ProcessAsync(IngestionDocument document, CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(document);
+
+        foreach (var element in document.EnumerateContent())
+        {
+            if (element is IngestionDocumentImage image)
+            {
+                await ProcessAsync(image, cancellationToken).ConfigureAwait(false);
+            }
+            else if (element is IngestionDocumentTable table)
+            {
+                foreach (var cell in table.Cells)
+                {
+                    if (cell is IngestionDocumentImage cellImage)
+                    {
+                        await ProcessAsync(cellImage, cancellationToken).ConfigureAwait(false);
+                    }
+                }
+            }
+        }
+
+        return document;
+    }
+
+    private async Task ProcessAsync(IngestionDocumentImage image, CancellationToken cancellationToken)
+    {
+        if (image.Content.HasValue && !string.IsNullOrEmpty(image.MediaType)
+            && string.IsNullOrEmpty(image.AlternativeText))
+        {
+            var response = await _chatClient.GetResponseAsync(
+            [
+                _systemPrompt,
+                new(ChatRole.User, [new DataContent(image.Content.Value, image.MediaType!)])
+            ], _chatOptions, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+            image.AlternativeText = response.Text;
+        }
+    }
+}

src/Libraries/Microsoft.Extensions.DataIngestion/Processors/KeywordEnricher.cs

@@ -0,0 +1,160 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Frozen;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.DataIngestion;
+
+/// <summary>
+/// Enriches chunks with keyword extraction using an AI chat model.
+/// </summary>
+/// <remarks>
+/// It adds "keywords" metadata to each chunk. It's an array of strings representing the extracted keywords.
+/// </remarks>
+public sealed class KeywordEnricher : IngestionChunkProcessor<string>
+{
+    private const int DefaultMaxKeywords = 5;
+#if NET
+    private static readonly System.Buffers.SearchValues<char> _illegalCharacters = System.Buffers.SearchValues.Create([';', ',']);
+#else
+    private static readonly char[] _illegalCharacters = [';', ','];
+#endif
+    private readonly IChatClient _chatClient;
+    private readonly ChatOptions? _chatOptions;
+    private readonly FrozenSet<string>? _predefinedKeywords;
+    private readonly ChatMessage _systemPrompt;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="KeywordEnricher"/> class.
+    /// </summary>
+    /// <param name="chatClient">The chat client used for keyword extraction.</param>
+    /// <param name="predefinedKeywords">The set of predefined keywords for extraction.</param>
+    /// <param name="chatOptions">Options for the chat client.</param>
+    /// <param name="maxKeywords">The maximum number of keywords to extract. When not provided, it defaults to 5.</param>
+    /// <param name="confidenceThreshold">The confidence threshold for keyword inclusion. When not provided, it defaults to 0.7.</param>
+    /// <remarks>
+    /// If no predefined keywords are provided, the model will extract keywords based on the content alone.
+    /// Such results may vary more significantly between different AI models.
+    /// </remarks>
+    public KeywordEnricher(IChatClient chatClient, ReadOnlySpan<string> predefinedKeywords,
+        ChatOptions? chatOptions = null, int? maxKeywords = null, double? confidenceThreshold = null)
+    {
+        _chatClient = Throw.IfNull(chatClient);
+        _chatOptions = chatOptions;
+        _predefinedKeywords = CreatePredfinedKeywords(predefinedKeywords);
+
+        double threshold = confidenceThreshold.HasValue
+            ? Throw.IfOutOfRange(confidenceThreshold.Value, 0.0, 1.0, nameof(confidenceThreshold))
+            : 0.7;
+        int keywordsCount = maxKeywords.HasValue
+            ? Throw.IfLessThanOrEqual(maxKeywords.Value, 0, nameof(maxKeywords))
+            : DefaultMaxKeywords;
+        _systemPrompt = CreateSystemPrompt(keywordsCount, predefinedKeywords, threshold);
+    }
+
+    /// <summary>
+    /// Gets the metadata key used to store the keywords.
+    /// </summary>
+    public static string MetadataKey => "keywords";
+
+    /// <inheritdoc/>
+    public override async IAsyncEnumerable<IngestionChunk<string>> ProcessAsync(IAsyncEnumerable<IngestionChunk<string>> chunks,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(chunks);
+
+        await foreach (IngestionChunk<string> chunk in chunks.WithCancellation(cancellationToken))
+        {
+            // Structured response is not used here because it's not part of Microsoft.Extensions.AI.Abstractions.
+            var response = await _chatClient.GetResponseAsync(
+            [
+                _systemPrompt,
+                new(ChatRole.User, chunk.Content)
+            ], _chatOptions, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+#pragma warning disable EA0009 // Use 'System.MemoryExtensions.Split' for improved performance
+            string[] keywords = response.Text.Split(';');
+            if (_predefinedKeywords is not null)
+            {
+                foreach (var keyword in keywords)
+                {
+                    if (!_predefinedKeywords.Contains(keyword))
+                    {
+                        throw new InvalidOperationException($"The extracted keyword '{keyword}' is not in the predefined keywords list.");
+                    }
+                }
+            }
+
+            chunk.Metadata[MetadataKey] = keywords;
+
+            yield return chunk;
+        }
+    }
+
+    private static FrozenSet<string>? CreatePredfinedKeywords(ReadOnlySpan<string> predefinedKeywords)
+    {
+        if (predefinedKeywords.Length == 0)
+        {
+            return null;
+        }
+
+        HashSet<string> result = new(StringComparer.Ordinal);
+        foreach (string keyword in predefinedKeywords)
+        {
+#if NET
+            if (keyword.AsSpan().ContainsAny(_illegalCharacters))
+#else
+            if (keyword.IndexOfAny(_illegalCharacters) >= 0)
+#endif
+            {
+                Throw.ArgumentException(nameof(predefinedKeywords), $"Predefined keyword '{keyword}' contains an invalid character (';' or ',').");
+            }
+
+            if (!result.Add(keyword))
+            {
+                Throw.ArgumentException(nameof(predefinedKeywords), $"Duplicate keyword found: '{keyword}'");
+            }
+        }
+
+        return result.ToFrozenSet(StringComparer.Ordinal);
+    }
+
+    private static ChatMessage CreateSystemPrompt(int maxKeywords, ReadOnlySpan<string> predefinedKeywords, double confidenceThreshold)
+    {
+        StringBuilder sb = new($"You are a keyword extraction expert. Analyze the given text and extract up to {maxKeywords} most relevant keywords. ");
+
+        if (predefinedKeywords.Length > 0)
+        {
+#pragma warning disable IDE0058 // Expression value is never used
+            sb.Append("Focus on extracting keywords from the following predefined list: ");
+#if NET9_0_OR_GREATER
+            sb.AppendJoin(", ", predefinedKeywords!);
+#else
+            for (int i = 0; i < predefinedKeywords.Length; i++)
+            {
+                sb.Append(predefinedKeywords[i]);
+                if (i < predefinedKeywords.Length - 1)
+                {
+                    sb.Append(", ");
+                }
+            }
+#endif
+
+            sb.Append(". ");
+        }
+
+        sb.Append("Exclude keywords with confidence score below ").Append(confidenceThreshold).Append('.');
+        sb.Append(" Return just the keywords separated with ';'.");
+#pragma warning restore IDE0058 // Expression value is never used
+
+        return new(ChatRole.System, sb.ToString());
+    }
+}