Tool reduction (#6781)

Author: MackinnonBuck

eng/packages/General.props

@@ -29,6 +29,7 @@
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
     <PackageVersion Include="System.ComponentModel.Annotations" Version="5.0.0" />
     <PackageVersion Include="System.Memory" Version="4.5.5" />
+    <PackageVersion Include="System.Numerics.Tensors" Version="$(SystemNumericsTensorsVersion)" />
     <PackageVersion Include="System.Private.Uri" Version="4.3.2" />
     <PackageVersion Include="System.Runtime.Caching" Version="$(SystemRuntimeCachingVersion)" />
     <PackageVersion Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.0" />

eng/packages/TestOnly.props

@@ -21,7 +21,6 @@
     <PackageVersion Include="Polly.Testing" Version="8.4.2" />
     <PackageVersion Include="StrongNamer" Version="0.2.5" />
     <PackageVersion Include="System.Configuration.ConfigurationManager" Version="$(SystemConfigurationConfigurationManagerVersion)" />
-    <PackageVersion Include="System.Numerics.Tensors" Version="$(SystemNumericsTensorsVersion)" />
     <PackageVersion Include="Verify.Xunit" Version="28.15.0" />
     <PackageVersion Include="Xunit.Combinatorial" Version="1.6.24" />
     <PackageVersion Include="xunit.extensibility.execution" Version="$(XUnitVersion)" />

src/Libraries/Microsoft.Extensions.AI.Abstractions/ToolReduction/IToolReductionStrategy.cs

@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a strategy capable of selecting a reduced set of tools for a chat request.
+/// </summary>
+/// <remarks>
+/// A tool reduction strategy is invoked prior to sending a request to an underlying <see cref="IChatClient"/>,
+/// enabling scenarios where a large tool catalog must be trimmed to fit provider limits or to improve model
+/// tool selection quality.
+/// <para>
+/// The implementation should return a non-<see langword="null"/> enumerable. Returning the original
+/// <see cref="ChatOptions.Tools"/> instance indicates no change. Returning a different enumerable indicates
+/// the caller may replace the existing tool list.
+/// </para>
+/// </remarks>
+[Experimental("MEAI001")]
+public interface IToolReductionStrategy
+{
+    /// <summary>
+    /// Selects the tools that should be included for a specific request.
+    /// </summary>
+    /// <param name="messages">The chat messages for the request. This is an <see cref="IEnumerable{T}"/> to avoid premature materialization.</param>
+    /// <param name="options">The chat options for the request (may be <see langword="null"/>).</param>
+    /// <param name="cancellationToken">A token to observe cancellation.</param>
+    /// <returns>
+    /// A (possibly reduced) enumerable of <see cref="AITool"/> instances. Must never be <see langword="null"/>.
+    /// Returning the same instance referenced by <paramref name="options"/>.<see cref="ChatOptions.Tools"/> signals no change.
+    /// </returns>
+    Task<IEnumerable<AITool>> SelectToolsForRequestAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options,
+        CancellationToken cancellationToken = default);
+}

src/Libraries/Microsoft.Extensions.AI/Microsoft.Extensions.AI.csproj

@@ -44,6 +44,7 @@
     <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
+    <PackageReference Include="System.Numerics.Tensors" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">

src/Libraries/Microsoft.Extensions.AI/ToolReduction/ChatClientBuilderToolReductionExtensions.cs

@@ -0,0 +1,32 @@
+// 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.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Extension methods for adding tool reduction middleware to a chat client pipeline.</summary>
+[Experimental("MEAI001")]
+public static class ChatClientBuilderToolReductionExtensions
+{
+    /// <summary>
+    /// Adds tool reduction to the chat client pipeline using the specified <paramref name="strategy"/>.
+    /// </summary>
+    /// <param name="builder">The chat client builder.</param>
+    /// <param name="strategy">The reduction strategy.</param>
+    /// <returns>The original builder for chaining.</returns>
+    /// <exception cref="ArgumentNullException">If <paramref name="builder"/> or <paramref name="strategy"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// This should typically appear in the pipeline before function invocation middleware so that only the reduced tools
+    /// are exposed to the underlying provider.
+    /// </remarks>
+    public static ChatClientBuilder UseToolReduction(this ChatClientBuilder builder, IToolReductionStrategy strategy)
+    {
+        _ = Throw.IfNull(builder);
+        _ = Throw.IfNull(strategy);
+
+        return builder.Use(inner => new ToolReducingChatClient(inner, strategy));
+    }
+}