Add parameterized AI tool instances

src/Abstractions/CrestApps.Core.AI.Abstractions/Models/AICompletionContext.cs

@@ -63,6 +63,13 @@ public sealed class AICompletionContext
     /// </summary>
     public string[] AgentNames { get; set; }
 
+    /// <summary>
+    /// Gets or sets the configured tool instance identifiers available to this request. Each identifier
+    /// refers to an <c>AIToolInstance</c> that binds a developer-defined tool source to user-provided
+    /// settings and is surfaced to the model as a distinct function.
+    /// </summary>
+    public string[] ToolInstanceIds { get; set; }
+
     /// <summary>
     /// Gets or sets the MCP (Model Context Protocol) connection identifiers available to this request.
     /// </summary>

src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIProfileToolInstanceMetadata.cs

@@ -0,0 +1,13 @@
+namespace CrestApps.Core.AI.Tooling;
+
+/// <summary>
+/// Profile metadata that records which configured <see cref="AIToolInstance"/> entries are attached to
+/// an AI profile (or other tool-bearing resource). Stored in the resource's properties bag.
+/// </summary>
+public sealed class AIProfileToolInstanceMetadata
+{
+    /// <summary>
+    /// Gets or sets the identifiers of the configured tool instances available to the resource.
+    /// </summary>
+    public string[] InstanceIds { get; set; }
+}

src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstance.cs

@@ -0,0 +1,79 @@
+using CrestApps.Core.Models;
+using CrestApps.Core.Services;
+
+namespace CrestApps.Core.AI.Tooling;
+
+/// <summary>
+/// Represents a user-configured, model-invokable tool instance created from a registered
+/// <see cref="IAIToolInstanceSource"/> blueprint. Unlike a plain <c>AITool</c> whose arguments are
+/// always supplied by the model, a tool instance binds developer-defined behavior to user-provided
+/// settings (endpoints, credentials, headers, etc.) captured up front. The AI model still decides when
+/// to invoke the resulting function, but the user-provided settings are applied at invocation time.
+/// </summary>
+/// <remarks>
+/// The <see cref="SourceCatalogEntry.Source"/> property holds the registered name of the owning tool
+/// instance source, while <see cref="Name"/> is a unique technical name used to derive the function name
+/// exposed to the AI model. Multiple instances may be created from the same source, each with different
+/// settings and a distinct <see cref="Description"/> so the model can tell them apart.
+/// </remarks>
+public sealed class AIToolInstance : SourceCatalogEntry, INameAwareModel, IDisplayTextAwareModel, IModifiedUtcAwareModel, ICloneable<AIToolInstance>
+{
+    /// <summary>
+    /// Gets or sets the unique technical name for this tool instance. This value is the basis for the
+    /// function name exposed to the AI model, so it must be unique across all configured instances.
+    /// </summary>
+    public string Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the human-readable display text shown in management and selection surfaces.
+    /// </summary>
+    public string DisplayText { get; set; }
+
+    /// <summary>
+    /// Gets or sets the natural-language description presented to the AI model. This is the primary
+    /// signal the model uses to distinguish between multiple instances built from the same source, so it
+    /// should clearly explain what this specific instance does (for example, which API it calls).
+    /// </summary>
+    public string Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets the UTC timestamp when this instance was created.
+    /// </summary>
+    public DateTime CreatedUtc { get; set; }
+
+    /// <summary>
+    /// Gets or sets the UTC timestamp when this instance was last modified.
+    /// </summary>
+    public DateTime? ModifiedUtc { get; set; }
+
+    /// <summary>
+    /// Gets or sets the display name of the user that authored this instance.
+    /// </summary>
+    public string Author { get; set; }
+
+    /// <summary>
+    /// Gets or sets the identifier of the user that owns this instance.
+    /// </summary>
+    public string OwnerId { get; set; }
+
+    /// <summary>
+    /// Creates a shallow copy of this instance, sharing the same <see cref="ExtensibleEntity.Properties"/> reference.
+    /// </summary>
+    /// <returns>A new <see cref="AIToolInstance"/> with the same values.</returns>
+    public AIToolInstance Clone()
+    {
+        return new AIToolInstance
+        {
+            ItemId = ItemId,
+            Source = Source,
+            Name = Name,
+            DisplayText = DisplayText,
+            Description = Description,
+            CreatedUtc = CreatedUtc,
+            ModifiedUtc = ModifiedUtc,
+            Author = Author,
+            OwnerId = OwnerId,
+            Properties = Properties,
+        };
+    }
+}

src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceExtensions.cs

@@ -0,0 +1,63 @@
+namespace CrestApps.Core.AI.Tooling;
+
+/// <summary>
+/// Extension methods for <see cref="AIToolInstance"/>, including production of stable, model-safe
+/// function names so that multiple instances built from the same source are exposed to the AI model as
+/// distinct callable functions.
+/// </summary>
+public static class AIToolInstanceExtensions
+{
+    private const int MaxFunctionNameLength = 64;
+
+    /// <summary>
+    /// Builds the unique function name presented to the AI model for the supplied instance. The name is
+    /// derived from the instance's unique <see cref="AIToolInstance.Name"/> (falling back to its
+    /// identifier) and is sanitized to the characters allowed by chat-completion providers (letters,
+    /// digits, underscores, and hyphens), truncated to 64 characters.
+    /// </summary>
+    /// <param name="instance">The configured tool instance.</param>
+    /// <returns>A deterministic, provider-safe function name.</returns>
+    public static string GetFunctionName(this AIToolInstance instance)
+    {
+        ArgumentNullException.ThrowIfNull(instance);
+
+        var name = Sanitize(instance.Name);
+
+        if (string.IsNullOrEmpty(name))
+        {
+            name = Sanitize(instance.ItemId);
+        }
+
+        if (string.IsNullOrEmpty(name))
+        {
+            name = "tool_instance";
+        }
+
+        if (name.Length > MaxFunctionNameLength)
+        {
+            name = name[..MaxFunctionNameLength];
+        }
+
+        return name;
+    }
+
+    private static string Sanitize(string value)
+    {
+        if (string.IsNullOrEmpty(value))
+        {
+            return string.Empty;
+        }
+
+        var buffer = new char[value.Length];
+        var length = 0;
+
+        foreach (var c in value)
+        {
+            buffer[length++] = char.IsAsciiLetterOrDigit(c) || c == '_' || c == '-'
+                ? c
+                : '_';
+        }
+
+        return new string(buffer, 0, length);
+    }
+}

src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceSourceContext.cs

@@ -0,0 +1,43 @@
+using Microsoft.Extensions.AI;
+
+namespace CrestApps.Core.AI.Tooling;
+
+/// <summary>
+/// Carries the information required to materialize an <see cref="AITool"/> for a configured
+/// <see cref="AIToolInstance"/>. Passed to <see cref="IAIToolInstanceSource.CreateTool"/>.
+/// </summary>
+public sealed class AIToolInstanceSourceContext
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AIToolInstanceSourceContext"/> class.
+    /// </summary>
+    /// <param name="instance">The configured tool instance.</param>
+    /// <param name="functionName">The unique function name to expose to the AI model.</param>
+    /// <param name="description">The description to expose to the AI model.</param>
+    public AIToolInstanceSourceContext(AIToolInstance instance, string functionName, string description)
+    {
+        ArgumentNullException.ThrowIfNull(instance);
+        ArgumentException.ThrowIfNullOrEmpty(functionName);
+
+        Instance = instance;
+        FunctionName = functionName;
+        Description = description;
+    }
+
+    /// <summary>
+    /// Gets the configured tool instance whose settings should be bound to the produced tool.
+    /// </summary>
+    public AIToolInstance Instance { get; }
+
+    /// <summary>
+    /// Gets the unique function name to expose to the AI model. This is derived per instance so that
+    /// multiple instances of the same source surface as distinct callable functions.
+    /// </summary>
+    public string FunctionName { get; }
+
+    /// <summary>
+    /// Gets the description to expose to the AI model, taken from the instance so the model can
+    /// distinguish between instances of the same source.
+    /// </summary>
+    public string Description { get; }
+}

src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IAIToolInstanceSource.cs

@@ -0,0 +1,32 @@
+using Microsoft.Extensions.AI;
+
+namespace CrestApps.Core.AI.Tooling;
+
+/// <summary>
+/// A developer-authored, parameterized tool blueprint that end users configure one or more times as
+/// <see cref="AIToolInstance"/> catalog entries. A source is registered under a unique name (stored as
+/// the <see cref="CrestApps.Core.Models.SourceCatalogEntry.Source"/> of every <see cref="AIToolInstance"/>
+/// created from it) and is responsible for turning a configured instance into a concrete
+/// <see cref="AITool"/> whose behavior is bound to the user's settings.
+/// </summary>
+/// <remarks>
+/// Sources are registered with <c>AddAIToolInstanceSource&lt;TSource&gt;(name, configure)</c>, which
+/// records the source's display metadata (display name, description, category) in
+/// <c>AIOptions.ToolInstanceSources</c> and registers the behavior as a keyed service. A source
+/// typically ships a settings model that it persists in <see cref="AIToolInstance.Properties"/> (via
+/// <c>.Put()</c>/<c>.TryGet()</c>) and reads back inside the produced tool. The classic example is a
+/// generic "call any HTTP API" source where the user provides the endpoint, authentication, and
+/// headers, while the model only supplies the remaining open arguments (if any).
+/// </remarks>
+public interface IAIToolInstanceSource
+{
+    /// <summary>
+    /// Creates the concrete <see cref="AITool"/> that the AI model can invoke for the supplied
+    /// configured instance. Implementations must apply the instance's user-provided settings and use the
+    /// supplied <see cref="AIToolInstanceSourceContext.FunctionName"/> and
+    /// <see cref="AIToolInstanceSourceContext.Description"/> so the instance surfaces distinctly.
+    /// </summary>
+    /// <param name="context">The context describing the instance and the function metadata to expose.</param>
+    /// <returns>The tool to expose to the AI model, or <see langword="null"/> to skip this instance.</returns>
+    AITool CreateTool(AIToolInstanceSourceContext context);
+}

src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IToolRegistryProvider.cs

@@ -12,7 +12,7 @@ public interface IToolRegistryProvider
     /// Retrieves all tool entries available from this provider, scoped to the given context.
     /// </summary>
     /// <param name="context">The completion context containing configured tool names,
-    /// instance IDs, and MCP connection IDs that scope the returned tools.</param>
+    /// tool definition IDs, and MCP connection IDs that scope the returned tools.</param>
     /// <param name="cancellationToken">A token to cancel the operation.</param>
     /// <returns>A read-only list of tool registry entries from this provider.</returns>
     Task<IReadOnlyList<ToolRegistryEntry>> GetToolsAsync(

src/CrestApps.Core.Docs/docs/changelog/v1.0.0.md

@@ -111,3 +111,4 @@ description: Initial standalone release notes for the CrestApps.Core repository.
 - adds a dedicated hidden `fill_empty_tabular_cells` tool for the Tabular Data Agent so “replace every empty cell with X” requests run as one set-based update instead of the model composing hundreds of per-column statements, and broadens `generate_file` tabular misuse detection so conversational/question text like “Would you like me to generate…” cannot be written into `.xlsx` downloads
 - keeps hidden tools private to their owning profiles and agents across the shared MCP server handlers, so agent-only helpers such as the Tabular Data Agent SQL tools are no longer listed or callable as direct MCP tools
 - moves tabular workspace storage from in-memory SQLite to a file-based SQLite database stored alongside uploaded documents in a `data` folder, so workspace state persists across process restarts without artifact-store round-trips and reduces peak memory usage under high traffic; removes the singleton workspace cache, invalidation publisher interfaces, and cleanup background service in favor of creating a disposable workspace per tool call that opens and closes its own connection, with the document cleanup service and document event handler deleting the database file directly on session or document removal
+- adds parameterized AI tool instances so developers can author a tool blueprint once in code via the `IAIToolInstanceSource` interface (registered under a unique name with `AddAIToolInstanceSource<TSource>()`) and let users create multiple configured `AIToolInstance` entries of it, each supplying its own settings (endpoint, authentication, headers, …), a unique name, and a natural-language description up front instead of relying on the AI model to provide them; the model still decides when to invoke each instance, `ToolInstanceRegistryProvider` (a pluggable `IToolRegistryProvider`) surfaces every referenced instance as a distinctly named `AITool` so multiple instances built from the same source appear as separate functions to every client (OpenAI, Azure OpenAI, …), projects can register their own `IToolRegistryProvider` to add logic such as permission checks, ships a built-in `http-api-request` source that calls arbitrary HTTP APIs with data-protected credentials, persists instances through the `AIToolInstance` catalog on both YesSql and EntityCore, and includes full management UI plus AI profile attachment in the MVC and Blazor sample hosts