diff --git a/src/Abstractions/CrestApps.Core.AI.Abstractions/Models/AICompletionContext.cs b/src/Abstractions/CrestApps.Core.AI.Abstractions/Models/AICompletionContext.cs index 34474e4e..af316ff2 100644 --- a/src/Abstractions/CrestApps.Core.AI.Abstractions/Models/AICompletionContext.cs +++ b/src/Abstractions/CrestApps.Core.AI.Abstractions/Models/AICompletionContext.cs @@ -63,6 +63,13 @@ public sealed class AICompletionContext /// public string[] AgentNames { get; set; } + /// + /// Gets or sets the configured tool instance names available to this request. Each name refers to an + /// AIToolInstance that binds a developer-defined tool source to user-provided settings and is + /// surfaced to the model as a distinct function. + /// + public string[] ToolInstanceNames { get; set; } + /// /// Gets or sets the MCP (Model Context Protocol) connection identifiers available to this request. /// diff --git a/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstance.cs b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstance.cs new file mode 100644 index 00000000..f7f1bfad --- /dev/null +++ b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstance.cs @@ -0,0 +1,74 @@ +using CrestApps.Core.Models; +using CrestApps.Core.Services; + +namespace CrestApps.Core.AI.Tooling; + +/// +/// Represents a user-configured, model-invokable tool instance created from a registered +/// blueprint. Unlike a plain AITool 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. +/// +/// +/// The property holds the registered name of the owning tool +/// instance source, while 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 so the model can tell them apart. +/// +public sealed class AIToolInstance : SourceCatalogEntry, INameAwareModel, IModifiedUtcAwareModel, ICloneable +{ + /// + /// 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. + /// + public string Name { get; set; } + + /// + /// 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). + /// + public string Description { get; set; } + + /// + /// Gets or sets the UTC timestamp when this instance was created. + /// + public DateTime CreatedUtc { get; set; } + + /// + /// Gets or sets the UTC timestamp when this instance was last modified. + /// + public DateTime? ModifiedUtc { get; set; } + + /// + /// Gets or sets the display name of the user that authored this instance. + /// + public string Author { get; set; } + + /// + /// Gets or sets the identifier of the user that owns this instance. + /// + public string OwnerId { get; set; } + + /// + /// Creates a deep copy of this instance. The dictionary is + /// cloned so mutations on the copy (for example caching an OAuth token) never leak back to the original. + /// + /// A new with the same values. + public AIToolInstance Clone() + { + return new AIToolInstance + { + ItemId = ItemId, + Source = Source, + Name = Name, + Description = Description, + CreatedUtc = CreatedUtc, + ModifiedUtc = ModifiedUtc, + Author = Author, + OwnerId = OwnerId, + Properties = Properties?.Clone() ?? new Dictionary(StringComparer.OrdinalIgnoreCase), + }; + } +} diff --git a/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceExtensions.cs b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceExtensions.cs new file mode 100644 index 00000000..7d054fcb --- /dev/null +++ b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceExtensions.cs @@ -0,0 +1,96 @@ +using System.Security.Cryptography; +using System.Text; + +namespace CrestApps.Core.AI.Tooling; + +/// +/// Extension methods for , 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. +/// +public static class AIToolInstanceExtensions +{ + private const int MaxFunctionNameLength = 64; + private const int HashSuffixLength = 8; + + /// + /// The namespace prefix applied to every tool-instance function name. User-configured instances are + /// named from arbitrary user input, whereas tools registered in code via AddCoreAITool are + /// surfaced to the model under their bare registered name. Prefixing every instance function name + /// guarantees a user-chosen instance name can never collide with a code-registered tool name in the + /// single function namespace the AI model sees. + /// + public const string FunctionNamePrefix = "tool_instance_"; + + /// + /// Builds the unique function name presented to the AI model for the supplied instance. The name is + /// derived from the instance's unique (falling back to its + /// identifier), sanitized to the characters allowed by chat-completion providers (letters, digits, + /// underscores, and hyphens), prefixed with so it can never collide + /// with a code-registered tool name, and capped at 64 characters. When sanitizing or truncating would + /// change the value, a short deterministic hash of the original unique name is appended so two distinct + /// instance names can never collapse to the same function name. + /// + /// The configured tool instance. + /// A deterministic, provider-safe, collision-resistant function name. + public static string GetFunctionName(this AIToolInstance instance) + { + ArgumentNullException.ThrowIfNull(instance); + + var original = !string.IsNullOrEmpty(instance.Name) + ? instance.Name + : instance.ItemId; + + var name = Sanitize(original); + + if (string.IsNullOrEmpty(name)) + { + return FunctionNamePrefix + ComputeShortHash(original ?? string.Empty); + } + + var maxBaseLength = MaxFunctionNameLength - FunctionNamePrefix.Length; + var isLossy = !string.Equals(name, original, StringComparison.Ordinal); + + if (isLossy || name.Length > maxBaseLength) + { + var suffix = "_" + ComputeShortHash(original); + var maxTruncatedLength = maxBaseLength - suffix.Length; + + if (name.Length > maxTruncatedLength) + { + name = name[..maxTruncatedLength]; + } + + name += suffix; + } + + return FunctionNamePrefix + 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); + } + + private static string ComputeShortHash(string value) + { + var hash = SHA256.HashData(Encoding.UTF8.GetBytes(value)); + + return Convert.ToHexStringLower(hash)[..HashSuffixLength]; + } +} diff --git a/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceMetadata.cs b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceMetadata.cs new file mode 100644 index 00000000..f0fe9eb5 --- /dev/null +++ b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/AIToolInstanceMetadata.cs @@ -0,0 +1,15 @@ +namespace CrestApps.Core.AI.Tooling; + +/// +/// Metadata that records which configured entries are attached to a +/// tool-bearing resource (for example an AI profile or a chat interaction). Instances are referenced by +/// their unique so the reference stays stable and human-readable. +/// Stored in the resource's properties bag. +/// +public sealed class AIToolInstanceMetadata +{ + /// + /// Gets or sets the unique names of the configured tool instances available to the resource. + /// + public string[] ToolInstanceNames { get; set; } +} diff --git a/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IAIToolInstanceSource.cs b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IAIToolInstanceSource.cs new file mode 100644 index 00000000..ba8ad1d1 --- /dev/null +++ b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IAIToolInstanceSource.cs @@ -0,0 +1,35 @@ +using Microsoft.Extensions.AI; + +namespace CrestApps.Core.AI.Tooling; + +/// +/// A developer-authored, parameterized tool blueprint that end users configure one or more times as +/// catalog entries. A source is registered under a unique name (stored as +/// the of every +/// created from it) and is responsible for turning a configured instance into a concrete +/// whose behavior is bound to the user's settings. +/// +/// +/// Sources are registered with AddSource<TSource>(name, configure) on the tool instances +/// builder, which records the source's display metadata (display name, description, category) in +/// AIOptions.ToolInstanceSources and registers the behavior as a keyed service. The registration +/// key is the source name, so there is no need for the source to carry its own name — the same key is +/// used to resolve the source for an instance via its value. A source +/// typically ships a settings model that it persists in (via +/// .Put()/.TryGet()) 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). +/// +public interface IAIToolInstanceSource +{ + /// + /// Creates the concrete that the AI model can invoke for the supplied configured + /// instance. Implementations must apply the instance's user-provided settings and derive the + /// model-facing function name and description from the instance (via + /// and ) + /// so multiple instances of the same source surface as distinct callable functions. + /// + /// The configured tool instance whose settings should be bound to the produced tool. + /// The tool to expose to the AI model, or to skip this instance. + AITool CreateTool(AIToolInstance instance); +} diff --git a/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IToolRegistryProvider.cs b/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IToolRegistryProvider.cs index 2be073cb..9aa0a195 100644 --- a/src/Abstractions/CrestApps.Core.AI.Abstractions/Tooling/IToolRegistryProvider.cs +++ b/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. /// /// The completion context containing configured tool names, - /// instance IDs, and MCP connection IDs that scope the returned tools. + /// tool instance names, and MCP connection IDs that scope the returned tools. /// A token to cancel the operation. /// A read-only list of tool registry entries from this provider. Task> GetToolsAsync( diff --git a/src/Abstractions/CrestApps.Core.Abstractions/Builders/CrestAppsBuilder.cs b/src/Abstractions/CrestApps.Core.Abstractions/Builders/CrestAppsBuilder.cs index 06014730..71d9175a 100644 --- a/src/Abstractions/CrestApps.Core.Abstractions/Builders/CrestAppsBuilder.cs +++ b/src/Abstractions/CrestApps.Core.Abstractions/Builders/CrestAppsBuilder.cs @@ -199,3 +199,25 @@ public CrestAppsAIMemoryBuilder(IServiceCollection services) /// public IServiceCollection Services { get; } } + +/// +/// Builder returned by AddToolInstances that provides access to the +/// for registering AI tool instance sources. +/// +public sealed class CrestAppsAIToolInstancesBuilder +{ + /// + /// Initializes a new instance of the class. + /// + /// The service collection. + public CrestAppsAIToolInstancesBuilder(IServiceCollection services) + { + ArgumentNullException.ThrowIfNull(services); + Services = services; + } + + /// + /// Gets the used to register AI tool instance sources. + /// + public IServiceCollection Services { get; } +} diff --git a/src/CrestApps.Core.Docs/docs/changelog/v1.0.0.md b/src/CrestApps.Core.Docs/docs/changelog/v1.0.0.md index 33687dbc..8d91fcc0 100644 --- a/src/CrestApps.Core.Docs/docs/changelog/v1.0.0.md +++ b/src/CrestApps.Core.Docs/docs/changelog/v1.0.0.md @@ -111,3 +111,8 @@ 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()`) 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 +- refines the parameterized AI tool instances so profiles and chat interactions reference instances by their stable unique **name** (via the renamed, feature-agnostic `AIToolInstanceMetadata` and `AICompletionContext.ToolInstanceNames`) resolved through `INamedCatalog.FindByNameAsync` instead of by generated id; the name is immutable after creation and `AIToolInstance.GetFunctionName()` appends a short deterministic hash when sanitizing would be lossy so distinct names can never collapse to the same function; decouples the default registry so the opt-out lives on `AddToolInstances(..., useDefaultRegistry: false)` and exposes `AddDefaultAIToolInstanceRegistryProvider()`, letting hosts opt out and register their own `IToolRegistryProvider` without ever calling `RemoveAll()`; makes `ToolInstanceRegistryProvider` public with a `ShouldIncludeInstanceAsync` hook for simple permission-gated subclasses; and adds OAuth 2.0 support to the built-in `http-api-request` source that acquires, data-protects, caches, and refreshes access/refresh tokens on the instance itself so it authenticates once and reuses the token across requests and restarts +- promotes the parameterized AI tool instances into a first-class opt-in feature registered on the AI suite builder with `AddToolInstances(toolInstances => toolInstances.AddSource(...))` (with an `AddHttpApiRequestSource()` convenience for the built-in source), instead of being wired into the core AI services automatically; persistence is registered on the tool-instances builder via `AddYesSqlStores()`/`AddEntityCoreStores()` rather than on the AI suite; drops the redundant per-instance `DisplayText` in favor of the unique `Name`, localizes the source `DisplayName`/`Description`/`Category`, simplifies `IAIToolInstanceSource.CreateTool(AIToolInstance instance)` to take the instance directly, generalizes the completion-context handler to honor tool instances on any resource so both AI profiles and chat interactions can select them, renames the built-in HTTP source's basic/OAuth credentials to `Username`/`Password` and adds the OAuth 2.0 resource-owner password grant, hardens model-provided paths so they cannot redirect a request off the configured host, and updates the MVC and Blazor sample hosts to let users attach instances to both AI profiles and chat interactions +- namespaces every tool-instance function name with the `AIToolInstanceExtensions.FunctionNamePrefix` (`tool_instance_`) prefix so a user-chosen instance name can never collide with a tool registered in code via `AddCoreAITool` (which the model sees under its bare registered name); both kinds of tool now coexist safely in the single function namespace exposed to OpenAI, Azure OpenAI, and every other client +- adds a source dropdown to the AI tool instance create form in the MVC and Blazor sample hosts that reveals only the selected source's fields (the source is fixed and shown read-only on edit), and relocates the "AI Tool Instances" admin menu item next to "AI Profiles" in both samples diff --git a/src/CrestApps.Core.Docs/docs/core/tool-instances.md b/src/CrestApps.Core.Docs/docs/core/tool-instances.md new file mode 100644 index 00000000..b4efd603 --- /dev/null +++ b/src/CrestApps.Core.Docs/docs/core/tool-instances.md @@ -0,0 +1,436 @@ +--- +sidebar_label: Tool Instances +sidebar_position: 9 +title: Parameterized Tool Instances +description: Let users configure reusable tool instances with their own endpoints, credentials, and settings that the AI model invokes on demand. +--- + +# Parameterized Tool Instances + +> Author a tool **source** once in code, then let users create multiple configured **instances** of it from the UI. Each instance supplies the parameters (endpoint, authentication, headers, …) and a natural-language description up front; the AI model only decides *when* to invoke each instance. + +## Quick Start + +Enable the feature on the AI suite builder with `AddToolInstances(...)`, then register one or more **sources** (reusable blueprints) inside it. Each source is a class implementing `IAIToolInstanceSource`, registered under a unique name with `AddSource()`: + +```csharp +builder.Services.AddCrestAppsCore(crestApps => crestApps + .AddAISuite(ai => ai + .AddYesSqlStores() + // Enable the tool instances feature and register your sources. + .AddToolInstances(toolInstances => toolInstances + // Register a persistence store for the instances users create (required). + .AddYesSqlStores() + .AddSource("my-source", options => + { + options.DisplayName = new LocalizedString("my-source", "My Source"); + options.Description = new LocalizedString("my-source", "What this source does."); + options.Category = new LocalizedString("Integrations", "Integrations"); + }) + ) + ) +); +``` + +The framework also ships a built-in source — the [HTTP API Request tool](#built-in-http-api-request-tool) — as a ready-made example. Add it with the `AddHttpApiRequestSource()` convenience, which registers its named `HttpClient` and the source with sensible default display metadata: + +```csharp +.AddToolInstances(toolInstances => toolInstances + .AddYesSqlStores() + .AddHttpApiRequestSource() +) +``` + +Either way, once a source is registered, users create instances in the management UI, give each a unique **name** and a clear **description**, and attach one or more instances to an AI profile or a chat interaction. Each instance appears to the model as a distinct callable function. + +:::note +The examples above use YesSql, but the feature works with Entity Framework Core too — swap `AddYesSqlStores()` for `AddEntityCoreStores()`. See [Persistence](#persistence) for complete examples of both providers. +::: + +## Problem & Solution + +A [custom AI tool](tools) exposes a function whose arguments are always supplied by the model. That is perfect for stateless helpers (calculator, weather), but it does not fit tools that must be *configured before use*, such as: + +- calling a specific external HTTP API with a fixed endpoint, auth, and headers; +- talking to an internal service that requires a secret the model must never see; +- the same capability pointed at several different targets (staging vs. production, two vendors, …). + +**Tool instances** solve this by splitting the concern in two: + +| Concept | Authored by | Responsibility | +|---------|-------------|----------------| +| **Source** (`IAIToolInstanceSource`) | Developer (code) | Describes *how* the tool works and how to build it from stored settings. | +| **Instance** (`AIToolInstance`) | End user (UI) | Supplies *the parameters* (endpoint, credentials, headers), a unique name, and a natural-language description. | + +The AI model still decides *when* to call, but it calls the user-configured instance, using the user's predefined settings. Because every instance carries its own unique name and user-written description, the model can distinguish multiple instances built from the same source. + +`AIToolInstance` is a sealed [`SourceCatalogEntry`](extensible-entity): its `Source` property records which source produced it, and the management UI adapts to that source. This mirrors the framework's other source-aware catalogs (AI connections, AI deployments, AI data sources). + +## How It Works + +``` +IAIToolInstanceSource ──► AIToolInstance (user settings) ──► AITool ──► ChatOptions.Tools + (code) (catalog entry) (per instance) (model) +``` + +1. A developer registers the feature with `AddToolInstances(...)` and one or more **sources** with `AddSource(name, configure)`. +2. A user creates one or more **instances** from that source, each with a unique name, a description, and its own stored settings. The name is the stable lookup key and is fixed once the instance is created — the management UI keeps it editable only on create. +3. The user attaches instances to an AI profile or a chat interaction (via `AIToolInstanceMetadata`). +4. During completion, `ToolInstanceRegistryProvider` materializes each referenced instance into a distinct `AITool` whose function name and description are unique per instance. +5. The resulting `AITool` flows into `ChatOptions.Tools` through `Microsoft.Extensions.AI`, so **every client (OpenAI, Azure OpenAI, …) works with no client-specific code**. + +Distinct per-instance function names are produced by `AIToolInstance.GetFunctionName()`, which sanitizes the instance's unique `Name` to the characters chat-completion providers allow and prefixes it with `AIToolInstanceExtensions.FunctionNamePrefix` (`tool_instance_`). The prefix guarantees a user-chosen instance name can never collide with a tool registered in code via `AddCoreAITool` — those are surfaced to the model under their bare registered name, so both kinds of tool coexist in the single function namespace the model sees without clashing. When sanitizing or truncating to 64 characters would change the value, a short deterministic hash of the original name is appended so two distinct names can never collapse to the same function name. + +## Authoring a Source + +Authoring your own source is the core extension point — the built-in HTTP tool below is authored exactly this way. Implement `IAIToolInstanceSource` and its single `CreateTool` method. `CreateTool` receives the configured `AIToolInstance`, reads its stored settings, and returns an `AITool` bound to them. Derive the model-facing function name from `instance.GetFunctionName()` and the description from `instance.Description` so the instance surfaces distinctly: + +```csharp +using CrestApps.Core; +using CrestApps.Core.AI.Tooling; +using Microsoft.Extensions.AI; + +public sealed class HttpApiRequestToolInstanceSource : IAIToolInstanceSource +{ + public AITool CreateTool(AIToolInstance instance) + { + ArgumentNullException.ThrowIfNull(instance); + + // Read the settings the user stored on the instance. + var settings = instance.TryGet(out var stored) + ? stored + : new HttpApiRequestToolSettings(); + + // The function name and description are unique per instance so the model can tell them apart. + var functionName = instance.GetFunctionName(); + var description = string.IsNullOrWhiteSpace(instance.Description) + ? functionName + : instance.Description; + + // Pass the instance so the tool can cache state (for example OAuth 2.0 tokens) on it. + return new HttpApiRequestToolFunction(functionName, description, settings, instance); + } +} +``` + +The returned tool is an ordinary `Microsoft.Extensions.AI.AIFunction`. Read the configuration the user captured, resolve any services you need from `AIFunctionArguments.Services`, and only accept the open arguments you allow the model to supply. The source's *display* metadata (display name, description, category) is provided at registration time — not on the class — so no separate options or builder types are required. + +### Persisting metadata on the instance + +`AIToolInstance` extends the framework's [extensible entity](extensible-entity), so a source persists its own strongly typed configuration as metadata on the instance: + +```csharp +// When saving (UI/controller): +instance.Put(new HttpApiRequestToolSettings { BaseUrl = "https://api.example.com", ... }); + +// When building the tool (source): +instance.TryGet(out var settings); +``` + +### Protecting secrets + +Never store credentials in plain text. Protect them with ASP.NET Core Data Protection when saving and unprotect them at invocation time: + +```csharp +var protector = provider.CreateProtector("MySource.Secrets"); +var stored = protector.Protect(userSuppliedSecret); // when saving +var secret = protector.Unprotect(stored); // inside the tool +``` + +The built-in HTTP tool follows this pattern: on edit, a blank secret reuses the previously stored value, and `Unprotect` tolerates config-seeded plain values. + +## Registering a Source + +Register sources through the `AddToolInstances(...)` feature builder on the AI suite. Call `AddSource(name, configure)` for each source: + +```csharp +.AddToolInstances(toolInstances => toolInstances + .AddYesSqlStores() + .AddSource( + HttpApiRequestToolConstants.SourceName, + options => + { + options.DisplayName = new LocalizedString(HttpApiRequestToolConstants.SourceName, "HTTP API Request"); + options.Description = new LocalizedString(HttpApiRequestToolConstants.SourceName, "Calls an external HTTP API."); + options.Category = new LocalizedString("Integrations", "Integrations"); + }) +) +``` + +`AddToolInstances(configure, useDefaultRegistry = true)` does the following: + +- registers the core services (the catalog handler and the completion-context builder handler); +- when `useDefaultRegistry` is `true` (the default), registers the built-in `ToolInstanceRegistryProvider`. Pass `useDefaultRegistry: false` to opt out and supply [your own registry provider](#custom-tool-registry-providers) instead; +- invokes the `configure` delegate so you can register sources and a persistence store on the builder. + +The feature does **not** register a persistence store for you. Call `AddYesSqlStores()` or `AddEntityCoreStores()` on the tool-instances builder so the instances users create are saved. + +Each `AddSource(name, configure)`: + +- registers the source as a **keyed** scoped `IAIToolInstanceSource`, keyed by `name` (the value stored as each instance's `Source`); +- records the source's display metadata in `AIOptions.ToolInstanceSources[name]` via the `configure` delegate. + +| Configure property | Use | +|---|---| +| `DisplayName` | Friendly name shown when choosing a source (`LocalizedString`). | +| `Description` | Explains what the source does (`LocalizedString`). | +| `Category` | UI grouping (`LocalizedString`). | + +If `DisplayName` is left empty it defaults to the registered `name`. + +## Built-In HTTP API Request Tool + +The framework ships a ready-to-use source that calls arbitrary HTTP APIs. Add it with the `AddHttpApiRequestSource()` convenience, which registers its named `HttpClient` and the source: + +```csharp +.AddToolInstances(toolInstances => toolInstances + .AddYesSqlStores() + .AddHttpApiRequestSource() +) +``` + +`AddHttpApiRequestSource(configure)` applies default display metadata; pass an optional `configure` delegate to override the display name, description, or category. + +Each instance captures: + +| Setting | Purpose | +|---|---| +| `BaseUrl` | The endpoint the request targets. | +| `HttpMethod` | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. | +| `AuthenticationType` | `None`, `ApiKey`, `Bearer`, `Basic`, or `OAuth2`. | +| `ApiKey` / `ApiKeyHeaderName` | API-key auth (header defaults to `X-Api-Key`). | +| `BearerToken` | Bearer auth (`Authorization: Bearer …`). | +| `Username` / `Password` | HTTP basic auth, or the resource-owner credentials for the OAuth 2.0 password grant. | +| `TokenEndpoint` / `ClientId` / `ClientSecret` / `Scope` | OAuth 2.0 settings used to obtain (and refresh) a token automatically. | +| `DefaultHeaders` | Static headers always added. | +| `AllowModelProvidedPath` / `…Query` / `…Body` | Which open arguments the model may supply. | +| `TimeoutSeconds` | Optional per-request timeout. | + +Credentials (`ApiKey`, `BearerToken`, `Password`, `ClientSecret`) are data-protected at rest with the `HttpApiRequestToolConstants.DataProtectionPurpose` purpose. + +The tool exposes only the open arguments you enable (`path`, `query`, `body`) and returns a JSON envelope: + +```json +{ + "success": true, + "statusCode": 200, + "reasonPhrase": "OK", + "contentType": "application/json", + "truncated": false, + "body": "…" +} +``` + +### OAuth 2.0 token caching + +When an instance uses `AuthenticationType = OAuth2`, the tool obtains an access token from the configured `TokenEndpoint` the first time it runs and **caches it on the instance** so subsequent calls do not re-authenticate: + +1. Before each request the tool reads the cached `HttpApiRequestTokenState` from the instance (via `TryGet`). If a non-expired access token is present, it is reused. +2. Otherwise it requests a new token. If a refresh token was previously stored, it first tries `grant_type=refresh_token`. Otherwise, when a `Username` is configured it uses the resource-owner `grant_type=password` (sending `Username` / `Password`); when no username is configured it falls back to `grant_type=client_credentials` using `ClientId` / `ClientSecret` / `Scope`. +3. The returned access token, refresh token, token type, and expiry are data-protected and persisted back onto the instance with `Put(...)`, then saved through the catalog so the cache survives across requests and restarts. + +The access and refresh tokens are protected at rest with the same `HttpApiRequestToolConstants.DataProtectionPurpose` purpose as the other credentials. Because the cache lives on the `AIToolInstance` itself, each instance maintains its own independent token, and no token is ever exposed to the model. + +:::note +Token and credential protection depends on a registered `IDataProtectionProvider` (ASP.NET Core apps have one by default). If no provider is resolvable, the source degrades gracefully and stores the values unprotected, so make sure data protection is configured in production. +::: + +## Creating Instances in the Sample Hosts + +In the sample hosts, open **AI Tool Instances**, then: + +1. Choose a **source** (for example, *HTTP API Request*). +2. Enter a unique **technical name** and a **description**. The name becomes the function name exposed to the model, and the description is the primary signal the model uses to tell instances apart, so make it specific — e.g. *"Looks up order status from the Orders API."* +3. Fill in the source-specific settings (endpoint, auth, headers, …). +4. Save. + +Repeat to add **multiple instances from the same source** — each with a different name, settings, and description. For example, one instance calls the Orders API and another calls the Weather API; both use the same `http-api-request` source but appear to the model as two separate functions. + +## Attaching Instances to a Profile or Chat Interaction + +Instances only reach the model when a profile or chat interaction references them. The sample hosts add a checkbox section on both the AI profile and chat interaction Create/Edit pages; the selected instance **names** are stored via `AIToolInstanceMetadata` — a generic metadata type usable by any resource, including both AI profiles and chat interactions: + +```csharp +// The same call works for an AIProfile or a ChatInteraction. +resource.Alter(metadata => +{ + metadata.ToolInstanceNames = selectedInstanceNames; +}); +``` + +At completion time, `AIToolInstanceCompletionContextBuilderHandler` reads `AIToolInstanceMetadata` from the resource (any extensible entity) and copies those names onto `AICompletionContext.ToolInstanceNames`. The registry provider then looks each one up by name and surfaces it as a distinct tool. Because the handler works off the shared metadata rather than a specific resource type, the same instances are honored across every orchestrator. + +## Custom Tool Registry Providers + +The default `ToolInstanceRegistryProvider` surfaces every referenced instance to the model unconditionally. Real applications often need extra logic — most commonly a **permission check** so an instance is only exposed to users who are allowed to use it. + +Tools reach the model through the aggregated `IToolRegistryProvider` abstraction. Any number of providers can be registered; the registry concatenates the tools returned by each. + +For simple per-instance gating you do not have to write a provider from scratch. `ToolInstanceRegistryProvider` is `public` and exposes a `protected virtual ShouldIncludeInstanceAsync(instance, context, cancellationToken)` hook that runs for every referenced instance before it is surfaced. Subclass it and return `false` to hide an instance: + +```csharp +public sealed class PermissionAwareToolInstanceRegistryProvider : ToolInstanceRegistryProvider +{ + private readonly IAuthorizationService _authorization; + + public PermissionAwareToolInstanceRegistryProvider( + INamedCatalog catalog, + IServiceProvider services, + IAuthorizationService authorization) + : base(catalog, services) + { + _authorization = authorization; + } + + protected override async ValueTask ShouldIncludeInstanceAsync( + AIToolInstance instance, + AICompletionContext context, + CancellationToken cancellationToken) + => await IsAuthorizedAsync(instance, cancellationToken); +} +``` + +Register your subclass in place of the default (see [opting out](#opting-out-of-the-default-provider) below). + +If you need full control over how entries are built, implement `IToolRegistryProvider` directly instead: + +```csharp +using CrestApps.Core.AI.Models; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.Services; + +public sealed class PermissionAwareToolRegistryProvider : IToolRegistryProvider +{ + private readonly INamedCatalog _catalog; + private readonly IAuthorizationService _authorization; + // ... resolve the current user, sources, etc. + + public async Task> GetToolsAsync( + AICompletionContext context, + CancellationToken cancellationToken = default) + { + var names = context?.ToolInstanceNames; + + if (names is null || names.Length == 0) + { + return []; + } + + var entries = new List(); + + foreach (var name in names) + { + var instance = await _catalog.FindByNameAsync(name, cancellationToken); + + if (instance is null) + { + continue; + } + + // Only expose instances the current user is permitted to use. + if (!await IsAuthorizedAsync(instance, cancellationToken)) + { + continue; + } + + entries.Add(/* build a ToolRegistryEntry from the instance's source */); + } + + return entries; + } +} +``` + +### Opting Out of the Default Provider + +Register your provider and **opt out of the default one** so the built-in provider does not also surface ungated tools. Do this by passing `useDefaultRegistry: false` to `AddToolInstances`, then registering your provider explicitly: + +```csharp +// Enable the feature WITHOUT the default registry provider, and register your store and sources. +.AddToolInstances(toolInstances => toolInstances + .AddYesSqlStores() + .AddHttpApiRequestSource(), + useDefaultRegistry: false) + +// ...then register only your gated provider. +builder.Services.AddScoped(); +``` + +This is exactly how downstream products layer their own authorization on top of the same abstractions — for example, the Orchard Core CMS integration ships a `LocalToolRegistryProvider` that checks per-instance permissions before exposing each tool. + +## Persistence + +Tool instances are stored through the `AIToolInstance` catalog. Because the feature does not register a store on its own, register one on the **tool-instances** builder — not on the AI suite — so it matches the provider your app already uses. Register the same provider you use for the rest of the AI suite. + +### YesSql + +```csharp +builder.Services.AddCrestAppsCore(crestApps => crestApps + .AddAISuite(ai => ai + .AddYesSqlStores() + .AddToolInstances(toolInstances => toolInstances + .AddYesSqlStores() + .AddHttpApiRequestSource() + ) + ) +); +``` + +`AddYesSqlStores()` registers the catalog and the `AIToolInstanceIndex`. Create the index table during startup with `CreateAIToolInstanceIndexSchemaAsync()`. + +### Entity Framework Core + +```csharp +builder.Services.AddCrestAppsCore(crestApps => crestApps + .AddAISuite(ai => ai + .AddEntityCoreStores() + .AddToolInstances(toolInstances => toolInstances + .AddEntityCoreStores() + .AddHttpApiRequestSource() + ) + ) + .AddEntityCoreSqliteDataStore("Data Source=App_Data\\crestapps.db") +); +``` + +`AddEntityCoreStores()` registers the source-document catalog for `AIToolInstance`; the schema is created and migrated by the Entity Framework Core data store, so no extra index step is required. + +Only the store, the source (`AddSource(...)`), and the management UI are app-specific. The `CrestApps.Core.Mvc.Web` sample uses YesSql and `CrestApps.Core.Blazor.Web` uses Entity Framework Core, so each provider has a working reference host. + +## Testing + +Because a source produces an ordinary `AIFunction`, you can test it in isolation. Supply services (such as `IHttpClientFactory`) through `AIFunctionArguments.Services`: + +```csharp +var settings = new HttpApiRequestToolSettings +{ + BaseUrl = "https://api.example.com/v1", + HttpMethod = "POST", + AuthenticationType = HttpApiRequestAuthenticationType.Bearer, + BearerToken = "secret-token", + AllowModelProvidedPath = true, +}; + +var function = new HttpApiRequestToolFunction("weather", "Gets the weather.", settings); + +var arguments = new AIFunctionArguments +{ + ["path"] = "forecast", + ["query"] = new Dictionary { ["city"] = "Seattle" }, + Services = serviceProvider, // provides a stubbed IHttpClientFactory +}; + +var result = await function.InvokeAsync(arguments); +``` + +To verify that multiple instances surface distinctly, build a service provider with the source registered as a keyed `IAIToolInstanceSource` plus an `INamedCatalog` whose `FindByNameAsync` returns two instances, then assert `ToolInstanceRegistryProvider.GetToolsAsync` (with `context.ToolInstanceNames` set to the two names) returns two entries with distinct `Name` and `Description`. + +:::tip +The sample projects (`CrestApps.Core.Mvc.Web` and `CrestApps.Core.Blazor.Web`) register the `http-api-request` source and include the full management UI. Run the Aspire host and add two HTTP API instances to see them appear to the model as separate functions. +::: + +## Related + +- [Custom AI Tools](tools) — tools whose arguments are always supplied by the model. +- [Extensible Entity](extensible-entity) — how instance settings are persisted. +- The Orchard Core CMS integration builds on the same abstractions; see the downstream product docs at [orchardcore.crestapps.com](https://orchardcore.crestapps.com). diff --git a/src/CrestApps.Core.Docs/sidebars.js b/src/CrestApps.Core.Docs/sidebars.js index 0c124461..b31a6fc7 100644 --- a/src/CrestApps.Core.Docs/sidebars.js +++ b/src/CrestApps.Core.Docs/sidebars.js @@ -87,6 +87,7 @@ const sidebars = { 'core/response-handlers', 'core/signalr', 'core/tools', + 'core/tool-instances', 'core/use-cases', ], }, diff --git a/src/Primitives/CrestApps.Core.AI/AIOptions.cs b/src/Primitives/CrestApps.Core.AI/AIOptions.cs index 8473c08f..e0346f39 100644 --- a/src/Primitives/CrestApps.Core.AI/AIOptions.cs +++ b/src/Primitives/CrestApps.Core.AI/AIOptions.cs @@ -13,6 +13,7 @@ public sealed class AIOptions private readonly Dictionary _deployments = new(StringComparer.OrdinalIgnoreCase); private readonly Dictionary _connectionSources = new(StringComparer.OrdinalIgnoreCase); private readonly Dictionary _templateSources = new(StringComparer.OrdinalIgnoreCase); + private readonly Dictionary _toolInstanceSources = new(StringComparer.OrdinalIgnoreCase); /// /// Gets the clients. @@ -69,6 +70,17 @@ public IReadOnlyDictionary TemplateSources } } + /// + /// Gets the registered tool instance sources, keyed by source name. + /// + public IReadOnlyDictionary ToolInstanceSources + { + get + { + return _toolInstanceSources; + } + } + internal void AddClient(string name) where TClient : class, IAICompletionClient { @@ -180,4 +192,31 @@ public void AddTemplateSource(string name, Action configu _templateSources[name] = entry; } + + /// + /// Registers or updates the display metadata for a tool instance source. + /// + /// The unique registered name of the tool instance source. + /// An optional delegate used to configure the source entry. + public void AddToolInstanceSource(string name, Action configure = null) + { + ArgumentException.ThrowIfNullOrEmpty(name); + + if (!_toolInstanceSources.TryGetValue(name, out var entry)) + { + entry = new AIToolInstanceSourceEntry(name); + } + + if (configure != null) + { + configure(entry); + } + + if (string.IsNullOrEmpty(entry.DisplayName)) + { + entry.DisplayName = new LocalizedString(name, name); + } + + _toolInstanceSources[name] = entry; + } } diff --git a/src/Primitives/CrestApps.Core.AI/AIToolInstanceServiceCollectionExtensions.cs b/src/Primitives/CrestApps.Core.AI/AIToolInstanceServiceCollectionExtensions.cs new file mode 100644 index 00000000..8a9dfc57 --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/AIToolInstanceServiceCollectionExtensions.cs @@ -0,0 +1,118 @@ +using CrestApps.Core.AI.Completions; +using CrestApps.Core.AI.Handlers; +using CrestApps.Core.AI.Orchestration; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.Builders; +using CrestApps.Core.Services; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; + +namespace CrestApps.Core.AI; + +/// +/// Service-collection extensions for registering the AI tool instance feature: parameterized, +/// user-configured tools built from developer-defined blueprints. +/// +public static class AIToolInstanceServiceCollectionExtensions +{ + /// + /// Registers the core services required to configure and run AI tool instances: the catalog handler + /// and the completion-context builder handler. This does not register a tool registry provider; + /// call for the built-in provider, or register + /// your own to control which instances are surfaced to the model. + /// + /// The service collection. + /// The service collection, for chaining. + public static IServiceCollection AddCoreAIToolInstances(this IServiceCollection services) + { + ArgumentNullException.ThrowIfNull(services); + + services.TryAddScoped>(sp => sp.GetRequiredService>()); + services.TryAddScoped>(); + + services.TryAddEnumerable(ServiceDescriptor.Scoped, AIToolInstanceCatalogHandler>()); + services.TryAddEnumerable(ServiceDescriptor.Scoped()); + + return services; + } + + /// + /// Registers the built-in that surfaces the configured + /// entries named on the completion context to the orchestrator. Registered + /// additively, so it is safe to call more than once. To take full control of which instances are + /// exposed (for example to enforce per-user permissions), skip this and register your own + /// instead — see the documentation for an example. + /// + /// The service collection. + /// The service collection, for chaining. + public static IServiceCollection AddDefaultAIToolInstanceRegistryProvider(this IServiceCollection services) + { + ArgumentNullException.ThrowIfNull(services); + + services.TryAddEnumerable(ServiceDescriptor.Scoped()); + + return services; + } + + /// + /// Registers a developer-defined blueprint so users can create one + /// or more configured entries from it and attach them to AI profiles or + /// chat interactions. The source's display metadata (display name, description, category) is recorded + /// in , while the behavior is registered as a keyed service + /// resolved by the source name. + /// + /// + /// Source registration never decides registry policy. Register the built-in registry provider with + /// (done for you by AddToolInstances) or + /// supply your own to control which instances reach the model. + /// + /// The source type. + /// The service collection. + /// The unique registered name of the source. Stored as the source of every instance created from it. + /// An optional delegate used to configure the source display metadata. + /// The service collection, for chaining. + public static IServiceCollection AddAIToolInstanceSource( + this IServiceCollection services, + string name, + Action configure = null) + where TSource : class, IAIToolInstanceSource + { + ArgumentNullException.ThrowIfNull(services); + ArgumentException.ThrowIfNullOrEmpty(name); + + services.AddCoreAIToolInstances(); + + services.TryAddKeyedScoped(name); + + services.Configure(options => + { + options.AddToolInstanceSource(name, configure); + }); + + return services; + } + + /// + /// Registers a developer-defined blueprint on the tool instances + /// builder. The registry provider is owned by AddToolInstances, so this method never registers + /// it; use AddToolInstances(useDefaultRegistry: false) to supply your own + /// . + /// + /// The source type. + /// The tool instances builder. + /// The unique registered name of the source. Stored as the source of every instance created from it. + /// An optional delegate used to configure the source display metadata. + /// The tool instances builder, for chaining. + public static CrestAppsAIToolInstancesBuilder AddSource( + this CrestAppsAIToolInstancesBuilder builder, + string name, + Action configure = null) + where TSource : class, IAIToolInstanceSource + { + ArgumentNullException.ThrowIfNull(builder); + + builder.Services.AddAIToolInstanceSource(name, configure); + + return builder; + } +} diff --git a/src/Primitives/CrestApps.Core.AI/AIToolInstanceSourceEntry.cs b/src/Primitives/CrestApps.Core.AI/AIToolInstanceSourceEntry.cs new file mode 100644 index 00000000..daed63eb --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/AIToolInstanceSourceEntry.cs @@ -0,0 +1,41 @@ +using Microsoft.Extensions.Localization; + +namespace CrestApps.Core.AI; + +/// +/// Describes the display metadata for a registered AI tool instance source. Instances of this entry are +/// stored in keyed by the source name and drive how the +/// source is presented when users create configured AIToolInstance entries. +/// +public sealed class AIToolInstanceSourceEntry +{ + /// + /// Initializes a new instance of the class. + /// + /// The unique registered name of the tool instance source. + public AIToolInstanceSourceEntry(string source) + { + Source = source; + } + + /// + /// Gets the unique registered name of the tool instance source. This value is stored as the + /// of every instance created from it. + /// + public string Source { get; } + + /// + /// Gets or sets the friendly display name shown when choosing this source to configure a new instance. + /// + public LocalizedString DisplayName { get; set; } + + /// + /// Gets or sets the description that explains what kinds of instances this source produces. + /// + public LocalizedString Description { get; set; } + + /// + /// Gets or sets an optional category used to group sources in the management UI. + /// + public LocalizedString Category { get; set; } +} diff --git a/src/Primitives/CrestApps.Core.AI/Handlers/AIToolInstanceCatalogHandler.cs b/src/Primitives/CrestApps.Core.AI/Handlers/AIToolInstanceCatalogHandler.cs new file mode 100644 index 00000000..68c93318 --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Handlers/AIToolInstanceCatalogHandler.cs @@ -0,0 +1,218 @@ +using System.ComponentModel.DataAnnotations; +using System.Security.Claims; +using System.Text.Json; +using System.Text.Json.Nodes; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.Handlers; +using CrestApps.Core.Models; +using CrestApps.Core.Services; +using CrestApps.Core.Support; +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Localization; +using Microsoft.Extensions.Options; + +namespace CrestApps.Core.AI.Handlers; + +/// +/// The authoritative catalog handler for entries. It maps incoming JSON onto +/// the model, applies create-time defaults, and validates the shared model concerns (unique name, tool +/// source, and the description used to disambiguate instances). Source-specific settings validation is +/// intentionally left to the presentation layer. +/// +internal sealed class AIToolInstanceCatalogHandler : CatalogEntryHandlerBase +{ + private readonly IHttpContextAccessor _httpContextAccessor; + private readonly TimeProvider _timeProvider; + private readonly AIOptions _aiOptions; + private readonly IServiceProvider _serviceProvider; + + internal readonly IStringLocalizer S; + + /// + /// Initializes a new instance of the class. + /// + /// The HTTP context accessor used to stamp owner details. + /// The time provider used for create/modify timestamps. + /// The AI options used to validate the selected tool source. + /// The service provider used to resolve the instance catalog for duplicate-name checks. + /// The string localizer used for validation messages. + public AIToolInstanceCatalogHandler( + IHttpContextAccessor httpContextAccessor, + TimeProvider timeProvider, + IOptions aiOptions, + IServiceProvider serviceProvider, + IStringLocalizer stringLocalizer) + { + _httpContextAccessor = httpContextAccessor; + _timeProvider = timeProvider; + _aiOptions = aiOptions.Value; + _serviceProvider = serviceProvider; + S = stringLocalizer; + } + + /// + /// Populates a new instance from the supplied JSON data. + /// + /// The initializing context. + /// The cancellation token. + public override Task InitializingAsync(InitializingContext context, CancellationToken cancellationToken = default) + => PopulateAsync(context.Model, context.Data, true); + + /// + /// Populates an existing instance from the supplied JSON data and updates the modified timestamp. + /// + /// The updating context. + /// The cancellation token. + public override async Task UpdatingAsync(UpdatingContext context, CancellationToken cancellationToken = default) + { + await PopulateAsync(context.Model, context.Data, false); + + context.Model.ModifiedUtc = _timeProvider.GetUtcNow().UtcDateTime; + } + + /// + /// Applies create-time defaults after initialization. + /// + /// The initialized context. + /// The cancellation token. + public override Task InitializedAsync(InitializedContext context, CancellationToken cancellationToken = default) + { + EnsureCreatedDefaults(context.Model); + + return Task.CompletedTask; + } + + /// + /// Applies create-time defaults before the instance is persisted. + /// + /// The creating context. + /// The cancellation token. + public override Task CreatingAsync(CreatingContext context, CancellationToken cancellationToken = default) + { + EnsureCreatedDefaults(context.Model); + + return Task.CompletedTask; + } + + /// + /// Validates the shared model concerns for the instance. + /// + /// The validating context. + /// The cancellation token. + public override async Task ValidatingAsync(ValidatingContext context, CancellationToken cancellationToken = default) + { + if (string.IsNullOrWhiteSpace(context.Model.Name)) + { + context.Result.Fail(new ValidationResult( + S["A unique name is required."], [nameof(AIToolInstance.Name)])); + } + + if (string.IsNullOrWhiteSpace(context.Model.Description)) + { + context.Result.Fail(new ValidationResult( + S["A description is required so the AI model can tell instances apart."], [nameof(AIToolInstance.Description)])); + } + + if (string.IsNullOrWhiteSpace(context.Model.Source)) + { + context.Result.Fail(new ValidationResult( + S["A tool source is required."], [nameof(AIToolInstance.Source)])); + } + else if (!_aiOptions.ToolInstanceSources.ContainsKey(context.Model.Source)) + { + context.Result.Fail(new ValidationResult( + S["The selected tool source is not registered."], [nameof(AIToolInstance.Source)])); + } + + await ValidateUniqueNameAsync(context, cancellationToken); + } + + private async Task ValidateUniqueNameAsync(ValidatingContext context, CancellationToken cancellationToken) + { + if (string.IsNullOrWhiteSpace(context.Model.Name)) + { + return; + } + + var catalog = _serviceProvider.GetService>(); + + if (catalog is null) + { + return; + } + + var existing = await catalog.GetAllAsync(cancellationToken); + + var duplicate = existing.Any(entry => + !string.Equals(entry.ItemId, context.Model.ItemId, StringComparison.Ordinal) && + string.Equals(entry.Name, context.Model.Name, StringComparison.OrdinalIgnoreCase)); + + if (duplicate) + { + context.Result.Fail(new ValidationResult( + S["A tool instance with this name already exists. The name must be unique."], [nameof(AIToolInstance.Name)])); + } + } + + private void EnsureCreatedDefaults(AIToolInstance instance) + { + if (instance.CreatedUtc == default) + { + instance.CreatedUtc = _timeProvider.GetUtcNow().UtcDateTime; + } + + var user = _httpContextAccessor.HttpContext?.User; + + if (user == null) + { + return; + } + + instance.OwnerId ??= user.FindFirstValue(ClaimTypes.NameIdentifier); + instance.Author ??= user.Identity?.Name; + } + + private static Task PopulateAsync(AIToolInstance instance, JsonNode data, bool isNew) + { + if (data is not JsonObject json) + { + return Task.CompletedTask; + } + + if (isNew) + { + json.TryUpdateTrimmedStringValue(nameof(AIToolInstance.Source), value => instance.Source = value); + json.TryUpdateTrimmedStringValue(nameof(AIToolInstance.Name), value => instance.Name = value); + } + + json.TryUpdateTrimmedStringValue(nameof(AIToolInstance.Description), value => instance.Description = value); + json.TryUpdateTrimmedStringValue(nameof(AIToolInstance.OwnerId), value => instance.OwnerId = value); + json.TryUpdateTrimmedStringValue(nameof(AIToolInstance.Author), value => instance.Author = value); + + if (json.TryGetDateTimeValue(nameof(AIToolInstance.CreatedUtc), out var createdUtc)) + { + instance.CreatedUtc = createdUtc; + } + + MergeProperties(instance, json); + + return Task.CompletedTask; + } + + private static void MergeProperties(AIToolInstance instance, JsonObject json) + { + if (!json.TryGetObjectValue(nameof(AIToolInstance.Properties), out var properties) || properties == null) + { + return; + } + + var currentJson = JsonExtensions.FromObject(instance.Properties ?? new Dictionary(), ExtensibleEntityExtensions.JsonSerializerOptions); + var existingPropertiesSnapshot = currentJson.Clone(); + + AIPropertiesMergeHelper.Merge(currentJson, properties); + AIPropertiesMergeHelper.MergeNamedEntries(currentJson, existingPropertiesSnapshot); + + instance.Properties = JsonSerializer.Deserialize>(currentJson, ExtensibleEntityExtensions.JsonSerializerOptions) ?? []; + } +} diff --git a/src/Primitives/CrestApps.Core.AI/Handlers/AIToolInstanceCompletionContextBuilderHandler.cs b/src/Primitives/CrestApps.Core.AI/Handlers/AIToolInstanceCompletionContextBuilderHandler.cs new file mode 100644 index 00000000..d2c11e06 --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Handlers/AIToolInstanceCompletionContextBuilderHandler.cs @@ -0,0 +1,40 @@ +using CrestApps.Core.AI.Completions; +using CrestApps.Core.AI.Models; +using CrestApps.Core.AI.Tooling; + +namespace CrestApps.Core.AI.Handlers; + +/// +/// Populates from the +/// stored on the resource driving the completion. Because the +/// metadata lives in the resource's bag, this handler works for +/// any resource that carries it — for example an or a ChatInteraction — so +/// configured tool instances are honored across every orchestrator, not just a single feature. +/// +internal sealed class AIToolInstanceCompletionContextBuilderHandler : IAICompletionContextBuilderHandler +{ + /// + /// Copies the resource's configured tool instance names onto the completion context. + /// + /// The building context. + public Task BuildingAsync(AICompletionContextBuildingContext context) + { + if (context.Resource is ExtensibleEntity entity && + entity.TryGet(out var metadata) && + metadata.ToolInstanceNames is { Length: > 0 }) + { + context.Context.ToolInstanceNames = metadata.ToolInstanceNames; + } + + return Task.CompletedTask; + } + + /// + /// No-op once the context has been built. + /// + /// The built context. + public Task BuiltAsync(AICompletionContextBuiltContext context) + { + return Task.CompletedTask; + } +} diff --git a/src/Primitives/CrestApps.Core.AI/Orchestration/ToolInstanceRegistryProvider.cs b/src/Primitives/CrestApps.Core.AI/Orchestration/ToolInstanceRegistryProvider.cs new file mode 100644 index 00000000..dd28c7eb --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Orchestration/ToolInstanceRegistryProvider.cs @@ -0,0 +1,150 @@ +using CrestApps.Core.AI.Models; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.Services; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; + +namespace CrestApps.Core.AI.Orchestration; + +/// +/// The default that surfaces the configured +/// entries referenced by the completion context to the tool registry. Each +/// instance is materialized into a distinct via its owning +/// (resolved as a keyed service by ), +/// so multiple instances built from the same source appear to the AI model as separate functions with +/// their own descriptions. +/// +/// +/// Projects that need custom logic (for example, permission checks before exposing an instance) have two +/// options: register an additional alongside this one, or subclass this +/// provider and override to filter instances while reusing the +/// entry-building logic. Register the subclass instead of the default (call +/// AddToolInstances(useDefaultRegistry: false) and register your provider) to fully control which +/// instances reach the model. +/// +public class ToolInstanceRegistryProvider : IToolRegistryProvider +{ + private readonly IServiceProvider _serviceProvider; + private readonly ILogger _logger; + + /// + /// Initializes a new instance of the class. + /// + /// The service provider used to resolve the instance catalog and sources. + /// The logger. + public ToolInstanceRegistryProvider( + IServiceProvider serviceProvider, + ILogger logger) + { + _serviceProvider = serviceProvider; + _logger = logger; + } + + /// + /// Gets the tool entries for the configured instance names on the completion context. + /// + /// The completion context that scopes available tools. + /// A token to cancel the operation. + public async Task> GetToolsAsync( + AICompletionContext context, + CancellationToken cancellationToken = default) + { + var instanceNames = context?.ToolInstanceNames; + + if (instanceNames is null || instanceNames.Length == 0) + { + return []; + } + + var catalog = _serviceProvider.GetService>(); + + if (catalog is null) + { + return []; + } + + var entries = new List(); + var seenNames = new HashSet(StringComparer.OrdinalIgnoreCase); + + foreach (var instanceName in instanceNames) + { + if (string.IsNullOrEmpty(instanceName) || !seenNames.Add(instanceName)) + { + continue; + } + + var instance = await catalog.FindByNameAsync(instanceName, cancellationToken); + + if (instance is null || string.IsNullOrEmpty(instance.Source)) + { + continue; + } + + if (!await ShouldIncludeInstanceAsync(instance, context, cancellationToken)) + { + continue; + } + + var source = _serviceProvider.GetKeyedService(instance.Source); + + if (source is null) + { + _logger.LogWarning( + "AI tool instance '{InstanceName}' references unknown source '{Source}'. Skipping.", + instance.Name, instance.Source); + + continue; + } + + var functionName = instance.GetFunctionName(); + var description = !string.IsNullOrWhiteSpace(instance.Description) + ? instance.Description + : functionName; + + entries.Add(new ToolRegistryEntry + { + Id = $"tool-instance:{instance.Name}", + Name = functionName, + Description = description, + Source = ToolRegistryEntrySource.Local, + SourceId = instance.Source, + CreateAsync = _ => ValueTask.FromResult(SafeCreate(source, instance)), + }); + } + + return entries; + } + + /// + /// Determines whether the resolved tool instance should be surfaced to the model for the current + /// completion context. The default implementation includes every instance. Override this to apply + /// custom rules such as per-user permission checks while reusing the built-in entry-building logic. + /// + /// The resolved tool instance. + /// The completion context that scopes available tools. + /// A token to cancel the operation. + /// to include the instance; otherwise . + protected virtual ValueTask ShouldIncludeInstanceAsync( + AIToolInstance instance, + AICompletionContext context, + CancellationToken cancellationToken) + => ValueTask.FromResult(true); + + private AITool SafeCreate(IAIToolInstanceSource source, AIToolInstance instance) + { + try + { + return source.CreateTool(instance); + } + catch (Exception ex) + { + _logger.LogError( + ex, + "Failed to create tool for instance '{InstanceName}' from source '{Source}'.", + instance.Name, instance.Source); + + return null; + } + } +} diff --git a/src/Primitives/CrestApps.Core.AI/ServiceCollectionExtensions.cs b/src/Primitives/CrestApps.Core.AI/ServiceCollectionExtensions.cs index d286e5f9..4ba53e01 100644 --- a/src/Primitives/CrestApps.Core.AI/ServiceCollectionExtensions.cs +++ b/src/Primitives/CrestApps.Core.AI/ServiceCollectionExtensions.cs @@ -411,6 +411,44 @@ public static CrestAppsAISuiteBuilder AddAIMemory(this CrestAppsAISuiteBuilder b return builder; } + /// + /// Adds the AI tool instances feature: parameterized, user-configured tools built from + /// developer-defined blueprints. Registers the core services and, + /// by default, the built-in registry provider that surfaces configured instances to every orchestrator. + /// Use the supplied builder to register one or more sources with + /// AddSource<TSource>(name, configure) or the built-in HTTP source with + /// AddHttpApiRequestSource(), and to register the persistence stores with + /// AddYesSqlStores() or AddEntityCoreStores(). + /// + /// The AI suite builder. + /// An optional delegate used to register tool instance sources and stores. + /// + /// When (the default), registers the built-in + /// . Pass to supply your own + /// instead — for example to enforce per-user permissions. + /// + public static CrestAppsAISuiteBuilder AddToolInstances( + this CrestAppsAISuiteBuilder builder, + Action configure = null, + bool useDefaultRegistry = true) + { + ArgumentNullException.ThrowIfNull(builder); + + builder.Services.AddCoreAIToolInstances(); + + if (useDefaultRegistry) + { + builder.Services.AddDefaultAIToolInstanceRegistryProvider(); + } + + if (configure is not null) + { + configure(new CrestAppsAIToolInstancesBuilder(builder.Services)); + } + + return builder; + } + /// /// Adds the orchestration services including the default progressive tool orchestrator, /// tool registry, orchestration context builder, and orchestrator resolver. diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestAuthenticationType.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestAuthenticationType.cs new file mode 100644 index 00000000..ca90ee09 --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestAuthenticationType.cs @@ -0,0 +1,35 @@ +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// Enumerates the authentication strategies supported by the HTTP API request tool. +/// +public enum HttpApiRequestAuthenticationType +{ + /// + /// No authentication is applied to the request. + /// + None = 0, + + /// + /// A static API key is sent in a configurable request header. + /// + ApiKey = 1, + + /// + /// A bearer token is sent in the Authorization header. + /// + Bearer = 2, + + /// + /// HTTP basic authentication (username and password) is applied. + /// + Basic = 3, + + /// + /// OAuth 2.0. When a username is configured the resource owner password grant is used; otherwise the + /// client credentials grant is used. In both cases the tool requests an access token from the + /// configured token endpoint, caches it on the instance, and reuses a stored refresh token when + /// available before requesting a new token. + /// + OAuth2 = 4, +} diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestTokenState.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestTokenState.cs new file mode 100644 index 00000000..0e524993 --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestTokenState.cs @@ -0,0 +1,29 @@ +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// Cached OAuth 2.0 token state persisted on an so the HTTP tool can reuse a +/// valid access token across requests and refresh it without re-authenticating on every call. The access +/// and refresh tokens are data-protected at rest. +/// +public sealed class HttpApiRequestTokenState +{ + /// + /// Gets or sets the data-protected access token. + /// + public string AccessToken { get; set; } + + /// + /// Gets or sets the data-protected refresh token, when the provider returned one. + /// + public string RefreshToken { get; set; } + + /// + /// Gets or sets the token type returned by the provider (for example, Bearer). + /// + public string TokenType { get; set; } + + /// + /// Gets or sets the UTC time at which the cached access token expires. + /// + public DateTimeOffset? ExpiresAtUtc { get; set; } +} diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolConstants.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolConstants.cs new file mode 100644 index 00000000..34fe314e --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolConstants.cs @@ -0,0 +1,22 @@ +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// Well-known identifiers for the built-in HTTP API request tool instance source. +/// +public static class HttpApiRequestToolConstants +{ + /// + /// The registered source name. Instances created from this source store this value as their source. + /// + public const string SourceName = "http-api-request"; + + /// + /// The data-protection purpose used to protect and unprotect stored credentials. + /// + public const string DataProtectionPurpose = "CrestApps.Core.AI.Tooling.HttpApiRequest"; + + /// + /// The named used to issue requests. + /// + public const string HttpClientName = "CrestApps.Core.AI.HttpApiRequest"; +} diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolFunction.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolFunction.cs new file mode 100644 index 00000000..ccc12b1c --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolFunction.cs @@ -0,0 +1,754 @@ +using System.Net.Http.Headers; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.Services; +using Microsoft.AspNetCore.DataProtection; +using Microsoft.AspNetCore.WebUtilities; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; + +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// An that issues an HTTP request to a user-configured endpoint. The endpoint, +/// HTTP method, authentication, and static headers are captured up front in +/// ; the AI model only supplies the open arguments (relative +/// path, query parameters, and request body) that the settings allow. +/// +public sealed class HttpApiRequestToolFunction : AIFunction +{ + private const int _maxResponseLength = 16000; + private static readonly HashSet _bodyMethods = new(StringComparer.OrdinalIgnoreCase) + { + "POST", + "PUT", + "PATCH", + "DELETE", + }; + + private readonly string _name; + private readonly string _description; + private readonly HttpApiRequestToolSettings _settings; + private readonly AIToolInstance _instance; + private readonly JsonElement _jsonSchema; + + /// + /// Initializes a new instance of the class. + /// + /// The function name exposed to the AI model. + /// The description exposed to the AI model. + /// The user-provided settings that configure the request. + /// + /// The configured tool instance the function belongs to. Used to cache OAuth 2.0 token state across + /// requests. May be (for example in tests), in which case token caching is + /// performed in-memory for the lifetime of the function only. + /// + public HttpApiRequestToolFunction( + string name, + string description, + HttpApiRequestToolSettings settings, + AIToolInstance instance = null) + { + ArgumentException.ThrowIfNullOrEmpty(name); + ArgumentNullException.ThrowIfNull(settings); + + _name = name; + _description = string.IsNullOrWhiteSpace(description) + ? name + : description; + _settings = settings; + _instance = instance; + _jsonSchema = BuildSchema(settings); + } + + /// + /// Gets the function name exposed to the AI model. + /// + public override string Name => _name; + + /// + /// Gets the description exposed to the AI model. + /// + public override string Description => _description; + + /// + /// Gets the JSON schema describing the open arguments the model may supply. + /// + public override JsonElement JsonSchema => _jsonSchema; + + /// + /// Gets additional metadata applied to the function. Strict mode is disabled because the request + /// body is an open-ended object. + /// + public override IReadOnlyDictionary AdditionalProperties { get; } = new Dictionary + { + ["Strict"] = false, + }; + + /// + /// Issues the configured HTTP request, merging the model-provided arguments with the stored settings. + /// + /// The arguments supplied by the AI model. + /// The cancellation token. + protected override async ValueTask InvokeCoreAsync(AIFunctionArguments arguments, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(arguments); + + var services = arguments.Services; + var logger = services?.GetService()?.CreateLogger(); + + if (string.IsNullOrWhiteSpace(_settings.BaseUrl)) + { + return Error("This tool instance is missing its base URL configuration."); + } + + Uri requestUri; + + try + { + requestUri = BuildRequestUri(arguments); + } + catch (Exception ex) + { + logger?.LogWarning(ex, "AI tool '{ToolName}' could not build the request URI.", _name); + + return Error($"The request URL could not be built: {ex.Message}"); + } + + var method = ResolveMethod(); + using var request = new HttpRequestMessage(method, requestUri); + + await ApplyAuthenticationAsync(request, services, logger, cancellationToken); + ApplyDefaultHeaders(request); + ApplyBody(request, method, arguments); + + var httpClient = CreateHttpClient(services); + + using var timeoutCts = CreateTimeoutScope(cancellationToken, out var effectiveToken); + + try + { + using var response = await httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, effectiveToken); + var body = response.Content is null + ? string.Empty + : await response.Content.ReadAsStringAsync(effectiveToken); + var truncated = body.Length > _maxResponseLength; + + if (truncated) + { + body = body[.._maxResponseLength]; + } + + if (logger?.IsEnabled(LogLevel.Debug) == true) + { + logger.LogDebug("AI tool '{ToolName}' called {Method} {Uri} -> {StatusCode}.", _name, method.Method, requestUri, (int)response.StatusCode); + } + + return JsonSerializer.Serialize(new + { + success = response.IsSuccessStatusCode, + statusCode = (int)response.StatusCode, + reasonPhrase = response.ReasonPhrase, + contentType = response.Content?.Headers?.ContentType?.ToString(), + truncated, + body, + }); + } + catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) + { + throw; + } + catch (Exception ex) + { + logger?.LogError(ex, "AI tool '{ToolName}' failed calling {Uri}.", _name, requestUri); + + return Error($"The request failed: {ex.Message}"); + } + } + + private Uri BuildRequestUri(AIFunctionArguments arguments) + { + var baseUri = new Uri(_settings.BaseUrl.Trim(), UriKind.Absolute); + var url = baseUri.ToString(); + + if (_settings.AllowModelProvidedPath && + TryGetString(arguments, "path", out var path) && + !string.IsNullOrWhiteSpace(path)) + { + url = CombineUrl(url, path.Trim()); + } + + if (_settings.AllowModelProvidedQuery && + arguments.TryGetValue("query", out var queryValue) && + TryReadObject(queryValue, out var query)) + { + var pairs = new Dictionary(StringComparer.Ordinal); + + foreach (var pair in query) + { + if (pair.Value is not null) + { + pairs[pair.Key] = pair.Value.ToString(); + } + } + + if (pairs.Count > 0) + { + url = QueryHelpers.AddQueryString(url, pairs); + } + } + + var requestUri = new Uri(url, UriKind.Absolute); + + // The endpoint is fixed by the instance configuration; the model may only extend the path/query. + // Reject any request that would leave the configured scheme/host/port to prevent SSRF redirection + // to arbitrary (for example internal) hosts. + if (requestUri.Scheme != baseUri.Scheme || + !string.Equals(requestUri.Host, baseUri.Host, StringComparison.OrdinalIgnoreCase) || + requestUri.Port != baseUri.Port) + { + throw new InvalidOperationException("The resolved request URL must stay on the configured base host."); + } + + return requestUri; + } + + private HttpMethod ResolveMethod() + { + return string.IsNullOrWhiteSpace(_settings.HttpMethod) + ? HttpMethod.Get + : HttpMethod.Parse(_settings.HttpMethod.Trim().ToUpperInvariant()); + } + + private async Task ApplyAuthenticationAsync( + HttpRequestMessage request, + IServiceProvider services, + ILogger logger, + CancellationToken cancellationToken) + { + switch (_settings.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + var apiKey = Unprotect(services, _settings.ApiKey); + + if (!string.IsNullOrWhiteSpace(apiKey)) + { + var headerName = string.IsNullOrWhiteSpace(_settings.ApiKeyHeaderName) + ? "X-Api-Key" + : _settings.ApiKeyHeaderName.Trim(); + + request.Headers.TryAddWithoutValidation(headerName, apiKey); + } + + break; + + case HttpApiRequestAuthenticationType.Bearer: + var token = Unprotect(services, _settings.BearerToken); + + if (!string.IsNullOrWhiteSpace(token)) + { + request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token); + } + + break; + + case HttpApiRequestAuthenticationType.Basic: + if (!string.IsNullOrWhiteSpace(_settings.Username)) + { + var password = Unprotect(services, _settings.Password); + var raw = $"{_settings.Username}:{password}"; + var encoded = Convert.ToBase64String(Encoding.UTF8.GetBytes(raw)); + + request.Headers.Authorization = new AuthenticationHeaderValue("Basic", encoded); + } + + break; + + case HttpApiRequestAuthenticationType.OAuth2: + var accessToken = await EnsureAccessTokenAsync(services, logger, cancellationToken); + + if (!string.IsNullOrWhiteSpace(accessToken)) + { + request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); + } + + break; + } + } + + private async Task EnsureAccessTokenAsync( + IServiceProvider services, + ILogger logger, + CancellationToken cancellationToken) + { + if (string.IsNullOrWhiteSpace(_settings.TokenEndpoint)) + { + logger?.LogWarning("AI tool '{ToolName}' is configured for OAuth2 but has no token endpoint.", _name); + + return null; + } + + var timeProvider = services?.GetService() ?? TimeProvider.System; + var now = timeProvider.GetUtcNow(); + + HttpApiRequestTokenState state = null; + + if (_instance is not null && _instance.TryGet(out var cached)) + { + state = cached; + } + + if (state is not null && + !string.IsNullOrEmpty(state.AccessToken) && + state.ExpiresAtUtc is { } expiresAt && + expiresAt > now.AddSeconds(30)) + { + return Unprotect(services, state.AccessToken); + } + + var refreshToken = state is not null && !string.IsNullOrEmpty(state.RefreshToken) + ? Unprotect(services, state.RefreshToken) + : null; + + var result = await RequestTokenAsync(services, refreshToken, logger, cancellationToken); + + if (result is null || string.IsNullOrEmpty(result.AccessToken)) + { + // Fall back to any previously cached token, even if it may be expired. + return state is not null + ? Unprotect(services, state.AccessToken) + : null; + } + + var expiresAtUtc = result.ExpiresInSeconds is > 0 + ? now.AddSeconds(result.ExpiresInSeconds.Value) + : now.AddMinutes(55); + + var newState = new HttpApiRequestTokenState + { + AccessToken = Protect(services, result.AccessToken), + RefreshToken = string.IsNullOrEmpty(result.RefreshToken) + ? state?.RefreshToken + : Protect(services, result.RefreshToken), + TokenType = result.TokenType, + ExpiresAtUtc = expiresAtUtc, + }; + + await PersistTokenStateAsync(services, newState, logger, cancellationToken); + + return result.AccessToken; + } + + private async Task RequestTokenAsync( + IServiceProvider services, + string refreshToken, + ILogger logger, + CancellationToken cancellationToken) + { + if (!string.IsNullOrEmpty(refreshToken)) + { + var refreshed = await PostTokenRequestAsync(services, new Dictionary(StringComparer.Ordinal) + { + ["grant_type"] = "refresh_token", + ["refresh_token"] = refreshToken, + }, logger, cancellationToken); + + if (refreshed is not null) + { + return refreshed; + } + } + + // When a resource owner username is configured, use the OAuth 2.0 password grant; otherwise fall + // back to the client credentials grant. + if (!string.IsNullOrWhiteSpace(_settings.Username)) + { + return await PostTokenRequestAsync(services, new Dictionary(StringComparer.Ordinal) + { + ["grant_type"] = "password", + ["username"] = _settings.Username.Trim(), + ["password"] = Unprotect(services, _settings.Password) ?? string.Empty, + }, logger, cancellationToken); + } + + return await PostTokenRequestAsync(services, new Dictionary(StringComparer.Ordinal) + { + ["grant_type"] = "client_credentials", + }, logger, cancellationToken); + } + + private async Task PostTokenRequestAsync( + IServiceProvider services, + Dictionary parameters, + ILogger logger, + CancellationToken cancellationToken) + { + var clientId = _settings.ClientId; + var clientSecret = Unprotect(services, _settings.ClientSecret); + + if (!string.IsNullOrEmpty(clientId)) + { + parameters["client_id"] = clientId; + } + + if (!string.IsNullOrEmpty(clientSecret)) + { + parameters["client_secret"] = clientSecret; + } + + if (!string.IsNullOrWhiteSpace(_settings.Scope)) + { + parameters["scope"] = _settings.Scope.Trim(); + } + + try + { + var httpClient = CreateHttpClient(services); + using var tokenRequest = new HttpRequestMessage(HttpMethod.Post, _settings.TokenEndpoint.Trim()) + { + Content = new FormUrlEncodedContent(parameters), + }; + + using var response = await httpClient.SendAsync(tokenRequest, cancellationToken); + var payload = response.Content is null + ? string.Empty + : await response.Content.ReadAsStringAsync(cancellationToken); + + if (!response.IsSuccessStatusCode) + { + logger?.LogWarning( + "AI tool '{ToolName}' token request to {Endpoint} failed with status {StatusCode}.", + _name, _settings.TokenEndpoint, (int)response.StatusCode); + + return null; + } + + return ParseTokenResponse(payload); + } + catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) + { + throw; + } + catch (Exception ex) + { + logger?.LogWarning(ex, "AI tool '{ToolName}' token request to {Endpoint} failed.", _name, _settings.TokenEndpoint); + + return null; + } + } + + private static OAuthTokenResult ParseTokenResponse(string payload) + { + if (string.IsNullOrWhiteSpace(payload)) + { + return null; + } + + try + { + using var document = JsonDocument.Parse(payload); + var root = document.RootElement; + + if (root.ValueKind != JsonValueKind.Object || + !root.TryGetProperty("access_token", out var accessTokenElement) || + accessTokenElement.ValueKind != JsonValueKind.String) + { + return null; + } + + var result = new OAuthTokenResult + { + AccessToken = accessTokenElement.GetString(), + }; + + if (root.TryGetProperty("refresh_token", out var refreshElement) && refreshElement.ValueKind == JsonValueKind.String) + { + result.RefreshToken = refreshElement.GetString(); + } + + if (root.TryGetProperty("token_type", out var typeElement) && typeElement.ValueKind == JsonValueKind.String) + { + result.TokenType = typeElement.GetString(); + } + + if (root.TryGetProperty("expires_in", out var expiresElement)) + { + if (expiresElement.ValueKind == JsonValueKind.Number && expiresElement.TryGetInt32(out var seconds)) + { + result.ExpiresInSeconds = seconds; + } + else if (expiresElement.ValueKind == JsonValueKind.String && + int.TryParse(expiresElement.GetString(), out var parsedSeconds)) + { + result.ExpiresInSeconds = parsedSeconds; + } + } + + return result; + } + catch (JsonException) + { + return null; + } + } + + private async Task PersistTokenStateAsync( + IServiceProvider services, + HttpApiRequestTokenState state, + ILogger logger, + CancellationToken cancellationToken) + { + if (_instance is null) + { + return; + } + + // Cache in-memory so a subsequent tool call within the same request reuses the token. + _instance.Put(state); + + var catalog = services?.GetService>(); + + if (catalog is null) + { + return; + } + + try + { + await catalog.UpdateAsync(_instance, cancellationToken); + } + catch (Exception ex) + { + logger?.LogWarning(ex, "AI tool '{ToolName}' could not persist the cached OAuth2 token state.", _name); + } + } + + private void ApplyDefaultHeaders(HttpRequestMessage request) + { + if (_settings.DefaultHeaders is null) + { + return; + } + + foreach (var header in _settings.DefaultHeaders) + { + if (!string.IsNullOrWhiteSpace(header.Key)) + { + request.Headers.TryAddWithoutValidation(header.Key, header.Value); + } + } + } + + private void ApplyBody(HttpRequestMessage request, HttpMethod method, AIFunctionArguments arguments) + { + if (!_settings.AllowModelProvidedBody || + !_bodyMethods.Contains(method.Method) || + !arguments.TryGetValue("body", out var bodyValue) || + bodyValue is null) + { + return; + } + + var json = bodyValue switch + { + JsonElement element => element.GetRawText(), + JsonNode node => node.ToJsonString(), + string text => text, + _ => JsonSerializer.Serialize(bodyValue), + }; + + request.Content = new StringContent(json, Encoding.UTF8, "application/json"); + } + + private static HttpClient CreateHttpClient(IServiceProvider services) + { + var factory = services?.GetService(); + + return factory is not null + ? factory.CreateClient(HttpApiRequestToolConstants.HttpClientName) + : new HttpClient(); + } + + private IDisposable CreateTimeoutScope(CancellationToken cancellationToken, out CancellationToken effectiveToken) + { + if (_settings.TimeoutSeconds is > 0) + { + var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + cts.CancelAfter(TimeSpan.FromSeconds(_settings.TimeoutSeconds.Value)); + effectiveToken = cts.Token; + + return cts; + } + + effectiveToken = cancellationToken; + + return new NoopDisposable(); + } + + private static string Protect(IServiceProvider services, string value) + { + if (string.IsNullOrEmpty(value)) + { + return value; + } + + var provider = services?.GetService(); + + if (provider is null) + { + return value; + } + + return provider + .CreateProtector(HttpApiRequestToolConstants.DataProtectionPurpose) + .Protect(value); + } + + private static string Unprotect(IServiceProvider services, string value) + { + if (string.IsNullOrEmpty(value)) + { + return value; + } + + var provider = services?.GetService(); + + if (provider is null) + { + return value; + } + + try + { + return provider + .CreateProtector(HttpApiRequestToolConstants.DataProtectionPurpose) + .Unprotect(value); + } + catch (System.Security.Cryptography.CryptographicException) + { + // The value was not protected (for example, seeded from configuration); use it as-is. + return value; + } + } + + private static string CombineUrl(string baseUrl, string path) + { + // The model-provided path is always treated as a relative segment appended to the configured base + // URL. Absolute URLs are never honored here so the model cannot redirect the request to a different + // host; BuildRequestUri additionally verifies the final host matches the configured base host. + return $"{baseUrl.TrimEnd('/')}/{path.TrimStart('/')}"; + } + + private static bool TryGetString(AIFunctionArguments arguments, string key, out string value) + { + if (arguments.TryGetValue(key, out var raw) && raw is not null) + { + value = raw is JsonElement { ValueKind: JsonValueKind.String } element + ? element.GetString() + : raw.ToString(); + + return !string.IsNullOrEmpty(value); + } + + value = null; + + return false; + } + + private static bool TryReadObject(object value, out IReadOnlyDictionary result) + { + switch (value) + { + case JsonElement { ValueKind: JsonValueKind.Object } element: + var fromElement = new Dictionary(StringComparer.Ordinal); + + foreach (var property in element.EnumerateObject()) + { + fromElement[property.Name] = property.Value.ValueKind == JsonValueKind.String + ? property.Value.GetString() + : property.Value.GetRawText(); + } + + result = fromElement; + + return true; + + case IReadOnlyDictionary dictionary: + result = dictionary; + + return true; + + default: + result = null; + + return false; + } + } + + private static string Error(string message) + => JsonSerializer.Serialize(new { success = false, error = message }); + + private static JsonElement BuildSchema(HttpApiRequestToolSettings settings) + { + var properties = new JsonObject(); + + if (settings.AllowModelProvidedPath) + { + properties["path"] = new JsonObject + { + ["type"] = "string", + ["description"] = "Optional relative path appended to the configured base URL.", + }; + } + + if (settings.AllowModelProvidedQuery) + { + properties["query"] = new JsonObject + { + ["type"] = "object", + ["description"] = "Optional query string parameters to append to the request.", + ["additionalProperties"] = new JsonObject { ["type"] = "string" }, + }; + } + + if (settings.AllowModelProvidedBody) + { + properties["body"] = new JsonObject + { + ["type"] = "object", + ["description"] = "Optional JSON request body to send for POST/PUT/PATCH/DELETE requests.", + ["additionalProperties"] = true, + }; + } + + var schema = new JsonObject + { + ["type"] = "object", + ["properties"] = properties, + ["additionalProperties"] = false, + }; + + return JsonSerializer.SerializeToElement(schema); + } + + private sealed class NoopDisposable : IDisposable + { + public void Dispose() + { + } + } + + private sealed class OAuthTokenResult + { + public string AccessToken { get; set; } + + public string RefreshToken { get; set; } + + public string TokenType { get; set; } + + public int? ExpiresInSeconds { get; set; } + } +} diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolInstanceSource.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolInstanceSource.cs new file mode 100644 index 00000000..33c53db7 --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolInstanceSource.cs @@ -0,0 +1,35 @@ +using CrestApps.Core; +using Microsoft.Extensions.AI; + +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// The built-in that lets users configure calls to arbitrary HTTP +/// APIs. Each configured binds a base URL, HTTP method, authentication, and +/// static headers; the AI model only supplies the open arguments the settings allow. Display metadata +/// (name, description, category) is supplied at registration time via +/// AddAIToolInstanceSource<HttpApiRequestToolInstanceSource>(...). +/// +public sealed class HttpApiRequestToolInstanceSource : IAIToolInstanceSource +{ + /// + /// Creates the bound to the supplied instance's settings. + /// + /// The configured tool instance whose settings should be bound to the produced tool. + /// The configured HTTP request function. + public AITool CreateTool(AIToolInstance instance) + { + ArgumentNullException.ThrowIfNull(instance); + + var settings = instance.TryGet(out var stored) + ? stored + : new HttpApiRequestToolSettings(); + + var functionName = instance.GetFunctionName(); + var description = string.IsNullOrWhiteSpace(instance.Description) + ? functionName + : instance.Description; + + return new HttpApiRequestToolFunction(functionName, description, settings, instance); + } +} diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolServiceCollectionExtensions.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolServiceCollectionExtensions.cs new file mode 100644 index 00000000..0a2ce14e --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolServiceCollectionExtensions.cs @@ -0,0 +1,45 @@ +using CrestApps.Core.Builders; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Localization; + +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// Convenience registration for the built-in , a generic +/// "call any HTTP API" tool that users configure per instance (endpoint, HTTP method, authentication, and +/// static headers). The AI model only supplies the open arguments the instance's settings allow. +/// +public static class HttpApiRequestToolServiceCollectionExtensions +{ + /// + /// Registers the named and the built-in HTTP API request + /// source on the tool instances builder so users can create configured instances from it. + /// + /// The tool instances builder. + /// + /// An optional delegate used to override the source display metadata (display name, description, + /// category). Sensible defaults are applied when not overridden. + /// + /// The tool instances builder, for chaining. + public static CrestAppsAIToolInstancesBuilder AddHttpApiRequestSource( + this CrestAppsAIToolInstancesBuilder builder, + Action configure = null) + { + ArgumentNullException.ThrowIfNull(builder); + + builder.Services.AddHttpClient(HttpApiRequestToolConstants.HttpClientName); + + builder.AddSource(HttpApiRequestToolConstants.SourceName, entry => + { + entry.DisplayName = new LocalizedString(HttpApiRequestToolConstants.SourceName, "HTTP API Request"); + entry.Description = new LocalizedString( + HttpApiRequestToolConstants.SourceName, + "Calls an external HTTP API using preconfigured settings (endpoint, authentication, headers)."); + entry.Category = new LocalizedString("Integrations", "Integrations"); + + configure?.Invoke(entry); + }); + + return builder; + } +} diff --git a/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolSettings.cs b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolSettings.cs new file mode 100644 index 00000000..ce5f237a --- /dev/null +++ b/src/Primitives/CrestApps.Core.AI/Tooling/Instances/HttpApiRequestToolSettings.cs @@ -0,0 +1,100 @@ +namespace CrestApps.Core.AI.Tooling.Instances; + +/// +/// The user-provided settings that configure a single HTTP API request tool instance. These values are +/// captured up front by the user (not by the AI model) and are persisted in the instance's properties. +/// +public sealed class HttpApiRequestToolSettings +{ + /// + /// Gets or sets the base URL the request targets. The model may append a relative path when + /// is enabled. + /// + public string BaseUrl { get; set; } + + /// + /// Gets or sets the HTTP method to use (for example, GET, POST, PUT, + /// PATCH, or DELETE). Defaults to GET. + /// + public string HttpMethod { get; set; } = "GET"; + + /// + /// Gets or sets the authentication strategy applied to the request. + /// + public HttpApiRequestAuthenticationType AuthenticationType { get; set; } + + /// + /// Gets or sets the header name used when is + /// . Defaults to X-Api-Key. + /// + public string ApiKeyHeaderName { get; set; } + + /// + /// Gets or sets the API key value used for API key authentication. May be data-protected at rest. + /// + public string ApiKey { get; set; } + + /// + /// Gets or sets the bearer token used for bearer authentication. May be data-protected at rest. + /// + public string BearerToken { get; set; } + + /// + /// Gets or sets the username used for basic authentication, or the resource owner username used for + /// the OAuth 2.0 password grant when is + /// . + /// + public string Username { get; set; } + + /// + /// Gets or sets the password used for basic authentication, or the resource owner password used for + /// the OAuth 2.0 password grant. May be data-protected at rest. + /// + public string Password { get; set; } + + /// + /// Gets or sets the OAuth 2.0 token endpoint the tool requests access tokens from when + /// is . + /// + public string TokenEndpoint { get; set; } + + /// + /// Gets or sets the OAuth 2.0 client identifier. + /// + public string ClientId { get; set; } + + /// + /// Gets or sets the OAuth 2.0 client secret. May be data-protected at rest. + /// + public string ClientSecret { get; set; } + + /// + /// Gets or sets the optional OAuth 2.0 scope requested when acquiring an access token. + /// + public string Scope { get; set; } + + /// + /// Gets or sets static headers that are always added to the request. + /// + public Dictionary DefaultHeaders { get; set; } + + /// + /// Gets or sets whether the AI model may supply a relative path appended to . + /// + public bool AllowModelProvidedPath { get; set; } = true; + + /// + /// Gets or sets whether the AI model may supply query string parameters. + /// + public bool AllowModelProvidedQuery { get; set; } = true; + + /// + /// Gets or sets whether the AI model may supply a request body (for methods that support one). + /// + public bool AllowModelProvidedBody { get; set; } = true; + + /// + /// Gets or sets an optional per-request timeout in seconds. + /// + public int? TimeoutSeconds { get; set; } +} diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Areas/ChatInteractions/Hubs/ChatInteractionHub.cs b/src/Startup/CrestApps.Core.Blazor.Web/Areas/ChatInteractions/Hubs/ChatInteractionHub.cs index f23b5873..6fbc35be 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Areas/ChatInteractions/Hubs/ChatInteractionHub.cs +++ b/src/Startup/CrestApps.Core.Blazor.Web/Areas/ChatInteractions/Hubs/ChatInteractionHub.cs @@ -1,10 +1,14 @@ +using System.Text.Json; using CrestApps.Core.AI.Chat.Hubs; using CrestApps.Core.AI.Chat.Services; using CrestApps.Core.AI.Models; using CrestApps.Core.AI.ResponseHandling; +using CrestApps.Core.AI.Tooling; using CrestApps.Core.Blazor.Web.Areas.ChatInteractions.Models; +using CrestApps.Core.Services; using CrestApps.Core.Startup.Shared.Services; using Microsoft.AspNetCore.Authorization; +using Microsoft.Extensions.DependencyInjection; namespace CrestApps.Core.Blazor.Web.Areas.ChatInteractions.Hubs; @@ -56,6 +60,27 @@ protected override Task IsTextToSpeechPlaybackEnabledAsync(IServiceProvide return Task.FromResult(settings.EnableTextToSpeechPlayback); } + protected override async Task ApplyCoreSettingsAsync( + IServiceProvider services, + ChatInteraction interaction, + JsonElement settings) + { + await base.ApplyCoreSettingsAsync(services, interaction, settings); + + var validToolInstanceNames = (await services.GetRequiredService>().GetAllAsync()) + .Select(instance => instance.Name) + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + interaction.Alter(metadata => + { + metadata.ToolInstanceNames = (JsonHelper.GetStringArray(settings, "toolInstanceNames") ?? []) + .Where(name => !string.IsNullOrWhiteSpace(name) && validToolInstanceNames.Contains(name)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToArray(); + }); + } + protected override Task GetDeploymentSettingsAsync(IServiceProvider services) { return Task.FromResult(_siteSettings.Get()); diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Layout/NavMenu.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Layout/NavMenu.razor index 86172d70..06e9bc7d 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Components/Layout/NavMenu.razor +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Layout/NavMenu.razor @@ -26,6 +26,11 @@ AI Profiles +
  • + + AI Tool Instances + +
  • Index Profiles diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Create.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Create.razor index eafe94df..1c9a37b3 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Create.razor +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Create.razor @@ -29,6 +29,7 @@ @inject ICatalog DeploymentCatalog @inject ICatalog A2ACatalog @inject ICatalog McpCatalog +@inject ISourceCatalog ToolInstanceCatalog @inject IAIDataSourceStore DataSourceStore @inject ISearchIndexProfileStore IndexProfileStore @inject ITemplateService TemplateService @@ -669,6 +670,31 @@ } } + +
    AI Tool Instances
    + @if (_model.AvailableToolInstances.Count == 0) + { +
    No tool instances are configured. Add them under AI Tool Instances first.
    + } + else + { +

    Select the preconfigured tool instances this profile can use. Each instance carries its own settings and description.

    + @foreach (var instance in _model.AvailableToolInstances) + { +
    + + +
    + } + } +
    AI Tools
    @if (_model.AvailableTools.Count == 0) @@ -1259,6 +1285,7 @@ _model.SelectedAgentNames = await GetValidAgentNamesAsync(_model.SelectedAgentNames); _model.SelectedA2AConnectionIds = await GetValidA2AConnectionIdsAsync(_model.SelectedA2AConnectionIds); _model.SelectedMcpConnectionIds = await GetValidMcpConnectionIdsAsync(_model.SelectedMcpConnectionIds); + _model.SelectedToolInstanceNames = await GetValidToolInstanceNamesAsync(_model.SelectedToolInstanceNames); var profile = new AIProfile { Type = AIProfileType.Chat }; _model.ApplyTo(profile); @@ -1288,6 +1315,7 @@ _model.SelectedAgentNames = _model.AvailableAgents.Where(a => a.IsSelected).Select(a => a.Name).ToArray(); _model.SelectedA2AConnectionIds = _model.AvailableA2AConnections.Where(c => c.IsSelected).Select(c => c.ItemId).ToArray(); _model.SelectedMcpConnectionIds = _model.AvailableMcpConnections.Where(c => c.IsSelected).Select(c => c.ItemId).ToArray(); + _model.SelectedToolInstanceNames = _model.AvailableToolInstances.Where(i => i.IsSelected).Select(i => i.Name).ToArray(); } private void ToggleTool(string name, bool isSelected) @@ -1326,6 +1354,15 @@ } } + private void ToggleToolInstance(string id, bool isSelected) + { + var instance = _model.AvailableToolInstances.FirstOrDefault(i => i.ItemId == id); + if (instance != null) + { + instance.IsSelected = isSelected; + } + } + private void SelectAllTools() { foreach (var t in _model.AvailableTools) t.IsSelected = true; } private void DeselectAllTools() { foreach (var t in _model.AvailableTools) t.IsSelected = false; } @@ -1490,6 +1527,19 @@ IsSelected = selectedMcpIds.Contains(c.ItemId), }).ToList(); + var toolInstances = await ToolInstanceCatalog.GetAllAsync(); + var selectedToolInstanceNames = new HashSet(_model.SelectedToolInstanceNames ?? [], StringComparer.OrdinalIgnoreCase); + _model.AvailableToolInstances = toolInstances + .OrderBy(i => i.Name, StringComparer.OrdinalIgnoreCase) + .Select(i => new AIToolInstanceSelectionItem + { + ItemId = i.ItemId, + Name = i.Name, + Description = i.Description, + Source = i.Source, + IsSelected = selectedToolInstanceNames.Contains(i.Name), + }).ToList(); + var allAgents = await ProfileManager.GetAsync(AIProfileType.Agent) ?? []; var selectedAgentNames = new HashSet(_model.SelectedAgentNames ?? [], StringComparer.OrdinalIgnoreCase); _model.AvailableAgents = allAgents @@ -1583,6 +1633,16 @@ return (selectedIds ?? []).Where(id => !string.IsNullOrWhiteSpace(id) && allIds.Contains(id)).Distinct(StringComparer.Ordinal).ToArray(); } + private async Task GetValidToolInstanceNamesAsync(IEnumerable selectedNames) + { + var allNames = (await ToolInstanceCatalog.GetAllAsync()) + .Select(i => i.Name) + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + return (selectedNames ?? []).Where(name => !string.IsNullOrWhiteSpace(name) && allNames.Contains(name)).Distinct(StringComparer.OrdinalIgnoreCase).ToArray(); + } + private async Task PopulateVoiceOptionsAsync(IEnumerable deployments) { _availableVoices = []; diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Edit.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Edit.razor index ab13c4f2..02111225 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Edit.razor +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/AI/AIProfiles/Edit.razor @@ -30,6 +30,7 @@ @inject ICatalog DeploymentCatalog @inject ICatalog A2ACatalog @inject ICatalog McpCatalog +@inject ISourceCatalog ToolInstanceCatalog @inject IAIDataSourceStore DataSourceStore @inject IAIDocumentStore DocumentStore @inject ISearchIndexProfileStore IndexProfileStore @@ -617,6 +618,30 @@ else if (_model != null) } } +
    AI Tool Instances
    + @if (_model.AvailableToolInstances.Count == 0) + { +
    No tool instances are configured. Add them under AI Tool Instances first.
    + } + else + { +

    Select the preconfigured tool instances this profile can use. Each instance carries its own settings and description.

    + @foreach (var instance in _model.AvailableToolInstances) + { +
    + + +
    + } + } +
    AI Tools
    @if (_model.AvailableTools.Count == 0) { @@ -1152,6 +1177,7 @@ else if (_model != null) _model.SelectedAgentNames = await GetValidAgentNamesAsync(_model.SelectedAgentNames); _model.SelectedA2AConnectionIds = await GetValidA2AConnectionIdsAsync(_model.SelectedA2AConnectionIds); _model.SelectedMcpConnectionIds = await GetValidMcpConnectionIdsAsync(_model.SelectedMcpConnectionIds); + _model.SelectedToolInstanceNames = await GetValidToolInstanceNamesAsync(_model.SelectedToolInstanceNames); _model.ApplyTo(existing); if (_removedDocumentIds.Count > 0) @@ -1181,12 +1207,14 @@ else if (_model != null) _model.SelectedAgentNames = _model.AvailableAgents.Where(a => a.IsSelected).Select(a => a.Name).ToArray(); _model.SelectedA2AConnectionIds = _model.AvailableA2AConnections.Where(c => c.IsSelected).Select(c => c.ItemId).ToArray(); _model.SelectedMcpConnectionIds = _model.AvailableMcpConnections.Where(c => c.IsSelected).Select(c => c.ItemId).ToArray(); + _model.SelectedToolInstanceNames = _model.AvailableToolInstances.Where(i => i.IsSelected).Select(i => i.Name).ToArray(); } private void ToggleTool(string name, bool v) { var t = _model.AvailableTools.FirstOrDefault(x => x.Name == name); if (t != null) t.IsSelected = v; } private void ToggleAgent(string name, bool v) { var a = _model.AvailableAgents.FirstOrDefault(x => x.Name == name); if (a != null) a.IsSelected = v; } private void ToggleA2A(string id, bool v) { var c = _model.AvailableA2AConnections.FirstOrDefault(x => x.ItemId == id); if (c != null) c.IsSelected = v; } private void ToggleMcp(string id, bool v) { var c = _model.AvailableMcpConnections.FirstOrDefault(x => x.ItemId == id); if (c != null) c.IsSelected = v; } + private void ToggleToolInstance(string id, bool v) { var i = _model.AvailableToolInstances.FirstOrDefault(x => x.ItemId == id); if (i != null) i.IsSelected = v; } private void SelectAllTools() { foreach (var t in _model.AvailableTools) t.IsSelected = true; } private void DeselectAllTools() { foreach (var t in _model.AvailableTools) t.IsSelected = false; } private void AddExtractionEntry() => _model.DataExtractionEntries.Add(new DataExtractionEntryItem()); @@ -1345,6 +1373,11 @@ else if (_model != null) _model.AvailableMcpConnections = mcpConnections.OrderBy(c => c.DisplayText, StringComparer.OrdinalIgnoreCase) .Select(c => new McpConnectionSelectionItem { ItemId = c.ItemId, DisplayText = c.DisplayText, Source = c.Source, IsSelected = selectedMcpIds.Contains(c.ItemId) }).ToList(); + var toolInstances = await ToolInstanceCatalog.GetAllAsync(); + var selectedToolInstanceNames = new HashSet(_model.SelectedToolInstanceNames ?? [], StringComparer.OrdinalIgnoreCase); + _model.AvailableToolInstances = toolInstances.OrderBy(i => i.Name, StringComparer.OrdinalIgnoreCase) + .Select(i => new AIToolInstanceSelectionItem { ItemId = i.ItemId, Name = i.Name, Description = i.Description, Source = i.Source, IsSelected = selectedToolInstanceNames.Contains(i.Name) }).ToList(); + var allAgents = await ProfileManager.GetAsync(AIProfileType.Agent) ?? []; var selectedAgentNames = new HashSet(_model.SelectedAgentNames ?? [], StringComparer.OrdinalIgnoreCase); _model.AvailableAgents = allAgents.Where(a => a.IsUserSelectableAgent()).OrderBy(a => a.DisplayText ?? a.Name, StringComparer.OrdinalIgnoreCase) @@ -1414,6 +1447,16 @@ else if (_model != null) return (selectedIds ?? []).Where(id => !string.IsNullOrWhiteSpace(id) && allIds.Contains(id)).Distinct(StringComparer.Ordinal).ToArray(); } + private async Task GetValidToolInstanceNamesAsync(IEnumerable selectedNames) + { + var allNames = (await ToolInstanceCatalog.GetAllAsync()) + .Select(i => i.Name) + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + return (selectedNames ?? []).Where(name => !string.IsNullOrWhiteSpace(name) && allNames.Contains(name)).Distinct(StringComparer.OrdinalIgnoreCase).ToArray(); + } + private async Task PopulateVoiceOptionsAsync(IEnumerable deployments) { _availableVoices = []; diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Chat.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Chat.razor index 365cae94..efee39bd 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Chat.razor +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Chat.razor @@ -24,6 +24,7 @@ @inject ICatalog DeploymentCatalog @inject ICatalog A2AConnectionCatalog @inject ICatalog McpConnectionCatalog +@inject ISourceCatalog ToolInstanceCatalog @inject ICatalog DataSourceCatalog @inject IAIProfileManager ProfileManager @inject IAIProfileTemplateManager TemplateManager @@ -355,6 +356,38 @@ else +
    +
    Tool Instances
    + @if (_model.AvailableToolInstances.Count == 0) + { +
    + No tool instances configured. +
    + } + else + { +
    + @foreach (var item in _model.AvailableToolInstances) + { + + } +
    + } +
    +
    Agents
    @if (_model.AvailableAgents.Count == 0) @@ -536,6 +569,7 @@ else interaction.TryGet(out var ragMetadata); interaction.TryGet(out var promptTemplateMetadata); interaction.TryGet(out var documentMetadata); + interaction.TryGet(out var toolInstanceMetadata); var hasSpeechToText = !string.IsNullOrWhiteSpace(deploymentDefaults.DefaultSpeechToTextDeploymentName); var hasTextToSpeech = !string.IsNullOrWhiteSpace(deploymentDefaults.DefaultTextToSpeechDeploymentName); @@ -585,6 +619,7 @@ else SelectedA2AConnectionIds = interaction.A2AConnectionIds?.ToArray() ?? [], SelectedMcpConnectionIds = interaction.McpConnectionIds?.ToArray() ?? [], SelectedToolNames = interaction.ToolNames?.ToArray() ?? [], + SelectedToolInstanceNames = toolInstanceMetadata?.ToolInstanceNames ?? [], SelectedAgentNames = interaction.AgentNames?.ToArray() ?? [], PromptTemplates = promptTemplateMetadata?.Templates?.Select(selection => new PromptTemplateSelectionItem { @@ -732,6 +767,19 @@ else .ThenBy(t => t.Title, StringComparer.OrdinalIgnoreCase) .ToList(); + var toolInstances = await ToolInstanceCatalog.GetAllAsync(); + model.AvailableToolInstances = toolInstances + .OrderBy(i => i.Name, StringComparer.OrdinalIgnoreCase) + .Select(i => new AIToolInstanceSelectionItem + { + ItemId = i.ItemId, + Name = i.Name, + Description = i.Description, + Source = i.Source, + IsSelected = model.SelectedToolInstanceNames.Contains(i.Name, StringComparer.OrdinalIgnoreCase), + }) + .ToList(); + var agentProfiles = await ProfileManager.GetAsync(AIProfileType.Agent); model.AvailableAgents = agentProfiles .Where(p => p.IsUserSelectableAgent()) diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Create.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Create.razor index 4cfbd131..9429ee1f 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Create.razor +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/ChatInteractions/Create.razor @@ -24,6 +24,7 @@ @inject ICatalog DeploymentCatalog @inject ICatalog A2AConnectionCatalog @inject ICatalog McpConnectionCatalog +@inject ISourceCatalog ToolInstanceCatalog @inject ICatalog DataSourceCatalog @inject IAIProfileManager ProfileManager @inject IAIProfileTemplateManager TemplateManager @@ -305,6 +306,34 @@ } } + +
    Tool Instances
    + @if (_model.AvailableToolInstances.Count == 0) + { +
    + No tool instances are configured. +
    + } + else + { +

    Select the preconfigured tool instances this interaction can use. Each instance carries its own settings and description.

    + @foreach (var instance in _model.AvailableToolInstances) + { +
    + + +
    + } + } +
    Agent to Agent Hosts
    @if (_model.AvailableA2AConnections.Count == 0) @@ -512,6 +541,21 @@ .OrderBy(t => t.Category).ThenBy(t => t.Title) .ToList(); + // AI Tool Instances + var toolInstances = await ToolInstanceCatalog.GetAllAsync(); + var selectedToolInstanceNames = new HashSet(_model.SelectedToolInstanceNames ?? [], StringComparer.OrdinalIgnoreCase); + _model.AvailableToolInstances = toolInstances + .OrderBy(i => i.Name, StringComparer.OrdinalIgnoreCase) + .Select(i => new AIToolInstanceSelectionItem + { + ItemId = i.ItemId, + Name = i.Name, + Description = i.Description, + Source = i.Source, + IsSelected = selectedToolInstanceNames.Contains(i.Name), + }) + .ToList(); + // AI Agents var agentProfiles = await ProfileManager.GetAsync(AIProfileType.Agent); _model.AvailableAgents = agentProfiles @@ -628,9 +672,18 @@ interaction.A2AConnectionIds = _model.AvailableA2AConnections.Where(c => c.IsSelected).Select(c => c.ItemId).ToList(); interaction.McpConnectionIds = _model.AvailableMcpConnections.Where(c => c.IsSelected).Select(c => c.ItemId).ToList(); interaction.ToolNames = _model.AvailableTools.Where(t => t.IsSelected).Select(t => t.Name).ToList(); + _model.SelectedToolInstanceNames = _model.AvailableToolInstances.Where(i => i.IsSelected).Select(i => i.Name).ToArray(); interaction.AgentNames = _model.AvailableAgents.Where(a => a.IsSelected).Select(a => a.Name).ToList(); interaction.CreatedUtc = DateTime.UtcNow; + interaction.Alter(metadata => + { + metadata.ToolInstanceNames = _model.SelectedToolInstanceNames + .Where(name => !string.IsNullOrWhiteSpace(name)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToArray(); + }); + if (!string.IsNullOrWhiteSpace(_model.DataSourceId)) { var dataSource = await DataSourceCatalog.FindByIdAsync(_model.DataSourceId); diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Create.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Create.razor new file mode 100644 index 00000000..bb47e254 --- /dev/null +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Create.razor @@ -0,0 +1,437 @@ +@page "/tooling/instances/create" +@attribute [Authorize(Policy = "Admin")] +@using System.Text.Json +@using CrestApps.Core +@using CrestApps.Core.AI +@using CrestApps.Core.AI.Tooling +@using CrestApps.Core.AI.Tooling.Instances +@using CrestApps.Core.Blazor.Web.ViewModels +@using CrestApps.Core.Services +@using Microsoft.Extensions.Options +@inject ISourceCatalog Catalog +@inject IDataProtectionProvider DataProtectionProvider +@inject IStoreCommitter StoreCommitter +@inject NavigationManager Navigation +@inject TimeProvider TimeProvider +@inject IOptions AIOptions + +Create Tool Instance + +

    Create Tool Instance

    +
    + + + + +
    + @if (_errors.Count > 0) + { +
    + @foreach (var error in _errors) + { +
    @error
    + } +
    + } + +
    + + +
    Choose the tool source. The fields below change based on the selected source.
    +
    + +
    + + +
    This becomes the unique function name exposed to the AI model, so it must be unique.
    + +
    + +
    + + +
    Describe exactly what this instance does so the model can distinguish it from other instances.
    + +
    + + @if (string.Equals(_model.Source, HttpApiRequestToolConstants.SourceName, StringComparison.OrdinalIgnoreCase)) + { +
    Request
    + +
    + + + +
    + +
    + + + + + + + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    Authentication
    + +
    + + + @foreach (var authType in Enum.GetValues()) + { + + } + +
    + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.ApiKey) + { +
    + + + +
    + +
    + + + +
    + } + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.Bearer) + { +
    + + + +
    + } + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.Basic) + { +
    + + + +
    + +
    + + + +
    + } + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.OAuth2) + { +
    + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    + + +
    + +

    The access token is requested on demand, cached securely on the instance, and refreshed automatically. Providing a username uses the OAuth 2.0 password grant.

    + } + +
    Model-provided arguments
    +

    Choose which parts of the request the AI model is allowed to fill in at invocation time.

    + +
    + + +
    +
    + + +
    +
    + + +
    + } + +
    + + Cancel +
    +
    +     + +@code { + private AIToolInstanceViewModel _model = new() + { + Source = HttpApiRequestToolConstants.SourceName, + DefaultHeaders = "{}", + }; + + private List _errors = []; + + private void OnSourceChanged(ChangeEventArgs e) + { + _model.Source = e.Value?.ToString(); + } + + private async Task HandleSubmitAsync() + { + _errors.Clear(); + await ValidateAsync(_model, false); + + if (_errors.Count > 0) + { + return; + } + + var instance = new AIToolInstance + { + ItemId = UniqueId.GenerateId(), + Source = _model.Source, + CreatedUtc = TimeProvider.GetUtcNow().UtcDateTime, + }; + + Apply(_model, instance); + await Catalog.CreateAsync(instance); + await StoreCommitter.CommitAsync(); + Navigation.NavigateTo("/tooling/instances"); + } + + private async Task ValidateAsync(AIToolInstanceViewModel model, bool isEditing) + { + if (string.IsNullOrWhiteSpace(model.Source)) + { + _errors.Add("A source is required."); + } + else if (!AIOptions.Value.ToolInstanceSources.ContainsKey(model.Source)) + { + _errors.Add("The selected source is not registered."); + } + + if (string.IsNullOrWhiteSpace(model.Name)) + { + _errors.Add("A unique technical name is required."); + } + else if (await IsDuplicateNameAsync(model.Name, model.ItemId)) + { + _errors.Add("A tool instance with this name already exists. The name must be unique."); + } + + if (string.IsNullOrWhiteSpace(model.Description)) + { + _errors.Add("A description is required so the AI model can tell instances apart."); + } + + if (!string.Equals(model.Source, HttpApiRequestToolConstants.SourceName, StringComparison.OrdinalIgnoreCase)) + { + return; + } + + if (string.IsNullOrWhiteSpace(model.BaseUrl)) + { + _errors.Add("Base URL is required."); + } + else if (!Uri.TryCreate(model.BaseUrl, UriKind.Absolute, out _)) + { + _errors.Add("Base URL must be a valid absolute URL."); + } + + if (string.IsNullOrWhiteSpace(model.HttpMethod)) + { + _errors.Add("HTTP method is required."); + } + + switch (model.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + if (string.IsNullOrWhiteSpace(model.ApiKeyHeaderName)) + { + _errors.Add("API key header name is required."); + } + + if ((!isEditing || !model.HasApiKey) && string.IsNullOrWhiteSpace(model.ApiKey)) + { + _errors.Add("API key is required."); + } + + break; + case HttpApiRequestAuthenticationType.Bearer: + if ((!isEditing || !model.HasBearerToken) && string.IsNullOrWhiteSpace(model.BearerToken)) + { + _errors.Add("Bearer token is required."); + } + + break; + case HttpApiRequestAuthenticationType.Basic: + if (string.IsNullOrWhiteSpace(model.Username)) + { + _errors.Add("Username is required."); + } + + if ((!isEditing || !model.HasPassword) && string.IsNullOrWhiteSpace(model.Password)) + { + _errors.Add("Password is required."); + } + + break; + case HttpApiRequestAuthenticationType.OAuth2: + if (string.IsNullOrWhiteSpace(model.TokenEndpoint)) + { + _errors.Add("Token endpoint is required."); + } + else if (!Uri.TryCreate(model.TokenEndpoint, UriKind.Absolute, out _)) + { + _errors.Add("Token endpoint must be a valid absolute URL."); + } + + if (string.IsNullOrWhiteSpace(model.ClientId)) + { + _errors.Add("Client ID is required."); + } + + if ((!isEditing || !model.HasClientSecret) && string.IsNullOrWhiteSpace(model.ClientSecret)) + { + _errors.Add("Client secret is required."); + } + + if (!string.IsNullOrWhiteSpace(model.Username) && + (!isEditing || !model.HasPassword) && + string.IsNullOrWhiteSpace(model.Password)) + { + _errors.Add("Password is required when a username is provided."); + } + + break; + } + + if (!string.IsNullOrWhiteSpace(model.DefaultHeaders)) + { + try + { + _ = JsonSerializer.Deserialize>(model.DefaultHeaders); + } + catch (JsonException) + { + _errors.Add("Default headers must be a valid JSON object."); + } + } + + if (model.TimeoutSeconds is < 1 or > 600) + { + _errors.Add("Timeout must be between 1 and 600 seconds."); + } + } + + private async Task IsDuplicateNameAsync(string name, string currentItemId) + { + var existing = await Catalog.GetAllAsync(); + + return existing.Any(entry => + !string.Equals(entry.ItemId, currentItemId, StringComparison.Ordinal) && + string.Equals(entry.Name, name, StringComparison.OrdinalIgnoreCase)); + } + + private void Apply(AIToolInstanceViewModel model, AIToolInstance instance) + { + instance.Name = model.Name.Trim(); + instance.Description = model.Description.Trim(); + instance.ModifiedUtc = TimeProvider.GetUtcNow().UtcDateTime; + + var protector = DataProtectionProvider.CreateProtector(HttpApiRequestToolConstants.DataProtectionPurpose); + var existing = instance.TryGet(out var stored) ? stored : new HttpApiRequestToolSettings(); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = model.BaseUrl?.Trim(), + HttpMethod = string.IsNullOrWhiteSpace(model.HttpMethod) ? "GET" : model.HttpMethod.Trim().ToUpperInvariant(), + AuthenticationType = model.AuthenticationType, + AllowModelProvidedPath = model.AllowModelProvidedPath, + AllowModelProvidedQuery = model.AllowModelProvidedQuery, + AllowModelProvidedBody = model.AllowModelProvidedBody, + TimeoutSeconds = model.TimeoutSeconds, + DefaultHeaders = string.IsNullOrWhiteSpace(model.DefaultHeaders) + ? [] + : JsonSerializer.Deserialize>(model.DefaultHeaders) ?? [], + }; + + switch (model.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + settings.ApiKeyHeaderName = model.ApiKeyHeaderName?.Trim(); + settings.ApiKey = ProtectOrReuse(model.ApiKey, existing.ApiKey, protector); + break; + case HttpApiRequestAuthenticationType.Bearer: + settings.BearerToken = ProtectOrReuse(model.BearerToken, existing.BearerToken, protector); + break; + case HttpApiRequestAuthenticationType.Basic: + settings.Username = model.Username?.Trim(); + settings.Password = ProtectOrReuse(model.Password, existing.Password, protector); + break; + case HttpApiRequestAuthenticationType.OAuth2: + settings.TokenEndpoint = model.TokenEndpoint?.Trim(); + settings.ClientId = model.ClientId?.Trim(); + settings.ClientSecret = ProtectOrReuse(model.ClientSecret, existing.ClientSecret, protector); + settings.Username = model.Username?.Trim(); + settings.Password = ProtectOrReuse(model.Password, existing.Password, protector); + settings.Scope = model.Scope?.Trim(); + break; + } + + instance.Put(settings); + } + + private static string ProtectOrReuse(string newValue, string existingValue, IDataProtector protector) + { + return string.IsNullOrWhiteSpace(newValue) ? existingValue : protector.Protect(newValue); + } +} diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Edit.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Edit.razor new file mode 100644 index 00000000..df04ccf1 --- /dev/null +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Edit.razor @@ -0,0 +1,490 @@ +@page "/tooling/instances/edit/{Id}" +@attribute [Authorize(Policy = "Admin")] +@using System.Text.Json +@using CrestApps.Core.AI +@using CrestApps.Core.AI.Tooling +@using CrestApps.Core.AI.Tooling.Instances +@using CrestApps.Core.Blazor.Web.ViewModels +@using CrestApps.Core.Services +@using Microsoft.Extensions.Options +@inject ISourceCatalog Catalog +@inject IDataProtectionProvider DataProtectionProvider +@inject IStoreCommitter StoreCommitter +@inject NavigationManager Navigation +@inject IOptions AIOptions + +Edit Tool Instance + +

    Edit Tool Instance

    +
    + +@if (_notFound) +{ +
    Tool instance not found.
    +} +else if (_model == null) +{ +

    Loading...

    +} +else +{ + + + +
    + @if (_errors.Count > 0) + { +
    + @foreach (var error in _errors) + { +
    @error
    + } +
    + } + +
    + + +
    The source is fixed after creation.
    +
    + +
    + + +
    The name is the function name exposed to the AI model and cannot be changed after creation.
    +
    + +
    + + +
    Describe exactly what this instance does so the model can distinguish it from other instances.
    + +
    + + @if (string.Equals(_model.Source, HttpApiRequestToolConstants.SourceName, StringComparison.OrdinalIgnoreCase)) + { +
    Request
    + +
    + + + +
    + +
    + + + + + + + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    Authentication
    + +
    + + + @foreach (var authType in Enum.GetValues()) + { + + } + +
    + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.ApiKey) + { +
    + + + +
    + +
    + + + @if (_model.HasApiKey) + { +
    Leave blank to keep the existing API key.
    + } + +
    + } + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.Bearer) + { +
    + + + @if (_model.HasBearerToken) + { +
    Leave blank to keep the existing bearer token.
    + } + +
    + } + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.Basic) + { +
    + + + +
    + +
    + + + @if (_model.HasPassword) + { +
    Leave blank to keep the existing password.
    + } + +
    + } + + @if (_model.AuthenticationType == HttpApiRequestAuthenticationType.OAuth2) + { +
    + + + +
    + +
    + + + +
    + +
    + + + @if (_model.HasClientSecret) + { +
    Leave blank to keep the existing client secret.
    + } + +
    + +
    + + + +
    + +
    + + + @if (_model.HasPassword) + { +
    Leave blank to keep the existing password.
    + } + +
    + +
    + + +
    + +

    The access token is requested on demand, cached securely on the instance, and refreshed automatically. Providing a username uses the OAuth 2.0 password grant.

    + } + +
    Model-provided arguments
    +

    Choose which parts of the request the AI model is allowed to fill in at invocation time.

    + +
    + + +
    +
    + + +
    +
    + + +
    + } + +
    + + Cancel +
    +
    +     +} + +@code { + private static readonly JsonSerializerOptions _indentedJsonOptions = new() { WriteIndented = true }; + + [Parameter] + public string Id { get; set; } + + private AIToolInstanceViewModel _model; + private bool _notFound; + private List _errors = []; + + private string GetSourceDisplayName(string source) + { + if (!string.IsNullOrEmpty(source) && + AIOptions.Value.ToolInstanceSources.TryGetValue(source, out var entry)) + { + return entry.DisplayName?.Value ?? source; + } + + return source; + } + + protected override async Task OnInitializedAsync() + { + var instance = await Catalog.FindByIdAsync(Id); + + if (instance == null) + { + _notFound = true; + + return; + } + + _model = ToViewModel(instance); + } + + private async Task HandleSubmitAsync() + { + _errors.Clear(); + var instance = await Catalog.FindByIdAsync(_model.ItemId); + + if (instance == null) + { + _notFound = true; + + return; + } + + Validate(_model, true); + + if (_errors.Count > 0) + { + return; + } + + Apply(_model, instance); + await Catalog.UpdateAsync(instance); + await StoreCommitter.CommitAsync(); + Navigation.NavigateTo("/tooling/instances"); + } + + private void Validate(AIToolInstanceViewModel model, bool isEditing) + { + if (string.IsNullOrWhiteSpace(model.Name)) + { + _errors.Add("Name is required."); + } + + if (string.IsNullOrWhiteSpace(model.Description)) + { + _errors.Add("A description is required so the AI model can tell instances apart."); + } + + if (string.IsNullOrWhiteSpace(model.BaseUrl)) + { + _errors.Add("Base URL is required."); + } + else if (!Uri.TryCreate(model.BaseUrl, UriKind.Absolute, out _)) + { + _errors.Add("Base URL must be a valid absolute URL."); + } + + if (string.IsNullOrWhiteSpace(model.HttpMethod)) + { + _errors.Add("HTTP method is required."); + } + + switch (model.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + if (string.IsNullOrWhiteSpace(model.ApiKeyHeaderName)) + { + _errors.Add("API key header name is required."); + } + + if ((!isEditing || !model.HasApiKey) && string.IsNullOrWhiteSpace(model.ApiKey)) + { + _errors.Add("API key is required."); + } + + break; + case HttpApiRequestAuthenticationType.Bearer: + if ((!isEditing || !model.HasBearerToken) && string.IsNullOrWhiteSpace(model.BearerToken)) + { + _errors.Add("Bearer token is required."); + } + + break; + case HttpApiRequestAuthenticationType.Basic: + if (string.IsNullOrWhiteSpace(model.Username)) + { + _errors.Add("Username is required."); + } + + if ((!isEditing || !model.HasPassword) && string.IsNullOrWhiteSpace(model.Password)) + { + _errors.Add("Password is required."); + } + + break; + case HttpApiRequestAuthenticationType.OAuth2: + if (string.IsNullOrWhiteSpace(model.TokenEndpoint)) + { + _errors.Add("Token endpoint is required."); + } + else if (!Uri.TryCreate(model.TokenEndpoint, UriKind.Absolute, out _)) + { + _errors.Add("Token endpoint must be a valid absolute URL."); + } + + if (string.IsNullOrWhiteSpace(model.ClientId)) + { + _errors.Add("Client ID is required."); + } + + if ((!isEditing || !model.HasClientSecret) && string.IsNullOrWhiteSpace(model.ClientSecret)) + { + _errors.Add("Client secret is required."); + } + + if (!string.IsNullOrWhiteSpace(model.Username) && + (!isEditing || !model.HasPassword) && + string.IsNullOrWhiteSpace(model.Password)) + { + _errors.Add("Password is required when a username is provided."); + } + + break; + } + + if (!string.IsNullOrWhiteSpace(model.DefaultHeaders)) + { + try + { + _ = JsonSerializer.Deserialize>(model.DefaultHeaders); + } + catch (JsonException) + { + _errors.Add("Default headers must be a valid JSON object."); + } + } + + if (model.TimeoutSeconds is < 1 or > 600) + { + _errors.Add("Timeout must be between 1 and 600 seconds."); + } + } + + private void Apply(AIToolInstanceViewModel model, AIToolInstance instance) + { + instance.Description = model.Description.Trim(); + + var protector = DataProtectionProvider.CreateProtector(HttpApiRequestToolConstants.DataProtectionPurpose); + var existing = instance.TryGet(out var stored) ? stored : new HttpApiRequestToolSettings(); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = model.BaseUrl?.Trim(), + HttpMethod = string.IsNullOrWhiteSpace(model.HttpMethod) ? "GET" : model.HttpMethod.Trim().ToUpperInvariant(), + AuthenticationType = model.AuthenticationType, + AllowModelProvidedPath = model.AllowModelProvidedPath, + AllowModelProvidedQuery = model.AllowModelProvidedQuery, + AllowModelProvidedBody = model.AllowModelProvidedBody, + TimeoutSeconds = model.TimeoutSeconds, + DefaultHeaders = string.IsNullOrWhiteSpace(model.DefaultHeaders) + ? [] + : JsonSerializer.Deserialize>(model.DefaultHeaders) ?? [], + }; + + switch (model.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + settings.ApiKeyHeaderName = model.ApiKeyHeaderName?.Trim(); + settings.ApiKey = ProtectOrReuse(model.ApiKey, existing.ApiKey, protector); + break; + case HttpApiRequestAuthenticationType.Bearer: + settings.BearerToken = ProtectOrReuse(model.BearerToken, existing.BearerToken, protector); + break; + case HttpApiRequestAuthenticationType.Basic: + settings.Username = model.Username?.Trim(); + settings.Password = ProtectOrReuse(model.Password, existing.Password, protector); + break; + case HttpApiRequestAuthenticationType.OAuth2: + settings.TokenEndpoint = model.TokenEndpoint?.Trim(); + settings.ClientId = model.ClientId?.Trim(); + settings.ClientSecret = ProtectOrReuse(model.ClientSecret, existing.ClientSecret, protector); + settings.Username = model.Username?.Trim(); + settings.Password = ProtectOrReuse(model.Password, existing.Password, protector); + settings.Scope = model.Scope?.Trim(); + break; + } + + instance.Put(settings); + } + + private static string ProtectOrReuse(string newValue, string existingValue, IDataProtector protector) + { + return string.IsNullOrWhiteSpace(newValue) ? existingValue : protector.Protect(newValue); + } + + private static AIToolInstanceViewModel ToViewModel(AIToolInstance instance) + { + var model = new AIToolInstanceViewModel + { + ItemId = instance.ItemId, + Source = instance.Source, + Name = instance.Name, + Description = instance.Description, + DefaultHeaders = "{}", + }; + + if (instance.TryGet(out var settings)) + { + model.BaseUrl = settings.BaseUrl; + model.HttpMethod = string.IsNullOrWhiteSpace(settings.HttpMethod) ? "GET" : settings.HttpMethod; + model.AuthenticationType = settings.AuthenticationType; + model.ApiKeyHeaderName = string.IsNullOrWhiteSpace(settings.ApiKeyHeaderName) ? "X-Api-Key" : settings.ApiKeyHeaderName; + model.HasApiKey = !string.IsNullOrEmpty(settings.ApiKey); + model.HasBearerToken = !string.IsNullOrEmpty(settings.BearerToken); + model.Username = settings.Username; + model.HasPassword = !string.IsNullOrEmpty(settings.Password); + model.TokenEndpoint = settings.TokenEndpoint; + model.ClientId = settings.ClientId; + model.HasClientSecret = !string.IsNullOrEmpty(settings.ClientSecret); + model.Scope = settings.Scope; + model.AllowModelProvidedPath = settings.AllowModelProvidedPath; + model.AllowModelProvidedQuery = settings.AllowModelProvidedQuery; + model.AllowModelProvidedBody = settings.AllowModelProvidedBody; + model.TimeoutSeconds = settings.TimeoutSeconds; + model.DefaultHeaders = settings.DefaultHeaders is { Count: > 0 } + ? JsonSerializer.Serialize(settings.DefaultHeaders, _indentedJsonOptions) + : "{}"; + } + + return model; + } +} diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Index.razor b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Index.razor new file mode 100644 index 00000000..1cbab2bb --- /dev/null +++ b/src/Startup/CrestApps.Core.Blazor.Web/Components/Pages/Tooling/ToolInstances/Index.razor @@ -0,0 +1,106 @@ +@page "/tooling/instances" +@attribute [Authorize(Policy = "Admin")] +@using CrestApps.Core.AI.Tooling +@using CrestApps.Core.Services +@inject ISourceCatalog Catalog +@inject IStoreCommitter StoreCommitter +@inject NavigationManager Navigation +@inject IJSRuntime JS +@inject ToastNotificationService ToastNotifications + +AI Tool Instances + +
    +

    AI Tool Instances

    + + Add Instance + +
    + +

    + Tool instances are preconfigured, model-invokable functions. You supply the settings (endpoint, authentication, headers) + up front and a description so the AI model can tell instances apart. The same source can be configured multiple times. +

    + +@if (_instances == null) +{ +

    Loading...

    +} +else if (_instances.Count == 0) +{ +
    No tool instances are configured yet.
    +} +else +{ +
    + + + + + + + + + + + @foreach (var instance in _instances) + { + + + + + + + } + +
    NameSourceDescriptionActions
    @instance.Name@instance.Source@instance.Description + + Edit + + +
    +
    +} + +@code { + private List _instances; + + protected override async Task OnInitializedAsync() + { + await LoadAsync(); + } + + private async Task LoadAsync() + { + var all = await Catalog.GetAllAsync(); + + _instances = all + .OrderBy(instance => instance.Name, StringComparer.OrdinalIgnoreCase) + .ToList(); + } + + private async Task DeleteAsync(string id) + { + var confirmed = await JS.InvokeAsync("confirm", "Delete this tool instance?"); + + if (!confirmed) + { + return; + } + + var instance = await Catalog.FindByIdAsync(id); + + if (instance == null) + { + ToastNotifications.ShowError("Tool instance not found."); + + return; + } + + await Catalog.DeleteAsync(instance); + await StoreCommitter.CommitAsync(); + await LoadAsync(); + } +} diff --git a/src/Startup/CrestApps.Core.Blazor.Web/Program.cs b/src/Startup/CrestApps.Core.Blazor.Web/Program.cs index 8618a043..10a75d16 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/Program.cs +++ b/src/Startup/CrestApps.Core.Blazor.Web/Program.cs @@ -20,6 +20,7 @@ using CrestApps.Core.AI.OpenAI; using CrestApps.Core.AI.OpenAI.Azure; using CrestApps.Core.AI.PostgreSQL; +using CrestApps.Core.AI.Tooling.Instances; using CrestApps.Core.Azure.AISearch; using CrestApps.Core.Blazor.Web; using CrestApps.Core.Blazor.Web.Areas.AIChat.Endpoints; @@ -101,6 +102,10 @@ .AddEntityCoreStores() .ConfigureChatHubOptions() ) + .AddToolInstances(toolInstances => toolInstances + .AddHttpApiRequestSource() + .AddEntityCoreStores() + ) .AddDocumentProcessing(documentProcessing => documentProcessing .AddEntityCoreStores() .AddOpenXml() diff --git a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIProfileViewModel.cs b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIProfileViewModel.cs index 06272bff..5b2b2d3b 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIProfileViewModel.cs +++ b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIProfileViewModel.cs @@ -8,6 +8,7 @@ using CrestApps.Core.AI.Mcp.Models; using CrestApps.Core.AI.Models; using CrestApps.Core.AI.Security; +using CrestApps.Core.AI.Tooling; using CrestApps.Core.Templates.Models; namespace CrestApps.Core.Blazor.Web.ViewModels; @@ -107,6 +108,11 @@ public sealed class AIProfileViewModel public List AvailableMcpConnections { get; set; } = []; + // AI Tool Instances + public string[] SelectedToolInstanceNames { get; set; } = []; + + public List AvailableToolInstances { get; set; } = []; + // Prompt Templates public List PromptTemplates { get; set; } = []; @@ -312,6 +318,11 @@ public static AIProfileViewModel FromProfile(AIProfile profile) vm.SelectedMcpConnectionIds = mcpMetadata.ConnectionIds ?? []; } + if (profile.TryGet(out var toolInstanceMetadata)) + { + vm.SelectedToolInstanceNames = toolInstanceMetadata.ToolInstanceNames ?? []; + } + if (profile.TryGet(out var promptMetadata)) { vm.PromptTemplates = (promptMetadata.Templates ?? []) @@ -457,6 +468,14 @@ public void ApplyTo(AIProfile profile) .ToArray() ?? []; }); + profile.Alter(x => + { + x.ToolInstanceNames = SelectedToolInstanceNames? + .Where(name => !string.IsNullOrWhiteSpace(name)) + .Distinct(StringComparer.Ordinal) + .ToArray() ?? []; + }); + profile.Alter(a => { var agentNames = SelectedAgentNames?.Where(n => !string.IsNullOrWhiteSpace(n)).ToArray(); @@ -746,3 +765,34 @@ public sealed class McpConnectionSelectionItem public bool IsSelected { get; set; } } + +/// +/// Represents a selectable AI tool instance shown when configuring an AI profile. +/// +public sealed class AIToolInstanceSelectionItem +{ + /// + /// Gets or sets the instance identifier. + /// + public string ItemId { get; set; } + + /// + /// Gets or sets the unique instance name. Used as the stable reference stored on the profile. + /// + public string Name { get; set; } + + /// + /// Gets or sets the instance description shown to the model. + /// + public string Description { get; set; } + + /// + /// Gets or sets the source name that produced the instance. + /// + public string Source { get; set; } + + /// + /// Gets or sets a value indicating whether the instance is selected. + /// + public bool IsSelected { get; set; } +} diff --git a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIToolInstanceViewModel.cs b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIToolInstanceViewModel.cs new file mode 100644 index 00000000..921ecb11 --- /dev/null +++ b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/AIToolInstanceViewModel.cs @@ -0,0 +1,137 @@ +using System.ComponentModel.DataAnnotations; +using CrestApps.Core.AI.Tooling.Instances; + +namespace CrestApps.Core.Blazor.Web.ViewModels; + +/// +/// The view model used to create and edit an AI tool instance configured from the built-in HTTP API request source. +/// +public sealed class AIToolInstanceViewModel +{ + /// + /// Gets or sets the identifier of the instance being edited. + /// + public string ItemId { get; set; } + + /// + /// Gets or sets the tool source name (the catalog source). + /// + public string Source { get; set; } = HttpApiRequestToolConstants.SourceName; + + /// + /// Gets or sets the unique technical name used to derive the function name exposed to the AI model. + /// + [Required] + public string Name { get; set; } + + /// + /// Gets or sets the description shown to the AI model so it can distinguish this instance from other instances. + /// + [Required] + public string Description { get; set; } + + /// + /// Gets or sets the base URL the request targets. + /// + public string BaseUrl { get; set; } + + /// + /// Gets or sets the HTTP method to use. + /// + public string HttpMethod { get; set; } = "GET"; + + /// + /// Gets or sets the authentication strategy applied to the request. + /// + public HttpApiRequestAuthenticationType AuthenticationType { get; set; } + + /// + /// Gets or sets the header name used for API key authentication. + /// + public string ApiKeyHeaderName { get; set; } = "X-Api-Key"; + + /// + /// Gets or sets the API key value used for API key authentication. + /// + public string ApiKey { get; set; } + + /// + /// Gets or sets a value indicating whether a protected API key is already stored. + /// + public bool HasApiKey { get; set; } + + /// + /// Gets or sets the bearer token used for bearer authentication. + /// + public string BearerToken { get; set; } + + /// + /// Gets or sets a value indicating whether a protected bearer token is already stored. + /// + public bool HasBearerToken { get; set; } + + /// + /// Gets or sets the username used for basic authentication. + /// + public string Username { get; set; } + + /// + /// Gets or sets the password used for basic authentication. + /// + public string Password { get; set; } + + /// + /// Gets or sets a value indicating whether a protected basic password is already stored. + /// + public bool HasPassword { get; set; } + + /// + /// Gets or sets the OAuth 2.0 token endpoint used to acquire access tokens. + /// + public string TokenEndpoint { get; set; } + + /// + /// Gets or sets the OAuth 2.0 client identifier. + /// + public string ClientId { get; set; } + + /// + /// Gets or sets the OAuth 2.0 client secret. + /// + public string ClientSecret { get; set; } + + /// + /// Gets or sets a value indicating whether a protected client secret is already stored. + /// + public bool HasClientSecret { get; set; } + + /// + /// Gets or sets the optional OAuth 2.0 scope requested when acquiring an access token. + /// + public string Scope { get; set; } + + /// + /// Gets or sets the static headers, as a JSON object, always added to the request. + /// + public string DefaultHeaders { get; set; } = "{}"; + + /// + /// Gets or sets a value indicating whether the AI model may supply a relative path. + /// + public bool AllowModelProvidedPath { get; set; } = true; + + /// + /// Gets or sets a value indicating whether the AI model may supply query string parameters. + /// + public bool AllowModelProvidedQuery { get; set; } = true; + + /// + /// Gets or sets a value indicating whether the AI model may supply a request body. + /// + public bool AllowModelProvidedBody { get; set; } = true; + + /// + /// Gets or sets an optional per-request timeout in seconds. + /// + public int? TimeoutSeconds { get; set; } +} diff --git a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionChatViewModel.cs b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionChatViewModel.cs index efa08339..73c54d63 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionChatViewModel.cs +++ b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionChatViewModel.cs @@ -40,6 +40,18 @@ public sealed class ChatInteractionChatViewModel public string[] SelectedToolNames { get; set; } = []; public List AvailableTools { get; set; } = []; + // AI Tool Instances + + /// + /// Gets or sets the selected AI tool instance names. + /// + public string[] SelectedToolInstanceNames { get; set; } = []; + + /// + /// Gets or sets the available AI tool instances. + /// + public List AvailableToolInstances { get; set; } = []; + // AI Agents public string[] SelectedAgentNames { get; set; } = []; public List AvailableAgents { get; set; } = []; diff --git a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionViewModel.cs b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionViewModel.cs index d7c89a9b..17d1b285 100644 --- a/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionViewModel.cs +++ b/src/Startup/CrestApps.Core.Blazor.Web/ViewModels/ChatInteractionViewModel.cs @@ -37,6 +37,18 @@ public sealed class ChatInteractionViewModel public string[] SelectedToolNames { get; set; } = []; public List AvailableTools { get; set; } = []; + // AI Tool Instances + + /// + /// Gets or sets the selected AI tool instance names. + /// + public string[] SelectedToolInstanceNames { get; set; } = []; + + /// + /// Gets or sets the available AI tool instances. + /// + public List AvailableToolInstances { get; set; } = []; + // AI Agents public string[] SelectedAgentNames { get; set; } = []; public List AvailableAgents { get; set; } = []; diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Controllers/AIProfileController.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Controllers/AIProfileController.cs index aec10f2f..38440207 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Controllers/AIProfileController.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Controllers/AIProfileController.cs @@ -19,6 +19,7 @@ using CrestApps.Core.Mvc.Web.Areas.AIChat.Services; using CrestApps.Core.Mvc.Web.Areas.ChatInteractions.ViewModels; using CrestApps.Core.Mvc.Web.Areas.Mcp.ViewModels; +using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; using CrestApps.Core.Services; using CrestApps.Core.Startup.Shared.Services; using CrestApps.Core.Templates.Services; @@ -38,6 +39,7 @@ public sealed class AIProfileController : Controller private readonly IAIProfileTemplateManager _templateManager; private readonly ICatalog _a2aConnectionCatalog; private readonly ICatalog _mcpConnectionCatalog; + private readonly ISourceCatalog _toolInstanceCatalog; private readonly IAIDocumentStore _documentStore; private readonly AIProfileDocumentService _profileDocumentService; private readonly AIProfileTemplateDocumentService _templateDocumentService; @@ -57,6 +59,7 @@ public AIProfileController( IAIProfileTemplateManager templateManager, ICatalog a2aConnectionCatalog, ICatalog mcpConnectionCatalog, + ISourceCatalog toolInstanceCatalog, IAIDocumentStore documentStore, AIProfileDocumentService profileDocumentService, AIProfileTemplateDocumentService templateDocumentService, @@ -76,6 +79,7 @@ public AIProfileController( _templateManager = templateManager; _a2aConnectionCatalog = a2aConnectionCatalog; _mcpConnectionCatalog = mcpConnectionCatalog; + _toolInstanceCatalog = toolInstanceCatalog; _documentStore = documentStore; _profileDocumentService = profileDocumentService; _templateDocumentService = templateDocumentService; @@ -155,6 +159,7 @@ public async Task Create(AIProfileViewModel model, List Edit(AIProfileViewModel model, List model.SelectedAgentNames = await GetValidAgentNamesAsync(model.SelectedAgentNames); model.SelectedA2AConnectionIds = await GetValidA2AConnectionIdsAsync(model.SelectedA2AConnectionIds); model.SelectedMcpConnectionIds = await GetValidMcpConnectionIdsAsync(model.SelectedMcpConnectionIds); + model.SelectedToolInstanceNames = await GetValidToolInstanceNamesAsync(model.SelectedToolInstanceNames); model.ApplyTo(existing); if (RemovedDocumentIds is { Length: > 0 }) { @@ -295,6 +301,9 @@ private async Task PopulateDropdownsAsync(AIProfileViewModel model) var mcpConnections = await _mcpConnectionCatalog.GetAllAsync(); var selectedMcpIds = new HashSet(model.SelectedMcpConnectionIds ?? [], StringComparer.Ordinal); model.AvailableMcpConnections = mcpConnections.OrderBy(c => c.DisplayText, StringComparer.OrdinalIgnoreCase).Select(c => new McpConnectionSelectionItem { ItemId = c.ItemId, DisplayText = c.DisplayText, Source = c.Source, IsSelected = selectedMcpIds.Contains(c.ItemId), }).ToList(); + var toolInstances = await _toolInstanceCatalog.GetAllAsync(); + var selectedToolInstanceNames = new HashSet(model.SelectedToolInstanceNames ?? [], StringComparer.OrdinalIgnoreCase); + model.AvailableToolInstances = toolInstances.OrderBy(i => i.Name, StringComparer.OrdinalIgnoreCase).Select(i => new AIToolInstanceSelectionItem { ItemId = i.ItemId, Name = i.Name, Description = i.Description, Source = i.Source, IsSelected = selectedToolInstanceNames.Contains(i.Name), }).ToList(); var allAgents = await _profileManager.GetAsync(AIProfileType.Agent) ?? []; var selectedAgentNames = new HashSet(model.SelectedAgentNames ?? [], StringComparer.OrdinalIgnoreCase); model.AvailableAgents = allAgents.Where(a => a.IsUserSelectableAgent()).OrderBy(a => a.DisplayText ?? a.Name, StringComparer.OrdinalIgnoreCase).Select(a => new AgentSelectionItem { Name = a.Name, DisplayText = a.DisplayText ?? a.Name, Description = a.Description, IsSelected = selectedAgentNames.Contains(a.Name), }).ToList(); @@ -361,6 +370,19 @@ private async Task GetValidMcpConnectionIdsAsync(IEnumerable s .ToArray(); } + private async Task GetValidToolInstanceNamesAsync(IEnumerable selectedNames) + { + var allNames = (await _toolInstanceCatalog.GetAllAsync()) + .Select(i => i.Name) + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + return (selectedNames ?? []) + .Where(name => !string.IsNullOrWhiteSpace(name) && allNames.Contains(name)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToArray(); + } + private async Task PopulateAttachedDocumentsAsync(AIProfileViewModel model, string referenceId, string referenceType) { if (string.IsNullOrWhiteSpace(referenceId) || string.IsNullOrWhiteSpace(referenceType)) diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/ViewModels/AIProfileViewModel.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/ViewModels/AIProfileViewModel.cs index f53d47fd..971dfee7 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/ViewModels/AIProfileViewModel.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/ViewModels/AIProfileViewModel.cs @@ -8,9 +8,11 @@ using CrestApps.Core.AI.Mcp.Models; using CrestApps.Core.AI.Models; using CrestApps.Core.AI.Security; +using CrestApps.Core.AI.Tooling; using CrestApps.Core.Mvc.Web.Areas.A2A.ViewModels; using CrestApps.Core.Mvc.Web.Areas.ChatInteractions.ViewModels; using CrestApps.Core.Mvc.Web.Areas.Mcp.ViewModels; +using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; using CrestApps.Core.Templates.Models; using Microsoft.AspNetCore.Mvc.ModelBinding; using Microsoft.AspNetCore.Mvc.Rendering; @@ -101,6 +103,10 @@ public sealed class AIProfileViewModel public string[] SelectedMcpConnectionIds { get; set; } = []; public List AvailableMcpConnections { get; set; } = []; + // AI Tool Instances + public string[] SelectedToolInstanceNames { get; set; } = []; + public List AvailableToolInstances { get; set; } = []; + // Prompt Templates public List PromptTemplates { get; set; } = []; public List AvailablePromptTemplates { get; set; } = []; @@ -298,6 +304,11 @@ public static AIProfileViewModel FromProfile(AIProfile profile) vm.SelectedMcpConnectionIds = mcpMetadata.ConnectionIds ?? []; } + if (profile.TryGet(out var toolInstanceMetadata)) + { + vm.SelectedToolInstanceNames = toolInstanceMetadata.ToolInstanceNames ?? []; + } + if (profile.TryGet(out var promptMetadata)) { vm.PromptTemplates = (promptMetadata.Templates ?? []) @@ -445,6 +456,14 @@ public void ApplyTo(AIProfile profile) .ToArray() ?? []; }); + profile.Alter(x => + { + x.ToolInstanceNames = SelectedToolInstanceNames? + .Where(name => !string.IsNullOrWhiteSpace(name)) + .Distinct(StringComparer.Ordinal) + .ToArray() ?? []; + }); + profile.Alter(a => { var agentNames = SelectedAgentNames?.Where(n => !string.IsNullOrWhiteSpace(n)).ToArray(); diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Create.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Create.cshtml index b8837319..5458a7ba 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Create.cshtml +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Create.cshtml @@ -470,6 +470,36 @@ } } + +
    AI Tool Instances
    + @if (Model.AvailableToolInstances.Count == 0) + { +
    + No tool instances are configured. Add them under AI Tool Instances first. +
    + } + else + { +

    Select the preconfigured tool instances this profile can use. Each instance carries its own settings and description.

    + @foreach (var instance in Model.AvailableToolInstances) + { +
    + + +
    + } + } +
    AI Tools
    @if (Model.AvailableTools.Count == 0) diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Edit.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Edit.cshtml index 92c6603c..76c206f5 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Edit.cshtml +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/AI/Views/AIProfile/Edit.cshtml @@ -525,6 +525,36 @@ } } + +
    AI Tool Instances
    + @if (Model.AvailableToolInstances.Count == 0) + { +
    + No tool instances are configured. Add them under AI Tool Instances first. +
    + } + else + { +

    Select the preconfigured tool instances this profile can use. Each instance carries its own settings and description.

    + @foreach (var instance in Model.AvailableToolInstances) + { +
    + + +
    + } + } +
    AI Tools
    @if (Model.AvailableTools.Count == 0) diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Controllers/ChatInteractionController.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Controllers/ChatInteractionController.cs index bd3ac2b1..9d12fc36 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Controllers/ChatInteractionController.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Controllers/ChatInteractionController.cs @@ -23,6 +23,7 @@ using CrestApps.Core.Mvc.Web.Areas.ChatInteractions.Models; using CrestApps.Core.Mvc.Web.Areas.ChatInteractions.ViewModels; using CrestApps.Core.Mvc.Web.Areas.Mcp.ViewModels; +using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; using CrestApps.Core.Services; using CrestApps.Core.Startup.Shared.Services; using CrestApps.Core.Templates.Services; @@ -61,6 +62,7 @@ public sealed class ChatInteractionController : Controller private readonly IOptionsSnapshot _copilotOptions; private readonly GitHubOAuthService _oauthService; private readonly AIToolDefinitionOptions _toolOptions; + private readonly ISourceCatalog _toolInstanceCatalog; public ChatInteractionController( ICatalogManager interactionManager, @@ -85,7 +87,8 @@ public ChatInteractionController( ClaudeClientService anthropicClientService, IOptionsSnapshot copilotOptions, GitHubOAuthService oauthService, - IOptions toolOptions) + IOptions toolOptions, + ISourceCatalog toolInstanceCatalog) { _interactionManager = interactionManager; _promptStore = promptStore; @@ -110,6 +113,7 @@ public ChatInteractionController( _copilotOptions = copilotOptions; _oauthService = oauthService; _toolOptions = toolOptions.Value; + _toolInstanceCatalog = toolInstanceCatalog; } public async Task Index() @@ -199,6 +203,7 @@ public async Task Chat(string id) interaction.TryGet(out var promptMetadata); interaction.TryGet(out var anthropicMetadata); interaction.TryGet(out var documentMetadata); + interaction.TryGet(out var toolInstanceMetadata); var chatMode = chatInteractionSettings.ChatMode; var hasSpeechToText = !string.IsNullOrWhiteSpace(deploymentDefaults.DefaultSpeechToTextDeploymentName); @@ -236,6 +241,7 @@ public async Task Chat(string id) SelectedA2AConnectionIds = interaction.A2AConnectionIds?.ToArray() ?? [], SelectedMcpConnectionIds = interaction.McpConnectionIds?.ToArray() ?? [], SelectedToolNames = interaction.ToolNames?.ToArray() ?? [], + SelectedToolInstanceNames = toolInstanceMetadata?.ToolInstanceNames ?? [], SelectedAgentNames = interaction.AgentNames?.ToArray() ?? [], PromptTemplates = (promptMetadata?.Templates ?? []) .Where(template => !string.IsNullOrWhiteSpace(template.TemplateId)) @@ -358,6 +364,21 @@ private async Task PopulateDropdownsAsync(ChatInteractionViewModel model) .ThenBy(t => t.Title) .ToList(); + // AI Tool Instances + var toolInstances = await _toolInstanceCatalog.GetAllAsync(); + var selectedToolInstanceNames = new HashSet(model.SelectedToolInstanceNames ?? [], StringComparer.OrdinalIgnoreCase); + model.AvailableToolInstances = toolInstances + .OrderBy(instance => instance.Name, StringComparer.OrdinalIgnoreCase) + .Select(instance => new AIToolInstanceSelectionItem + { + ItemId = instance.ItemId, + Name = instance.Name, + Description = instance.Description, + Source = instance.Source, + IsSelected = selectedToolInstanceNames.Contains(instance.Name), + }) + .ToList(); + // AI Agents var agentProfiles = await _profileManager.GetAsync(AIProfileType.Agent); var selectedAgentNames = new HashSet(model.SelectedAgentNames ?? [], StringComparer.OrdinalIgnoreCase); @@ -498,6 +519,21 @@ private async Task PopulateChatDropdownsAsync(ChatInteractionChatViewModel model .ThenBy(t => t.Title) .ToList(); + // AI Tool Instances + var toolInstances = await _toolInstanceCatalog.GetAllAsync(); + var selectedToolInstanceNames = new HashSet(model.SelectedToolInstanceNames ?? [], StringComparer.OrdinalIgnoreCase); + model.AvailableToolInstances = toolInstances + .OrderBy(instance => instance.Name, StringComparer.OrdinalIgnoreCase) + .Select(instance => new AIToolInstanceSelectionItem + { + ItemId = instance.ItemId, + Name = instance.Name, + Description = instance.Description, + Source = instance.Source, + IsSelected = selectedToolInstanceNames.Contains(instance.Name), + }) + .ToList(); + // AI Agents var agentProfiles = await _profileManager.GetAsync(AIProfileType.Agent); var selectedAgentNames = new HashSet(model.SelectedAgentNames ?? [], StringComparer.OrdinalIgnoreCase); @@ -561,6 +597,7 @@ private async Task PopulateChatDropdownsAsync(ChatInteractionChatViewModel model private async Task ApplyMetadataAsync(ChatInteraction interaction, ChatInteractionViewModel model) { var dataSourceId = await ResolveDataSourceIdAsync(model.DataSourceId); + var toolInstanceNames = await GetValidToolInstanceNamesAsync(model.SelectedToolInstanceNames); interaction.Alter(metadata => { @@ -585,6 +622,11 @@ private async Task ApplyMetadataAsync(ChatInteraction interaction, ChatInteracti metadata.SetSelections(BuildPromptTemplateSelections(model.PromptTemplates)); }); + interaction.Alter(metadata => + { + metadata.ToolInstanceNames = toolInstanceNames.ToArray(); + }); + if (string.Equals(model.OrchestratorName, ClaudeOrchestrator.OrchestratorName, StringComparison.OrdinalIgnoreCase)) { interaction.Alter(metadata => @@ -701,6 +743,19 @@ private List GetValidToolNames(IEnumerable selectedNames) .ToList(); } + private async Task> GetValidToolInstanceNamesAsync(IEnumerable selectedNames) + { + var validToolInstanceNames = (await _toolInstanceCatalog.GetAllAsync()) + .Select(instance => instance.Name) + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + return (selectedNames ?? []) + .Where(name => !string.IsNullOrWhiteSpace(name) && validToolInstanceNames.Contains(name)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToList(); + } + private async Task> GetValidAgentNamesAsync(IEnumerable selectedNames) { var agentProfiles = await _profileManager.GetAsync(AIProfileType.Agent); diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Handlers/AIToolInstanceChatInteractionSettingsHandler.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Handlers/AIToolInstanceChatInteractionSettingsHandler.cs new file mode 100644 index 00000000..b4367957 --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Handlers/AIToolInstanceChatInteractionSettingsHandler.cs @@ -0,0 +1,97 @@ +using System.Text.Json; +using CrestApps.Core.AI.Chat; +using CrestApps.Core.AI.Models; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.Services; + +namespace CrestApps.Core.Mvc.Web.Areas.ChatInteractions.Handlers; + +/// +/// Persists AI tool instance selections from chat interaction settings updates. +/// +public sealed class AIToolInstanceChatInteractionSettingsHandler : IChatInteractionSettingsHandler +{ + private readonly ISourceCatalog _toolInstanceCatalog; + + /// + /// Initializes a new instance of the class. + /// + /// The AI tool instance catalog. + public AIToolInstanceChatInteractionSettingsHandler(ISourceCatalog toolInstanceCatalog) + { + _toolInstanceCatalog = toolInstanceCatalog; + } + + /// + /// Applies selected AI tool instance names to the interaction metadata. + /// + /// The interaction being updated. + /// The raw settings payload from the client. + /// The token to monitor for cancellation requests. + public async Task UpdatingAsync( + ChatInteraction interaction, + JsonElement settings, + CancellationToken cancellationToken = default) + { + var toolInstanceNames = await GetValidToolInstanceNamesAsync(GetStringArray(settings, "toolInstanceNames")); + + cancellationToken.ThrowIfCancellationRequested(); + + interaction.Alter(metadata => + { + metadata.ToolInstanceNames = toolInstanceNames; + }); + } + + /// + /// Handles post-save chat interaction settings updates. + /// + /// The updated interaction. + /// The raw settings payload from the client. + /// The token to monitor for cancellation requests. + public Task UpdatedAsync( + ChatInteraction interaction, + JsonElement settings, + CancellationToken cancellationToken = default) + { + return Task.CompletedTask; + } + + /// + /// Filters selected tool instance names to the names that still exist in the catalog. + /// + /// The selected tool instance names. + /// The valid selected tool instance names. + private async Task GetValidToolInstanceNamesAsync(IEnumerable selectedNames) + { + var validToolInstanceNames = (await _toolInstanceCatalog.GetAllAsync()) + .Select(instance => instance.Name) + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + return (selectedNames ?? []) + .Where(name => !string.IsNullOrWhiteSpace(name) && validToolInstanceNames.Contains(name)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToArray(); + } + + /// + /// Reads a string array from the settings payload. + /// + /// The raw settings payload from the client. + /// The property name to read. + /// The string array value, or an empty array when the property is absent. + private static string[] GetStringArray(JsonElement settings, string propertyName) + { + if (!settings.TryGetProperty(propertyName, out var property) || property.ValueKind != JsonValueKind.Array) + { + return []; + } + + return property.EnumerateArray() + .Where(item => item.ValueKind == JsonValueKind.String) + .Select(item => item.GetString()) + .Where(value => !string.IsNullOrWhiteSpace(value)) + .ToArray(); + } +} diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionChatViewModel.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionChatViewModel.cs index c5d81808..1f6edd7a 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionChatViewModel.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionChatViewModel.cs @@ -3,6 +3,7 @@ using CrestApps.Core.Mvc.Web.Areas.A2A.ViewModels; using CrestApps.Core.Mvc.Web.Areas.AI.ViewModels; using CrestApps.Core.Mvc.Web.Areas.Mcp.ViewModels; +using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; using CrestApps.Core.Templates.Models; using Microsoft.AspNetCore.Mvc.ModelBinding; using Microsoft.AspNetCore.Mvc.Rendering; @@ -47,6 +48,11 @@ internal sealed class ChatInteractionChatViewModel public List AvailableTools { get; set; } = []; + // AI Tool Instances + public string[] SelectedToolInstanceNames { get; set; } = []; + + public List AvailableToolInstances { get; set; } = []; + // AI Agents public string[] SelectedAgentNames { get; set; } = []; diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionViewModel.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionViewModel.cs index 1a121385..d627627c 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionViewModel.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/ViewModels/ChatInteractionViewModel.cs @@ -2,6 +2,7 @@ using CrestApps.Core.Mvc.Web.Areas.A2A.ViewModels; using CrestApps.Core.Mvc.Web.Areas.AI.ViewModels; using CrestApps.Core.Mvc.Web.Areas.Mcp.ViewModels; +using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; using CrestApps.Core.Templates.Models; using Microsoft.AspNetCore.Mvc.ModelBinding; using Microsoft.AspNetCore.Mvc.Rendering; @@ -42,6 +43,18 @@ public sealed class ChatInteractionViewModel public string[] SelectedToolNames { get; set; } = []; public List AvailableTools { get; set; } = []; + // AI Tool Instances + + /// + /// Gets or sets the selected AI tool instance names. + /// + public string[] SelectedToolInstanceNames { get; set; } = []; + + /// + /// Gets or sets the available AI tool instances. + /// + public List AvailableToolInstances { get; set; } = []; + // AI Agents public string[] SelectedAgentNames { get; set; } = []; public List AvailableAgents { get; set; } = []; diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Chat.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Chat.cshtml index 0b22ed1a..cb8f6d93 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Chat.cshtml +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Chat.cshtml @@ -402,6 +402,30 @@
    } + + @if (Model.AvailableToolInstances.Count > 0) + { +
    +
    AI Tool Instances
    + @foreach (var instance in Model.AvailableToolInstances) + { +
    + + +
    + } +
    + } + @if (Model.AvailableA2AConnections.Any()) { @@ -446,6 +470,7 @@ } @if (Model.AvailableAgents.Count == 0 && Model.AvailableTools.Count == 0 + && Model.AvailableToolInstances.Count == 0 && !Model.AvailableA2AConnections.Any() && !Model.AvailableMcpConnections.Any()) {
    diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Create.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Create.cshtml index 8f864688..00d14a47 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Create.cshtml +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/ChatInteractions/Views/ChatInteraction/Create.cshtml @@ -349,6 +349,36 @@ } } + +
    AI Tool Instances
    + @if (Model.AvailableToolInstances.Count == 0) + { +
    + No tool instances are configured. Add them under AI Tool Instances first. +
    + } + else + { +

    Select the preconfigured tool instances this interaction can use. Each instance carries its own settings and description.

    + @foreach (var instance in Model.AvailableToolInstances) + { +
    + + +
    + } + } +
    Agent to Agent Hosts
    @if (Model.AvailableA2AConnections.Count == 0) diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Controllers/AIToolInstanceController.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Controllers/AIToolInstanceController.cs new file mode 100644 index 00000000..758788ee --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Controllers/AIToolInstanceController.cs @@ -0,0 +1,425 @@ +using System.Text.Json; +using CrestApps.Core.AI; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.AI.Tooling.Instances; +using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; +using CrestApps.Core.Services; +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.DataProtection; +using Microsoft.AspNetCore.Mvc; +using Microsoft.AspNetCore.Mvc.Rendering; +using Microsoft.Extensions.Options; + +namespace CrestApps.Core.Mvc.Web.Areas.Tooling.Controllers; + +/// +/// Manages tool instances. Each instance is a preconfigured, model-invokable tool created from a registered +/// source; the built-in HTTP API request source carries its own endpoint, authentication, headers, and a +/// description used to disambiguate instances. +/// +[Area("Tooling")] +[Authorize(Policy = "Admin")] +public sealed class AIToolInstanceController : Controller +{ + private static readonly JsonSerializerOptions _indentedJsonOptions = new() + { + WriteIndented = true, + }; + + private readonly ISourceCatalog _catalog; + private readonly IDataProtectionProvider _dataProtectionProvider; + private readonly TimeProvider _timeProvider; + private readonly AIOptions _aiOptions; + + /// + /// Initializes a new instance of the class. + /// + /// The tool instance catalog. + /// The data protection provider used to protect secrets. + /// The time provider used for timestamps. + /// The AI options used to enumerate registered tool instance sources. + public AIToolInstanceController( + ISourceCatalog catalog, + IDataProtectionProvider dataProtectionProvider, + TimeProvider timeProvider, + IOptions aiOptions) + { + _catalog = catalog; + _dataProtectionProvider = dataProtectionProvider; + _timeProvider = timeProvider; + _aiOptions = aiOptions.Value; + } + + /// + /// Lists all configured tool instances. + /// + public async Task Index() + { + var items = (await _catalog.GetAllAsync()) + .OrderBy(instance => instance.Name, StringComparer.OrdinalIgnoreCase) + .ToList(); + + return View(items); + } + + /// + /// Renders the create form. + /// + public IActionResult Create() + { + var sources = BuildSourceList(); + + return View(new AIToolInstanceViewModel + { + Source = sources.FirstOrDefault()?.Value ?? HttpApiRequestToolConstants.SourceName, + Sources = sources, + DefaultHeaders = "{}", + }); + } + + /// + /// Handles the create form submission. + /// + /// The submitted view model. + [HttpPost] + [ValidateAntiForgeryToken] + public async Task Create(AIToolInstanceViewModel model) + { + await ValidateAsync(model, false); + + if (!ModelState.IsValid) + { + model.Sources = BuildSourceList(); + + return View(model); + } + + var instance = new AIToolInstance + { + ItemId = UniqueId.GenerateId(), + Source = model.Source, + CreatedUtc = _timeProvider.GetUtcNow().UtcDateTime, + }; + + Apply(model, instance, isNew: true); + + await _catalog.CreateAsync(instance); + + return RedirectToAction(nameof(Index)); + } + + /// + /// Renders the edit form. + /// + /// The instance identifier. + public async Task Edit(string id) + { + var instance = await _catalog.FindByIdAsync(id); + + if (instance == null) + { + return NotFound(); + } + + return View(ToViewModel(instance)); + } + + /// + /// Handles the edit form submission. + /// + /// The submitted view model. + [HttpPost] + [ValidateAntiForgeryToken] + public async Task Edit(AIToolInstanceViewModel model) + { + var instance = await _catalog.FindByIdAsync(model.ItemId); + + if (instance == null) + { + return NotFound(); + } + + model.Source = instance.Source; + + await ValidateAsync(model, true); + + if (!ModelState.IsValid) + { + model.Sources = BuildSourceList(); + + return View(model); + } + + Apply(model, instance, isNew: false); + + await _catalog.UpdateAsync(instance); + + return RedirectToAction(nameof(Index)); + } + + /// + /// Deletes a tool instance. + /// + /// The instance identifier. + [HttpPost] + [ValidateAntiForgeryToken] + public async Task Delete(string id) + { + var instance = await _catalog.FindByIdAsync(id); + + if (instance == null) + { + return NotFound(); + } + + await _catalog.DeleteAsync(instance); + + return RedirectToAction(nameof(Index)); + } + + private List BuildSourceList() + { + return _aiOptions.ToolInstanceSources + .OrderBy(entry => entry.Value.DisplayName?.Value ?? entry.Key, StringComparer.OrdinalIgnoreCase) + .Select(entry => new SelectListItem + { + Value = entry.Key, + Text = entry.Value.DisplayName?.Value ?? entry.Key, + }) + .ToList(); + } + + private async Task ValidateAsync(AIToolInstanceViewModel model, bool isEditing) + { + if (string.IsNullOrWhiteSpace(model.Source)) + { + ModelState.AddModelError(nameof(model.Source), "A source is required."); + } + else if (!_aiOptions.ToolInstanceSources.ContainsKey(model.Source)) + { + ModelState.AddModelError(nameof(model.Source), "The selected source is not registered."); + } + + if (string.IsNullOrWhiteSpace(model.Name)) + { + ModelState.AddModelError(nameof(model.Name), "A unique name is required."); + } + else + { + await ValidateUniqueNameAsync(model.Name, model.ItemId); + } + + if (string.IsNullOrWhiteSpace(model.Description)) + { + ModelState.AddModelError(nameof(model.Description), "A description is required so the AI model can tell instances apart."); + } + + if (!string.Equals(model.Source, HttpApiRequestToolConstants.SourceName, StringComparison.OrdinalIgnoreCase)) + { + return; + } + + if (string.IsNullOrWhiteSpace(model.BaseUrl)) + { + ModelState.AddModelError(nameof(model.BaseUrl), "Base URL is required."); + } + else if (!Uri.TryCreate(model.BaseUrl, UriKind.Absolute, out _)) + { + ModelState.AddModelError(nameof(model.BaseUrl), "Base URL must be a valid absolute URL."); + } + + if (string.IsNullOrWhiteSpace(model.HttpMethod)) + { + ModelState.AddModelError(nameof(model.HttpMethod), "HTTP method is required."); + } + + switch (model.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + if (string.IsNullOrWhiteSpace(model.ApiKeyHeaderName)) + { + ModelState.AddModelError(nameof(model.ApiKeyHeaderName), "API key header name is required."); + } + + if ((!isEditing || !model.HasApiKey) && string.IsNullOrWhiteSpace(model.ApiKey)) + { + ModelState.AddModelError(nameof(model.ApiKey), "API key is required."); + } + + break; + case HttpApiRequestAuthenticationType.Bearer: + if ((!isEditing || !model.HasBearerToken) && string.IsNullOrWhiteSpace(model.BearerToken)) + { + ModelState.AddModelError(nameof(model.BearerToken), "Bearer token is required."); + } + + break; + case HttpApiRequestAuthenticationType.Basic: + if (string.IsNullOrWhiteSpace(model.Username)) + { + ModelState.AddModelError(nameof(model.Username), "Username is required."); + } + + if ((!isEditing || !model.HasPassword) && string.IsNullOrWhiteSpace(model.Password)) + { + ModelState.AddModelError(nameof(model.Password), "Password is required."); + } + + break; + case HttpApiRequestAuthenticationType.OAuth2: + if (string.IsNullOrWhiteSpace(model.TokenEndpoint)) + { + ModelState.AddModelError(nameof(model.TokenEndpoint), "Token endpoint is required."); + } + else if (!Uri.TryCreate(model.TokenEndpoint, UriKind.Absolute, out _)) + { + ModelState.AddModelError(nameof(model.TokenEndpoint), "Token endpoint must be a valid absolute URL."); + } + + if (string.IsNullOrWhiteSpace(model.ClientId)) + { + ModelState.AddModelError(nameof(model.ClientId), "Client ID is required."); + } + + if ((!isEditing || !model.HasClientSecret) && string.IsNullOrWhiteSpace(model.ClientSecret)) + { + ModelState.AddModelError(nameof(model.ClientSecret), "Client secret is required."); + } + + if (!string.IsNullOrWhiteSpace(model.Username) && + (!isEditing || !model.HasPassword) && + string.IsNullOrWhiteSpace(model.Password)) + { + ModelState.AddModelError(nameof(model.Password), "Password is required when a username is provided."); + } + + break; + } + + if (!string.IsNullOrWhiteSpace(model.DefaultHeaders)) + { + try + { + _ = JsonSerializer.Deserialize>(model.DefaultHeaders); + } + catch (JsonException) + { + ModelState.AddModelError(nameof(model.DefaultHeaders), "Default headers must be a valid JSON object."); + } + } + + if (model.TimeoutSeconds is < 1 or > 600) + { + ModelState.AddModelError(nameof(model.TimeoutSeconds), "Timeout must be between 1 and 600 seconds."); + } + } + + private async Task ValidateUniqueNameAsync(string name, string currentItemId) + { + var existing = await _catalog.GetAllAsync(); + + var duplicate = existing.Any(entry => + !string.Equals(entry.ItemId, currentItemId, StringComparison.Ordinal) && + string.Equals(entry.Name, name, StringComparison.OrdinalIgnoreCase)); + + if (duplicate) + { + ModelState.AddModelError(nameof(AIToolInstanceViewModel.Name), "A tool instance with this name already exists. The name must be unique."); + } + } + + private void Apply(AIToolInstanceViewModel model, AIToolInstance instance, bool isNew) + { + if (isNew) + { + instance.Name = model.Name.Trim(); + } + + instance.Description = model.Description.Trim(); + instance.ModifiedUtc = _timeProvider.GetUtcNow().UtcDateTime; + + var protector = _dataProtectionProvider.CreateProtector(HttpApiRequestToolConstants.DataProtectionPurpose); + var existing = instance.TryGet(out var stored) ? stored : new HttpApiRequestToolSettings(); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = model.BaseUrl?.Trim(), + HttpMethod = string.IsNullOrWhiteSpace(model.HttpMethod) ? "GET" : model.HttpMethod.Trim().ToUpperInvariant(), + AuthenticationType = model.AuthenticationType, + AllowModelProvidedPath = model.AllowModelProvidedPath, + AllowModelProvidedQuery = model.AllowModelProvidedQuery, + AllowModelProvidedBody = model.AllowModelProvidedBody, + TimeoutSeconds = model.TimeoutSeconds, + DefaultHeaders = string.IsNullOrWhiteSpace(model.DefaultHeaders) + ? [] + : JsonSerializer.Deserialize>(model.DefaultHeaders) ?? [], + }; + + switch (model.AuthenticationType) + { + case HttpApiRequestAuthenticationType.ApiKey: + settings.ApiKeyHeaderName = model.ApiKeyHeaderName?.Trim(); + settings.ApiKey = ProtectOrReuse(model.ApiKey, existing.ApiKey, protector); + break; + case HttpApiRequestAuthenticationType.Bearer: + settings.BearerToken = ProtectOrReuse(model.BearerToken, existing.BearerToken, protector); + break; + case HttpApiRequestAuthenticationType.Basic: + settings.Username = model.Username?.Trim(); + settings.Password = ProtectOrReuse(model.Password, existing.Password, protector); + break; + case HttpApiRequestAuthenticationType.OAuth2: + settings.TokenEndpoint = model.TokenEndpoint?.Trim(); + settings.ClientId = model.ClientId?.Trim(); + settings.ClientSecret = ProtectOrReuse(model.ClientSecret, existing.ClientSecret, protector); + settings.Username = model.Username?.Trim(); + settings.Password = ProtectOrReuse(model.Password, existing.Password, protector); + settings.Scope = model.Scope?.Trim(); + break; + } + + instance.Put(settings); + } + + private static string ProtectOrReuse(string newValue, string existingValue, IDataProtector protector) + { + return string.IsNullOrWhiteSpace(newValue) ? existingValue : protector.Protect(newValue); + } + + private static AIToolInstanceViewModel ToViewModel(AIToolInstance instance) + { + var model = new AIToolInstanceViewModel + { + ItemId = instance.ItemId, + Source = instance.Source, + Name = instance.Name, + Description = instance.Description, + DefaultHeaders = "{}", + }; + + if (instance.TryGet(out var settings)) + { + model.BaseUrl = settings.BaseUrl; + model.HttpMethod = string.IsNullOrWhiteSpace(settings.HttpMethod) ? "GET" : settings.HttpMethod; + model.AuthenticationType = settings.AuthenticationType; + model.ApiKeyHeaderName = string.IsNullOrWhiteSpace(settings.ApiKeyHeaderName) ? "X-Api-Key" : settings.ApiKeyHeaderName; + model.HasApiKey = !string.IsNullOrEmpty(settings.ApiKey); + model.HasBearerToken = !string.IsNullOrEmpty(settings.BearerToken); + model.Username = settings.Username; + model.HasPassword = !string.IsNullOrEmpty(settings.Password); + model.TokenEndpoint = settings.TokenEndpoint; + model.ClientId = settings.ClientId; + model.HasClientSecret = !string.IsNullOrEmpty(settings.ClientSecret); + model.Scope = settings.Scope; + model.AllowModelProvidedPath = settings.AllowModelProvidedPath; + model.AllowModelProvidedQuery = settings.AllowModelProvidedQuery; + model.AllowModelProvidedBody = settings.AllowModelProvidedBody; + model.TimeoutSeconds = settings.TimeoutSeconds; + model.DefaultHeaders = settings.DefaultHeaders is { Count: > 0 } + ? JsonSerializer.Serialize(settings.DefaultHeaders, _indentedJsonOptions) + : "{}"; + } + + return model; + } +} diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/ViewModels/AIToolInstanceSelectionItem.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/ViewModels/AIToolInstanceSelectionItem.cs new file mode 100644 index 00000000..1200a4e0 --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/ViewModels/AIToolInstanceSelectionItem.cs @@ -0,0 +1,32 @@ +namespace CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; + +/// +/// Represents a selectable tool instance shown when configuring an AI profile or chat interaction. +/// +public sealed class AIToolInstanceSelectionItem +{ + /// + /// Gets or sets the instance identifier. + /// + public string ItemId { get; set; } + + /// + /// Gets or sets the unique instance name used as the stable reference. + /// + public string Name { get; set; } + + /// + /// Gets or sets the instance description shown to the model. + /// + public string Description { get; set; } + + /// + /// Gets or sets the source name that produced the instance. + /// + public string Source { get; set; } + + /// + /// Gets or sets a value indicating whether the instance is selected. + /// + public bool IsSelected { get; set; } +} diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/ViewModels/AIToolInstanceViewModel.cs b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/ViewModels/AIToolInstanceViewModel.cs new file mode 100644 index 00000000..ee8473f1 --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/ViewModels/AIToolInstanceViewModel.cs @@ -0,0 +1,145 @@ +using System.ComponentModel.DataAnnotations; +using CrestApps.Core.AI.Tooling.Instances; +using Microsoft.AspNetCore.Mvc.Rendering; + +namespace CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels; + +/// +/// The view model used to create and edit an +/// configured from the built-in HTTP API request source. +/// +public sealed class AIToolInstanceViewModel +{ + /// + /// Gets or sets the identifier of the instance being edited. + /// + public string ItemId { get; set; } + + /// + /// Gets or sets the tool source name (the catalog source). + /// + public string Source { get; set; } + + /// + /// Gets or sets the registered tool sources shown in the source dropdown when creating an instance. + /// + public IReadOnlyList Sources { get; set; } = []; + + /// + /// Gets or sets the unique name shown in the UI and used to derive the function name exposed to the AI model. + /// + [Required] + public string Name { get; set; } + + /// + /// Gets or sets the description shown to the AI model so it can distinguish this instance from + /// other instances of the same source. + /// + [Required] + public string Description { get; set; } + + /// + /// Gets or sets the base URL the request targets. + /// + public string BaseUrl { get; set; } + + /// + /// Gets or sets the HTTP method to use. + /// + public string HttpMethod { get; set; } = "GET"; + + /// + /// Gets or sets the authentication strategy applied to the request. + /// + public HttpApiRequestAuthenticationType AuthenticationType { get; set; } + + /// + /// Gets or sets the header name used for API key authentication. + /// + public string ApiKeyHeaderName { get; set; } = "X-Api-Key"; + + /// + /// Gets or sets the API key value used for API key authentication. + /// + public string ApiKey { get; set; } + + /// + /// Gets or sets a value indicating whether a protected API key is already stored. + /// + public bool HasApiKey { get; set; } + + /// + /// Gets or sets the bearer token used for bearer authentication. + /// + public string BearerToken { get; set; } + + /// + /// Gets or sets a value indicating whether a protected bearer token is already stored. + /// + public bool HasBearerToken { get; set; } + + /// + /// Gets or sets the username used for basic authentication or the OAuth 2.0 password grant. + /// + public string Username { get; set; } + + /// + /// Gets or sets the password used for basic authentication or the OAuth 2.0 password grant. + /// + public string Password { get; set; } + + /// + /// Gets or sets a value indicating whether a protected password is already stored. + /// + public bool HasPassword { get; set; } + + /// + /// Gets or sets the OAuth 2.0 token endpoint used to acquire access tokens. + /// + public string TokenEndpoint { get; set; } + + /// + /// Gets or sets the OAuth 2.0 client identifier. + /// + public string ClientId { get; set; } + + /// + /// Gets or sets the OAuth 2.0 client secret. + /// + public string ClientSecret { get; set; } + + /// + /// Gets or sets a value indicating whether a protected client secret is already stored. + /// + public bool HasClientSecret { get; set; } + + /// + /// Gets or sets the optional OAuth 2.0 scope requested when acquiring an access token. + /// + public string Scope { get; set; } + + /// + /// Gets or sets the static headers, as a JSON object, always added to the request. + /// + public string DefaultHeaders { get; set; } + + /// + /// Gets or sets a value indicating whether the AI model may supply a relative path. + /// + public bool AllowModelProvidedPath { get; set; } = true; + + /// + /// Gets or sets a value indicating whether the AI model may supply query string parameters. + /// + public bool AllowModelProvidedQuery { get; set; } = true; + + /// + /// Gets or sets a value indicating whether the AI model may supply a request body. + /// + public bool AllowModelProvidedBody { get; set; } = true; + + /// + /// Gets or sets an optional per-request timeout in seconds. + /// + public int? TimeoutSeconds { get; set; } +} diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Create.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Create.cshtml new file mode 100644 index 00000000..d1bd4e20 --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Create.cshtml @@ -0,0 +1,9 @@ +@using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels +@model AIToolInstanceViewModel +@{ + ViewData["Title"] = "Create Tool Instance"; +} + +

    Create Tool Instance

    +
    + diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Edit.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Edit.cshtml new file mode 100644 index 00000000..55c1ff0d --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Edit.cshtml @@ -0,0 +1,9 @@ +@using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels +@model AIToolInstanceViewModel +@{ + ViewData["Title"] = "Edit Tool Instance"; +} + +

    Edit Tool Instance

    +
    + diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Index.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Index.cshtml new file mode 100644 index 00000000..f28696bc --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/Index.cshtml @@ -0,0 +1,50 @@ +@model IReadOnlyCollection +@{ + ViewData["Title"] = "AI Tool Instances"; +} + +
    +

    AI Tool Instances

    + Add Instance +
    + +

    + Tool instances are preconfigured, model-invokable functions. You supply the settings (endpoint, authentication, headers) + up front and a description so the AI model can tell instances apart. The same source can be configured multiple times. +

    + +@if (!Model.Any()) +{ +
    No tool instances are configured yet.
    +} +else +{ +
    + + + + + + + + + + + @foreach (var instance in Model) + { + + + + + + + } + +
    NameSourceDescriptionActions
    @instance.Name@instance.Source@instance.Description + Edit +
    + +
    +
    +
    +} diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/_Form.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/_Form.cshtml new file mode 100644 index 00000000..ccf040be --- /dev/null +++ b/src/Startup/CrestApps.Core.Mvc.Web/Areas/Tooling/Views/AIToolInstance/_Form.cshtml @@ -0,0 +1,238 @@ +@using CrestApps.Core.AI.Tooling.Instances +@using CrestApps.Core.Mvc.Web.Areas.Tooling.ViewModels +@model AIToolInstanceViewModel + +
    + @if (!string.IsNullOrEmpty(Model.ItemId)) + { + + } +
    +
    +
    + + @if (string.IsNullOrEmpty(Model.ItemId)) + { + + +
    Choose the tool source. The fields below change based on the selected source.
    + } + else + { + + +
    The source is fixed after creation.
    + } +
    + +
    + + @if (string.IsNullOrEmpty(Model.ItemId)) + { + + +
    Shown in the UI. The model function name is derived from this value, so it must be unique. It cannot be changed after creation.
    + } + else + { + +
    The name is fixed after creation because profiles and chat interactions reference this instance by name.
    + } +
    + +
    + + +
    Describe exactly what this instance does so the model can distinguish it from other instances.
    + +
    + +
    +
    Request
    + + +
    + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    + + + +
    + +
    Authentication
    + +
    + + +
    + +
    +
    + + + +
    +
    + + + @if (Model.HasApiKey) + { +
    Leave blank to keep the existing API key.
    + } + +
    +
    + +
    +
    + + + @if (Model.HasBearerToken) + { +
    Leave blank to keep the existing bearer token.
    + } + +
    +
    + +
    +
    + + + +
    +
    + + + @if (Model.HasPassword) + { +
    Leave blank to keep the existing password.
    + } + +
    +
    + +
    +
    + + + +
    +
    + + + +
    +
    + + + @if (Model.HasClientSecret) + { +
    Leave blank to keep the existing client secret.
    + } + +
    +
    + + + +
    +
    The access token is requested on demand, cached securely on the instance, and refreshed automatically. Providing a username uses the OAuth 2.0 password grant.
    +
    + +
    Model-provided arguments
    +

    Choose which parts of the request the AI model is allowed to fill in at invocation time.

    + +
    + + +
    +
    + + +
    +
    + + +
    +
    + +
    + + Cancel +
    +
    +
    +
    + + diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Program.cs b/src/Startup/CrestApps.Core.Mvc.Web/Program.cs index beaaf3a4..23f55562 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Program.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Program.cs @@ -20,11 +20,13 @@ using CrestApps.Core.AI.OpenAI; using CrestApps.Core.AI.OpenAI.Azure; using CrestApps.Core.AI.PostgreSQL; +using CrestApps.Core.AI.Tooling.Instances; using CrestApps.Core.Azure.AISearch; using CrestApps.Core.Data.YesSql; using CrestApps.Core.Elasticsearch; using CrestApps.Core.Mvc.Web.Areas.AIChat.Endpoints; using CrestApps.Core.Mvc.Web.Areas.AIChat.Hubs; +using CrestApps.Core.Mvc.Web.Areas.ChatInteractions.Handlers; using CrestApps.Core.Mvc.Web.Areas.ChatInteractions.Hubs; using CrestApps.Core.Mvc.Web.Services; using CrestApps.Core.Mvc.Web.Tools; @@ -121,6 +123,10 @@ .AddMcpClient(mcp => mcp .AddYesSqlStores() ) + .AddToolInstances(toolInstances => toolInstances + .AddHttpApiRequestSource() + .AddYesSqlStores() + ) .AddMcpServer(mcpServer => mcpServer .AddYesSqlStores() .AddFtpResources() @@ -180,6 +186,8 @@ .WithCategory("Communications") .Selectable(); +builder.Services.AddScoped(); + // ============================================================================= // 5. BACKGROUND TASKS AND PIPELINE // ============================================================================= diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Services/YesSqlServiceCollectionExtensions.cs b/src/Startup/CrestApps.Core.Mvc.Web/Services/YesSqlServiceCollectionExtensions.cs index 7f624124..c0d91061 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Services/YesSqlServiceCollectionExtensions.cs +++ b/src/Startup/CrestApps.Core.Mvc.Web/Services/YesSqlServiceCollectionExtensions.cs @@ -19,6 +19,7 @@ using CrestApps.Core.Data.YesSql.Indexes.DataSources; using CrestApps.Core.Data.YesSql.Indexes.Indexing; using CrestApps.Core.Data.YesSql.Indexes.Mcp; +using CrestApps.Core.Data.YesSql.Indexes.Tooling; using CrestApps.Core.Elasticsearch; using CrestApps.Core.Infrastructure.Indexing; using CrestApps.Core.Mvc.Web.Areas.Admin.Indexes; @@ -143,6 +144,7 @@ public static async Task InitializeYesSqlSchemaAsync(this IServiceProvider servi await TryCreateTableAsync(() => schemaBuilder.CreateAIProviderConnectionIndexSchemaAsync(storeOptions)); await TryCreateTableAsync(() => schemaBuilder.CreateA2AConnectionIndexSchemaAsync(storeOptions)); await TryCreateTableAsync(() => schemaBuilder.CreateMcpConnectionIndexSchemaAsync(storeOptions)); + await TryCreateTableAsync(() => schemaBuilder.CreateAIToolInstanceIndexSchemaAsync(storeOptions)); await TryCreateTableAsync(() => schemaBuilder.CreateMcpPromptIndexSchemaAsync(storeOptions)); await TryCreateTableAsync(() => schemaBuilder.CreateMcpResourceIndexSchemaAsync(storeOptions)); await TryCreateTableAsync(() => schemaBuilder.CreateAIDeploymentIndexSchemaAsync(storeOptions)); diff --git a/src/Startup/CrestApps.Core.Mvc.Web/Views/Shared/_Layout.cshtml b/src/Startup/CrestApps.Core.Mvc.Web/Views/Shared/_Layout.cshtml index 69dcdaec..44024520 100644 --- a/src/Startup/CrestApps.Core.Mvc.Web/Views/Shared/_Layout.cshtml +++ b/src/Startup/CrestApps.Core.Mvc.Web/Views/Shared/_Layout.cshtml @@ -87,6 +87,11 @@ AI Profiles
    • +
  • + + AI Tool Instances + +
  • diff --git a/src/Stores/CrestApps.Core.Data.EntityCore/ServiceCollectionExtensions.cs b/src/Stores/CrestApps.Core.Data.EntityCore/ServiceCollectionExtensions.cs index bf1ba2aa..5050c89c 100644 --- a/src/Stores/CrestApps.Core.Data.EntityCore/ServiceCollectionExtensions.cs +++ b/src/Stores/CrestApps.Core.Data.EntityCore/ServiceCollectionExtensions.cs @@ -10,6 +10,7 @@ using CrestApps.Core.AI.Models; using CrestApps.Core.AI.Profiles; using CrestApps.Core.AI.Security; +using CrestApps.Core.AI.Tooling; using CrestApps.Core.Builders; using CrestApps.Core.Data.EntityCore.Services; using CrestApps.Core.Infrastructure.Indexing; @@ -89,6 +90,7 @@ public static IServiceCollection AddEntityCoreStores(this IServiceCollection ser .AddCatalogManagers(); services.AddCoreAIServicesStoresEntityCore(); + services.AddCoreAIToolInstanceStoresEntityCore(); services.AddCoreAIProfileTemplateStoresEntityCore(); services.AddCoreAIA2AClientStoresEntityCore(); services.AddCoreAIMcpClientStoresEntityCore(); @@ -131,6 +133,20 @@ public static IServiceCollection AddCoreAIServicesStoresEntityCore(this IService return services; } + /// + /// Registers EntityCore-backed stores for the AI tool instances feature. + /// This includes a named-source document catalog for . + /// + /// The service collection. + public static IServiceCollection AddCoreAIToolInstanceStoresEntityCore(this IServiceCollection services) + { + ArgumentNullException.ThrowIfNull(services); + + services.AddNamedSourceDocumentCatalog>(); + + return services; + } + /// /// Registers EntityCore-backed stores for the AI profile template feature. /// This includes a catalog for . @@ -470,6 +486,20 @@ public static CrestAppsDocumentProcessingBuilder AddEntityCoreStores(this CrestA return builder; } + /// + /// Registers EntityCore-backed stores for the AI tool instances feature on the tool instances builder. + /// This includes a named-source document catalog for . + /// + /// The builder. + public static CrestAppsAIToolInstancesBuilder AddEntityCoreStores(this CrestAppsAIToolInstancesBuilder builder) + { + ArgumentNullException.ThrowIfNull(builder); + + builder.Services.AddCoreAIToolInstanceStoresEntityCore(); + + return builder; + } + /// /// Registers EntityCore-backed stores for the AI memory feature on the AI memory builder. /// This includes . diff --git a/src/Stores/CrestApps.Core.Data.YesSql/Indexes/Tooling/AIToolInstanceIndex.cs b/src/Stores/CrestApps.Core.Data.YesSql/Indexes/Tooling/AIToolInstanceIndex.cs new file mode 100644 index 00000000..358492a4 --- /dev/null +++ b/src/Stores/CrestApps.Core.Data.YesSql/Indexes/Tooling/AIToolInstanceIndex.cs @@ -0,0 +1,53 @@ +using CrestApps.Core.AI.Tooling; +using Microsoft.Extensions.Options; +using YesSql.Indexes; + +namespace CrestApps.Core.Data.YesSql.Indexes.Tooling; + +/// +/// YesSql map index for , storing the item identifier, unique name, and +/// source to support efficient tool instance queries. +/// +public sealed class AIToolInstanceIndex : CatalogItemIndex, ISourceAwareIndex, INameAwareIndex +{ + /// + /// Gets or sets the unique technical name of the tool instance. + /// + public string Name { get; set; } + + /// + /// Gets or sets the source, i.e. the tool instance source name. + /// + public string Source { get; set; } +} + +/// +/// YesSql index provider that maps documents +/// to entries in the AI collection. +/// +public sealed class AIToolInstanceIndexProvider : IndexProvider +{ + /// + /// Initializes a new instance of the class. + /// + /// The options. + public AIToolInstanceIndexProvider(IOptions options) + { + CollectionName = options.Value.AICollectionName; + } + + /// + /// Describes the index map for documents. + /// + /// The context. + public override void Describe(DescribeContext context) + { + context.For() + .Map(instance => new AIToolInstanceIndex + { + ItemId = instance.ItemId, + Name = instance.Name, + Source = instance.Source, + }); + } +} diff --git a/src/Stores/CrestApps.Core.Data.YesSql/Indexes/Tooling/AIToolInstanceIndexSchemaBuilderExtensions.cs b/src/Stores/CrestApps.Core.Data.YesSql/Indexes/Tooling/AIToolInstanceIndexSchemaBuilderExtensions.cs new file mode 100644 index 00000000..71e8b911 --- /dev/null +++ b/src/Stores/CrestApps.Core.Data.YesSql/Indexes/Tooling/AIToolInstanceIndexSchemaBuilderExtensions.cs @@ -0,0 +1,38 @@ +using YesSql.Sql; + +namespace CrestApps.Core.Data.YesSql.Indexes.Tooling; + +/// +/// Schema builder extensions that create the table. +/// +public static class AIToolInstanceIndexSchemaBuilderExtensions +{ + /// + /// Creates the AI tool instance index schema. + /// + /// The schema builder. + /// The options. + public static async Task CreateAIToolInstanceIndexSchemaAsync(this ISchemaBuilder schemaBuilder, YesSqlStoreOptions options) + { + ArgumentNullException.ThrowIfNull(schemaBuilder); + ArgumentNullException.ThrowIfNull(options); + + await schemaBuilder.CreateMapIndexTableAsync(table => table + .Column(nameof(AIToolInstanceIndex.ItemId), column => column.WithLength(26)) + .Column(nameof(AIToolInstanceIndex.Name), column => column.WithLength(255)) + .Column(nameof(AIToolInstanceIndex.Source), column => column.WithLength(255)), + collection: options?.AICollectionName); + + await schemaBuilder.AlterIndexTableAsync( + table => table.CreateIndex("IDX_AIToolInstance_DocumentId", "DocumentId"), + collection: options?.AICollectionName); + + await schemaBuilder.AlterIndexTableAsync( + table => table.CreateIndex("IDX_AIToolInstance_Source", "DocumentId", nameof(AIToolInstanceIndex.Source)), + collection: options?.AICollectionName); + + await schemaBuilder.AlterIndexTableAsync( + table => table.CreateIndex("IDX_AIToolInstance_Name", "DocumentId", nameof(AIToolInstanceIndex.Name)), + collection: options?.AICollectionName); + } +} diff --git a/src/Stores/CrestApps.Core.Data.YesSql/ServiceCollectionExtensions.cs b/src/Stores/CrestApps.Core.Data.YesSql/ServiceCollectionExtensions.cs index d67d4b6a..6acdf82b 100644 --- a/src/Stores/CrestApps.Core.Data.YesSql/ServiceCollectionExtensions.cs +++ b/src/Stores/CrestApps.Core.Data.YesSql/ServiceCollectionExtensions.cs @@ -10,6 +10,7 @@ using CrestApps.Core.AI.Models; using CrestApps.Core.AI.Profiles; using CrestApps.Core.AI.Security; +using CrestApps.Core.AI.Tooling; using CrestApps.Core.Builders; using CrestApps.Core.Data.YesSql.Indexes; using CrestApps.Core.Data.YesSql.Indexes.A2A; @@ -20,6 +21,7 @@ using CrestApps.Core.Data.YesSql.Indexes.DataSources; using CrestApps.Core.Data.YesSql.Indexes.Indexing; using CrestApps.Core.Data.YesSql.Indexes.Mcp; +using CrestApps.Core.Data.YesSql.Indexes.Tooling; using CrestApps.Core.Data.YesSql.Services; using CrestApps.Core.Infrastructure.Indexing; using CrestApps.Core.Models; @@ -235,6 +237,36 @@ public static CrestAppsIndexingBuilder AddYesSqlStores(this CrestAppsIndexingBui return builder; } + /// + /// Registers YesSql-backed stores for the AI tool instances feature on the tool instances builder. + /// This includes a named-source document catalog for and its index provider. + /// + /// The builder. + public static CrestAppsAIToolInstancesBuilder AddYesSqlStores(this CrestAppsAIToolInstancesBuilder builder) + { + ArgumentNullException.ThrowIfNull(builder); + + builder.Services.AddCoreAIToolInstanceStoresYesSql(); + + return builder; + } + + /// + /// Registers YesSql-backed stores for the AI tool instances feature. + /// This includes a named-source document catalog for and its index provider. + /// + /// The service collection. + public static IServiceCollection AddCoreAIToolInstanceStoresYesSql(this IServiceCollection services) + { + ArgumentNullException.ThrowIfNull(services); + + AddYesSqlNamedSourceDocumentCatalog(services, static o => o.AICollectionName); + + services.TryAddEnumerable(ServiceDescriptor.Singleton()); + + return services; + } + /// /// Registers YesSql-backed stores for the core AI services feature. /// This includes a catalog for diff --git a/tests/CrestApps.Core.Tests/Tooling/AIToolInstanceTests.cs b/tests/CrestApps.Core.Tests/Tooling/AIToolInstanceTests.cs new file mode 100644 index 00000000..42e261b9 --- /dev/null +++ b/tests/CrestApps.Core.Tests/Tooling/AIToolInstanceTests.cs @@ -0,0 +1,687 @@ +using System.Net; +using System.Text.Json; +using CrestApps.Core.AI; +using CrestApps.Core.AI.Models; +using CrestApps.Core.AI.Orchestration; +using CrestApps.Core.AI.Tooling; +using CrestApps.Core.AI.Tooling.Instances; +using CrestApps.Core.Services; +using Microsoft.AspNetCore.DataProtection; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Localization; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using Moq; + +namespace CrestApps.Core.Tests.Tooling; + +public sealed class AIToolInstanceTests +{ + [Fact] + public void GetFunctionName_UsesTheInstanceName() + { + var instance = new AIToolInstance + { + ItemId = "abc123", + Source = "http-api-request", + Name = "get_weather", + }; + + var name = instance.GetFunctionName(); + + Assert.Equal("tool_instance_get_weather", name); + } + + [Fact] + public void GetFunctionName_IsPrefixedSoItCannotCollideWithCodeRegisteredTools() + { + var instance = new AIToolInstance + { + ItemId = "abc123", + Source = "http-api-request", + Name = "get-weather", + }; + + var name = instance.GetFunctionName(); + + Assert.StartsWith(AIToolInstanceExtensions.FunctionNamePrefix, name); + Assert.NotEqual("get-weather", name); + } + + [Fact] + public void GetFunctionName_SanitizesDisallowedCharacters() + { + var instance = new AIToolInstance + { + ItemId = "abc123", + Source = "http-api-request", + Name = "weird name!", + }; + + var name = instance.GetFunctionName(); + + Assert.DoesNotContain(' ', name); + Assert.DoesNotContain('!', name); + Assert.StartsWith("tool_instance_weird_name_", name); + } + + [Fact] + public void GetFunctionName_ProducesDistinctNamesWhenSanitizationWouldCollide() + { + var first = new AIToolInstance { ItemId = "one", Source = "http-api-request", Name = "weather.api" }; + var second = new AIToolInstance { ItemId = "two", Source = "http-api-request", Name = "weather_api" }; + + var firstName = first.GetFunctionName(); + var secondName = second.GetFunctionName(); + + Assert.NotEqual(firstName, secondName); + Assert.DoesNotContain('.', firstName); + Assert.True(firstName.Length <= 64); + Assert.True(secondName.Length <= 64); + } + + [Fact] + public void Clone_CreatesIndependentPropertiesCopy() + { + var original = new AIToolInstance { ItemId = "i", Source = "s", Name = "n", Description = "d" }; + original.Put(new HttpApiRequestToolSettings { BaseUrl = "https://api.example.com" }); + + var clone = original.Clone(); + clone.Put(new HttpApiRequestTokenState { AccessToken = "tok" }); + + Assert.False(original.TryGet(out _)); + Assert.True(clone.TryGet(out _)); + } + + [Fact] + public void GetFunctionName_FallsBackToItemIdWhenNameMissing() + { + var instance = new AIToolInstance + { + ItemId = "abc123", + Source = "http-api-request", + }; + + var name = instance.GetFunctionName(); + + Assert.Equal("tool_instance_abc123", name); + } + + [Fact] + public void GetFunctionName_ProducesDistinctNamesForDistinctInstances() + { + var first = new AIToolInstance { ItemId = "one", Source = "http-api-request", Name = "weather_a" }; + var second = new AIToolInstance { ItemId = "two", Source = "http-api-request", Name = "weather_b" }; + + Assert.NotEqual(first.GetFunctionName(), second.GetFunctionName()); + } + + [Fact] + public void GetFunctionName_TruncatesToSixtyFourCharacters() + { + var instance = new AIToolInstance + { + ItemId = "abc123", + Source = "source", + Name = new string('a', 100), + }; + + var name = instance.GetFunctionName(); + + Assert.True(name.Length <= 64); + } + + [Fact] + public void AddAIToolInstanceSource_RegistersKeyedSourceWithMetadata() + { + var services = new ServiceCollection(); + services.AddLogging(); + services.AddAIToolInstanceSource(HttpApiRequestToolConstants.SourceName, options => + { + options.DisplayName = new LocalizedString(HttpApiRequestToolConstants.SourceName, "HTTP API Request"); + options.Description = new LocalizedString(HttpApiRequestToolConstants.SourceName, "Calls an external HTTP API."); + options.Category = new LocalizedString("Integrations", "Integrations"); + }); + + using var provider = services.BuildServiceProvider(); + + var source = provider.GetKeyedService(HttpApiRequestToolConstants.SourceName); + + Assert.NotNull(source); + Assert.IsType(source); + + var options = provider.GetRequiredService>().Value; + + Assert.True(options.ToolInstanceSources.TryGetValue(HttpApiRequestToolConstants.SourceName, out var entry)); + Assert.Equal("Integrations", entry.Category.Value); + Assert.Equal("HTTP API Request", entry.DisplayName.Value); + } + + [Fact] + public async Task GetToolsAsync_SurfacesDistinctInstancesOfSameSource() + { + var instances = new List + { + CreateWeatherInstance("weather-a", "weather_a", "Gets weather from provider A."), + CreateWeatherInstance("weather-b", "weather_b", "Gets weather from provider B."), + }; + + var provider = BuildProvider(instances); + var registryProvider = new ToolInstanceRegistryProvider( + provider, + provider.GetRequiredService>()); + + var context = new AICompletionContext + { + ToolInstanceNames = ["weather_a", "weather_b"], + }; + + var entries = await registryProvider.GetToolsAsync(context, TestContext.Current.CancellationToken); + + Assert.Equal(2, entries.Count); + Assert.Equal(2, entries.Select(e => e.Name).Distinct().Count()); + Assert.Equal(2, entries.Select(e => e.Description).Distinct().Count()); + Assert.Contains(entries, e => e.Description == "Gets weather from provider A."); + Assert.Contains(entries, e => e.Description == "Gets weather from provider B."); + + foreach (var entry in entries) + { + var tool = await entry.CreateAsync(provider); + var function = Assert.IsAssignableFrom(tool); + Assert.Equal(entry.Name, function.Name); + Assert.Equal(entry.Description, function.Description); + } + } + + [Fact] + public async Task GetToolsAsync_ReturnsEmptyWhenNoInstanceNames() + { + var provider = BuildProvider([]); + var registryProvider = new ToolInstanceRegistryProvider( + provider, + provider.GetRequiredService>()); + + var entries = await registryProvider.GetToolsAsync(new AICompletionContext(), TestContext.Current.CancellationToken); + + Assert.Empty(entries); + } + + [Fact] + public async Task GetToolsAsync_SkipsInstancesWithUnknownSource() + { + var instances = new List + { + new() + { + ItemId = "orphan", + Source = "not-registered", + Name = "orphan", + Description = "References a missing source.", + }, + }; + + var provider = BuildProvider(instances); + var registryProvider = new ToolInstanceRegistryProvider( + provider, + provider.GetRequiredService>()); + + var context = new AICompletionContext + { + ToolInstanceNames = ["orphan"], + }; + + var entries = await registryProvider.GetToolsAsync(context, TestContext.Current.CancellationToken); + + Assert.Empty(entries); + } + + [Fact] + public async Task HttpApiRequestToolFunction_BuildsRequestFromSettingsAndModelArguments() + { + var handler = new CapturingHttpMessageHandler(HttpStatusCode.OK, "{\"ok\":true}"); + var provider = BuildHttpProvider(handler); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com/v1", + HttpMethod = "POST", + AuthenticationType = HttpApiRequestAuthenticationType.Bearer, + BearerToken = "secret-token", + DefaultHeaders = new Dictionary { ["Accept"] = "application/json" }, + AllowModelProvidedPath = true, + AllowModelProvidedQuery = true, + AllowModelProvidedBody = true, + }; + + var function = new HttpApiRequestToolFunction("weather", "Gets the weather.", settings); + + var arguments = new AIFunctionArguments + { + ["path"] = "forecast", + ["query"] = new Dictionary { ["city"] = "Seattle" }, + ["body"] = new Dictionary { ["days"] = "3" }, + Services = provider, + }; + + var result = await function.InvokeAsync(arguments, TestContext.Current.CancellationToken); + + Assert.NotNull(handler.LastRequest); + Assert.Equal(HttpMethod.Post, handler.LastRequest.Method); + Assert.Equal("https://api.example.com/v1/forecast?city=Seattle", handler.LastRequest.RequestUri!.ToString()); + Assert.Equal("Bearer", handler.LastRequest.Headers.Authorization!.Scheme); + Assert.Equal("secret-token", handler.LastRequest.Headers.Authorization.Parameter); + Assert.Contains(handler.LastRequest.Headers, h => h.Key == "Accept"); + Assert.Equal("{\"days\":\"3\"}", handler.LastRequestBody); + + using var document = JsonDocument.Parse(result!.ToString()!); + Assert.True(document.RootElement.GetProperty("success").GetBoolean()); + Assert.Equal(200, document.RootElement.GetProperty("statusCode").GetInt32()); + } + + [Fact] + public async Task HttpApiRequestToolFunction_OmitsPathWhenModelProvidedPathDisabled() + { + var handler = new CapturingHttpMessageHandler(HttpStatusCode.OK, "{}"); + var provider = BuildHttpProvider(handler); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com/fixed", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.None, + AllowModelProvidedPath = false, + AllowModelProvidedQuery = false, + AllowModelProvidedBody = false, + }; + + var function = new HttpApiRequestToolFunction("fixed", "Fixed endpoint.", settings); + + var arguments = new AIFunctionArguments + { + ["path"] = "should-be-ignored", + Services = provider, + }; + + await function.InvokeAsync(arguments, TestContext.Current.CancellationToken); + + Assert.Equal("https://api.example.com/fixed", handler.LastRequest!.RequestUri!.ToString()); + } + + [Fact] + public async Task HttpApiRequestToolFunction_KeepsModelProvidedPathOnConfiguredHost() + { + var handler = new CapturingHttpMessageHandler(HttpStatusCode.OK, "{}"); + var provider = BuildHttpProvider(handler); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com/v1", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.None, + AllowModelProvidedPath = true, + }; + + var function = new HttpApiRequestToolFunction("weather", "Gets the weather.", settings); + + var arguments = new AIFunctionArguments + { + ["path"] = "https://evil.example.net/steal", + Services = provider, + }; + + await function.InvokeAsync(arguments, TestContext.Current.CancellationToken); + + Assert.NotNull(handler.LastRequest); + Assert.Equal("api.example.com", handler.LastRequest!.RequestUri!.Host); + } + + [Fact] + public async Task HttpApiRequestToolFunction_OAuth2_AcquiresCachesAndReusesToken() + { + const string tokenEndpoint = "https://login.example.com/token"; + var handler = new OAuthRoutingHandler(tokenEndpoint, "{\"access_token\":\"tok1\",\"token_type\":\"Bearer\",\"expires_in\":3600}"); + var time = new FixedTimeProvider(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero)); + var provider = BuildOAuthProvider(handler, time); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.OAuth2, + TokenEndpoint = tokenEndpoint, + ClientId = "client", + ClientSecret = "secret", + Scope = "api.read", + AllowModelProvidedPath = false, + AllowModelProvidedQuery = false, + AllowModelProvidedBody = false, + }; + + var instance = new AIToolInstance + { + ItemId = "oauth-1", + Source = HttpApiRequestToolConstants.SourceName, + Name = "oauth_tool", + }; + instance.Put(settings); + + var function = new HttpApiRequestToolFunction("oauth_tool", "Calls an OAuth2 API.", settings, instance); + + await function.InvokeAsync(new AIFunctionArguments { Services = provider }, TestContext.Current.CancellationToken); + + Assert.Equal(1, handler.TokenRequestCount); + Assert.Single(handler.ApiRequests); + Assert.Equal("Bearer", handler.ApiRequests[0].Headers.Authorization!.Scheme); + Assert.Equal("tok1", handler.ApiRequests[0].Headers.Authorization.Parameter); + Assert.Contains("grant_type=client_credentials", handler.TokenRequestBodies[0]); + Assert.True(instance.TryGet(out var cachedState)); + Assert.Equal("tok1", cachedState.AccessToken); + + await function.InvokeAsync(new AIFunctionArguments { Services = provider }, TestContext.Current.CancellationToken); + + Assert.Equal(1, handler.TokenRequestCount); + Assert.Equal(2, handler.ApiRequests.Count); + Assert.Equal("tok1", handler.ApiRequests[1].Headers.Authorization!.Parameter); + } + + [Fact] + public async Task HttpApiRequestToolFunction_OAuth2_ProtectsCachedTokenWhenDataProtectionAvailable() + { + const string tokenEndpoint = "https://login.example.com/token"; + var handler = new OAuthRoutingHandler(tokenEndpoint, "{\"access_token\":\"tok-secret\",\"token_type\":\"Bearer\",\"expires_in\":3600}"); + var time = new FixedTimeProvider(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero)); + var provider = BuildOAuthProvider(handler, time, withDataProtection: true); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.OAuth2, + TokenEndpoint = tokenEndpoint, + ClientId = "client", + ClientSecret = "secret", + AllowModelProvidedPath = false, + AllowModelProvidedQuery = false, + AllowModelProvidedBody = false, + }; + + var instance = new AIToolInstance + { + ItemId = "oauth-dp", + Source = HttpApiRequestToolConstants.SourceName, + Name = "oauth_dp", + }; + instance.Put(settings); + + var function = new HttpApiRequestToolFunction("oauth_dp", "Calls an OAuth2 API.", settings, instance); + + await function.InvokeAsync(new AIFunctionArguments { Services = provider }, TestContext.Current.CancellationToken); + + Assert.True(instance.TryGet(out var state)); + Assert.NotEqual("tok-secret", state.AccessToken); + + var unprotected = provider + .GetRequiredService() + .CreateProtector(HttpApiRequestToolConstants.DataProtectionPurpose) + .Unprotect(state.AccessToken); + + Assert.Equal("tok-secret", unprotected); + } + + [Fact] + public async Task HttpApiRequestToolFunction_OAuth2_UsesRefreshTokenWhenAccessTokenExpired() + { + const string tokenEndpoint = "https://login.example.com/token"; + var handler = new OAuthRoutingHandler(tokenEndpoint, "{\"access_token\":\"tok2\",\"token_type\":\"Bearer\",\"expires_in\":3600}"); + var time = new FixedTimeProvider(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero)); + var provider = BuildOAuthProvider(handler, time); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.OAuth2, + TokenEndpoint = tokenEndpoint, + ClientId = "client", + ClientSecret = "secret", + AllowModelProvidedPath = false, + AllowModelProvidedQuery = false, + AllowModelProvidedBody = false, + }; + + var instance = new AIToolInstance + { + ItemId = "oauth-2", + Source = HttpApiRequestToolConstants.SourceName, + Name = "oauth_tool", + }; + instance.Put(settings); + instance.Put(new HttpApiRequestTokenState + { + AccessToken = "old-token", + RefreshToken = "refresh-1", + TokenType = "Bearer", + ExpiresAtUtc = time.GetUtcNow().AddMinutes(-5), + }); + + var function = new HttpApiRequestToolFunction("oauth_tool", "Calls an OAuth2 API.", settings, instance); + + await function.InvokeAsync(new AIFunctionArguments { Services = provider }, TestContext.Current.CancellationToken); + + Assert.Equal(1, handler.TokenRequestCount); + Assert.Contains("grant_type=refresh_token", handler.TokenRequestBodies[0]); + Assert.Contains("refresh_token=refresh-1", handler.TokenRequestBodies[0]); + Assert.Equal("tok2", handler.ApiRequests[0].Headers.Authorization!.Parameter); + } + + [Fact] + public async Task HttpApiRequestToolFunction_OAuth2_UsesPasswordGrantWhenUsernameConfigured() + { + const string tokenEndpoint = "https://login.example.com/token"; + var handler = new OAuthRoutingHandler(tokenEndpoint, "{\"access_token\":\"tok3\",\"token_type\":\"Bearer\",\"expires_in\":3600}"); + var time = new FixedTimeProvider(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero)); + var provider = BuildOAuthProvider(handler, time); + + var settings = new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.OAuth2, + TokenEndpoint = tokenEndpoint, + ClientId = "client", + ClientSecret = "secret", + Username = "resource-owner", + Password = "owner-secret", + AllowModelProvidedPath = false, + AllowModelProvidedQuery = false, + AllowModelProvidedBody = false, + }; + + var instance = new AIToolInstance + { + ItemId = "oauth-3", + Source = HttpApiRequestToolConstants.SourceName, + Name = "oauth_tool", + }; + instance.Put(settings); + + var function = new HttpApiRequestToolFunction("oauth_tool", "Calls an OAuth2 API.", settings, instance); + + await function.InvokeAsync(new AIFunctionArguments { Services = provider }, TestContext.Current.CancellationToken); + + Assert.Equal(1, handler.TokenRequestCount); + Assert.Contains("grant_type=password", handler.TokenRequestBodies[0]); + Assert.Contains("username=resource-owner", handler.TokenRequestBodies[0]); + Assert.Contains("password=owner-secret", handler.TokenRequestBodies[0]); + Assert.Equal("tok3", handler.ApiRequests[0].Headers.Authorization!.Parameter); + } + + private static AIToolInstance CreateWeatherInstance(string itemId, string name, string description) + { + var instance = new AIToolInstance + { + ItemId = itemId, + Source = HttpApiRequestToolConstants.SourceName, + Name = name, + Description = description, + }; + + instance.Put(new HttpApiRequestToolSettings + { + BaseUrl = "https://api.example.com", + HttpMethod = "GET", + AuthenticationType = HttpApiRequestAuthenticationType.None, + }); + + return instance; + } + + private static ServiceProvider BuildProvider(IReadOnlyCollection instances) + { + var catalog = new Mock>(); + catalog + .Setup(c => c.FindByNameAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync((string name, CancellationToken _) => + instances.FirstOrDefault(d => string.Equals(d.Name, name, StringComparison.OrdinalIgnoreCase))); + + var services = new ServiceCollection(); + services.AddLogging(); + services.AddSingleton(catalog.Object); + services.AddKeyedSingleton(HttpApiRequestToolConstants.SourceName); + + return services.BuildServiceProvider(); + } + + private static ServiceProvider BuildHttpProvider(CapturingHttpMessageHandler handler) + { + var services = new ServiceCollection(); + services.AddLogging(); + services.AddSingleton(new StubHttpClientFactory(handler)); + + return services.BuildServiceProvider(); + } + + private static ServiceProvider BuildOAuthProvider(HttpMessageHandler handler, TimeProvider timeProvider, bool withDataProtection = false) + { + var services = new ServiceCollection(); + services.AddLogging(); + services.AddSingleton(new StubHttpClientFactory(handler)); + services.AddSingleton(timeProvider); + + if (withDataProtection) + { + services.AddSingleton(new EphemeralDataProtectionProvider()); + } + + return services.BuildServiceProvider(); + } + + private sealed class StubHttpClientFactory : IHttpClientFactory + { + private readonly HttpMessageHandler _handler; + + public StubHttpClientFactory(HttpMessageHandler handler) + { + _handler = handler; + } + + public HttpClient CreateClient(string name) + { + return new HttpClient(_handler, disposeHandler: false); + } + } + + private sealed class CapturingHttpMessageHandler : HttpMessageHandler + { + private readonly HttpStatusCode _statusCode; + private readonly string _responseBody; + + public CapturingHttpMessageHandler(HttpStatusCode statusCode, string responseBody) + { + _statusCode = statusCode; + _responseBody = responseBody; + } + + public HttpRequestMessage LastRequest { get; private set; } + + public string LastRequestBody { get; private set; } + + protected override async Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + LastRequest = request; + + if (request.Content is not null) + { + LastRequestBody = await request.Content.ReadAsStringAsync(cancellationToken); + } + + return new HttpResponseMessage(_statusCode) + { + Content = new StringContent(_responseBody), + }; + } + } + + private sealed class OAuthRoutingHandler : HttpMessageHandler + { + private readonly string _tokenEndpoint; + private readonly Queue _tokenResponses; + + public OAuthRoutingHandler(string tokenEndpoint, params string[] tokenResponses) + { + _tokenEndpoint = tokenEndpoint; + _tokenResponses = new Queue(tokenResponses); + } + + public int TokenRequestCount { get; private set; } + + public List TokenRequestBodies { get; } = []; + + public List ApiRequests { get; } = []; + + protected override async Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + if (string.Equals(request.RequestUri!.ToString(), _tokenEndpoint, StringComparison.Ordinal)) + { + TokenRequestCount++; + + if (request.Content is not null) + { + TokenRequestBodies.Add(await request.Content.ReadAsStringAsync(cancellationToken)); + } + + var body = _tokenResponses.Count > 1 + ? _tokenResponses.Dequeue() + : _tokenResponses.Peek(); + + return new HttpResponseMessage(HttpStatusCode.OK) + { + Content = new StringContent(body), + }; + } + + ApiRequests.Add(request); + + return new HttpResponseMessage(HttpStatusCode.OK) + { + Content = new StringContent("{}"), + }; + } + } + + private sealed class FixedTimeProvider : TimeProvider + { + private DateTimeOffset _now; + + public FixedTimeProvider(DateTimeOffset now) + { + _now = now; + } + + public override DateTimeOffset GetUtcNow() + { + return _now; + } + } +}