Merge branch 'feature/management-api'

Author: mattbrailsford

src/Umbraco.Ai.Web.StaticAssets/wwwroot/umbraco-package.json

@@ -1,7 +1,7 @@
 {
   "id": "Umbraco.Ai",
   "name": "Umbraco Ai",
-  "version": "17.0.0--preview.27.ge460d0a",
+  "version": "17.0.0--preview.40.g75b8b19",
   "allowTelemetry": true,
   "extensions": [
     {

src/Umbraco.Ai.Web/Api/Constants.cs

@@ -1,19 +1,19 @@
-namespace Umbraco.Ai.Cms.Api.Management.Api;
+namespace Umbraco.Ai.Web.Api;
 
 /// <summary>
 /// Defines constants for the Umbraco AI Management API.
 /// </summary>
 public class Constants
 {
     /// <summary>
-    /// Defines constants for the Forms Management API.
+    /// Defines constants for the AI Management API.
     /// </summary>
     public static class ManagementApi
     {
         /// <summary>
         /// The API root path.
         /// </summary>
-        public const string RootPath = "/umbraco/ai/management/api";
+        public const string BackofficePath = "/ai/management/api";
 
         /// <summary>
         /// The API title.
@@ -30,5 +30,96 @@ public static class ManagementApi
         /// The namespace prefix for AI Management API.
         /// </summary>
         public const string ApiNamespacePrefix = "Umbraco.Ai.Web.Api.Management";
+
+        /// <summary>
+        /// The name of the API group for version 1.0.
+        /// </summary>
+        public const string GroupNameV1 = "1.0";
+        
+        /// <summary>
+        /// Defines constants for different feature areas within the Management API.
+        /// </summary>
+        public static class Feature
+        {
+            /// <summary>
+            /// Defines constants for Connection features.
+            /// </summary>
+            public static class Connection
+            {
+                /// <summary>
+                /// The route segment for Connection features.
+                /// </summary>
+                public const string RouteSegment = "connections";
+
+                /// <summary>
+                /// The Swagger group name for Connection features.
+                /// </summary>
+                public const string GroupName = "Connections";
+            }
+
+            /// <summary>
+            /// Defines constants for Profile features.
+            /// </summary>
+            public static class Profile
+            {
+                /// <summary>
+                /// The route segment for Profile features.
+                /// </summary>
+                public const string RouteSegment = "profiles";
+
+                /// <summary>
+                /// The Swagger group name for Profile features.
+                /// </summary>
+                public const string GroupName = "Profiles";
+            }
+
+            /// <summary>
+            /// Defines constants for Provider features.
+            /// </summary>
+            public static class Provider
+            {
+                /// <summary>
+                /// The route segment for Provider features.
+                /// </summary>
+                public const string RouteSegment = "providers";
+
+                /// <summary>
+                /// The Swagger group name for Provider features.
+                /// </summary>
+                public const string GroupName = "Providers";
+            }
+
+            /// <summary>
+            /// Defines constants for Embedding features.
+            /// </summary>
+            public static class Embedding
+            {
+                /// <summary>
+                /// The route segment for Embedding features.
+                /// </summary>
+                public const string RouteSegment = "embedding";
+
+                /// <summary>
+                /// The Swagger group name for Embedding features.
+                /// </summary>
+                public const string GroupName = "Embedding";
+            }
+
+            /// <summary>
+            /// Defines constants for Chat features.
+            /// </summary>
+            public static class Chat
+            {
+                /// <summary>
+                /// The route segment for Chat features.
+                /// </summary>
+                public const string RouteSegment = "chat";
+
+                /// <summary>
+                /// The Swagger group name for Chat features.
+                /// </summary>
+                public const string GroupName = "Chat";
+            }
+        }
     }
 }

src/Umbraco.Ai.Web/Api/Management/Chat/Controllers/ChatControllerBase.cs

@@ -0,0 +1,15 @@
+using Microsoft.AspNetCore.Mvc;
+using Umbraco.Ai.Web.Api;
+using Umbraco.Ai.Web.Api.Management.Common.Controllers;
+using Umbraco.Ai.Web.Api.Management.Common.Routing;
+
+namespace Umbraco.Ai.Web.Api.Management.Chat.Controllers;
+
+/// <summary>
+/// Base controller for Chat management API endpoints.
+/// </summary>
+[ApiExplorerSettings(GroupName = Constants.ManagementApi.Feature.Chat.GroupName)]
+[UmbracoAiVersionedManagementApiRoute(Constants.ManagementApi.Feature.Chat.RouteSegment)]
+public abstract class ChatControllerBase : UmbracoAiManagementControllerBase
+{
+}

src/Umbraco.Ai.Web/Api/Management/Chat/Controllers/CompleteChatController.cs

@@ -0,0 +1,78 @@
+using Asp.Versioning;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.AI;
+using Umbraco.Ai.Core.Services;
+using Umbraco.Ai.Web.Api.Management.Chat.Models;
+using Umbraco.Cms.Core.Mapping;
+using Umbraco.Cms.Web.Common.Authorization;
+
+namespace Umbraco.Ai.Web.Api.Management.Chat.Controllers;
+
+/// <summary>
+/// Controller for non-streaming chat completion.
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize(Policy = AuthorizationPolicies.SectionAccessSettings)]
+public class CompleteChatController : ChatControllerBase
+{
+    private readonly IAiChatService _chatService;
+    private readonly IUmbracoMapper _umbracoMapper;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CompleteChatController"/> class.
+    /// </summary>
+    public CompleteChatController(IAiChatService chatService, IUmbracoMapper umbracoMapper)
+    {
+        _chatService = chatService;
+        _umbracoMapper = umbracoMapper;
+    }
+
+    /// <summary>
+    /// Complete a chat conversation (non-streaming).
+    /// </summary>
+    /// <param name="requestModel">The chat request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The chat completion response.</returns>
+    [HttpPost("complete")]
+    [MapToApiVersion("1.0")]
+    [ProducesResponseType(typeof(ChatResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> Complete(
+        ChatRequestModel requestModel,
+        CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            // Convert request messages to ChatMessage list
+            var messages = _umbracoMapper.MapEnumerable<ChatMessageModel, ChatMessage>(requestModel.Messages).ToList();
+
+            // Get chat response
+            var response = requestModel.ProfileId.HasValue
+                ? await _chatService.GetResponseAsync(
+                    requestModel.ProfileId.Value,
+                    messages,
+                    cancellationToken: cancellationToken)
+                : await _chatService.GetResponseAsync(
+                    messages,
+                    cancellationToken: cancellationToken);
+
+            return Ok(_umbracoMapper.Map<ChatResponseModel>(response));
+        }
+        catch (InvalidOperationException ex) when (ex.Message.Contains("not found"))
+        {
+            return ProfileNotFound();
+        }
+        catch (InvalidOperationException ex)
+        {
+            return BadRequest(new ProblemDetails
+            {
+                Title = "Chat completion failed",
+                Detail = ex.Message,
+                Status = StatusCodes.Status400BadRequest
+            });
+        }
+    }
+}

src/Umbraco.Ai.Web/Api/Management/Chat/Controllers/StreamChatController.cs

@@ -0,0 +1,94 @@
+using System.Text.Json;
+using Asp.Versioning;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.AI;
+using Umbraco.Ai.Core.Services;
+using Umbraco.Ai.Web.Api.Management.Chat.Models;
+using Umbraco.Cms.Core.Mapping;
+using Umbraco.Cms.Web.Common.Authorization;
+
+namespace Umbraco.Ai.Web.Api.Management.Chat.Controllers;
+
+/// <summary>
+/// Controller for streaming chat completion using Server-Sent Events (SSE).
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize(Policy = AuthorizationPolicies.SectionAccessSettings)]
+public class StreamChatController : ChatControllerBase
+{
+    private readonly IAiChatService _chatService;
+    private readonly IUmbracoMapper _umbracoMapper;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="StreamChatController"/> class.
+    /// </summary>
+    public StreamChatController(IAiChatService chatService, IUmbracoMapper umbracoMapper)
+    {
+        _chatService = chatService;
+        _umbracoMapper = umbracoMapper;
+    }
+
+    /// <summary>
+    /// Complete a chat conversation with streaming response (SSE).
+    /// </summary>
+    /// <param name="requestModel">The chat request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A stream of chat completion chunks.</returns>
+    [HttpPost("stream")]
+    [MapToApiVersion("1.0")]
+    [Produces("text/event-stream")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task Stream(
+        ChatRequestModel requestModel,
+        CancellationToken cancellationToken = default)
+    {
+        Response.ContentType = "text/event-stream";
+        Response.Headers.CacheControl = "no-cache";
+        Response.Headers.Connection = "keep-alive";
+
+        try
+        {
+            // Convert request messages to ChatMessage list
+            var messages = _umbracoMapper.MapEnumerable<ChatMessageModel, ChatMessage>(requestModel.Messages).ToList();
+
+            // Get streaming chat response
+            var stream = requestModel.ProfileId.HasValue
+                ? _chatService.GetStreamingResponseAsync(
+                    requestModel.ProfileId.Value,
+                    messages,
+                    cancellationToken: cancellationToken)
+                : _chatService.GetStreamingResponseAsync(
+                    messages,
+                    cancellationToken: cancellationToken);
+
+            await foreach (var update in stream.WithCancellation(cancellationToken))
+            {
+                var chunk = _umbracoMapper.Map<ChatStreamChunkModel>(update);
+
+                var json = JsonSerializer.Serialize(chunk);
+                await Response.WriteAsync($"data: {json}\n\n", cancellationToken);
+                await Response.Body.FlushAsync(cancellationToken);
+            }
+
+            // Send final event
+            await Response.WriteAsync("data: [DONE]\n\n", cancellationToken);
+            await Response.Body.FlushAsync(cancellationToken);
+        }
+        catch (InvalidOperationException ex) when (ex.Message.Contains("not found"))
+        {
+            Response.StatusCode = StatusCodes.Status404NotFound;
+            var error = JsonSerializer.Serialize(new { error = "Profile not found", detail = ex.Message });
+            await Response.WriteAsync($"data: {error}\n\n", cancellationToken);
+        }
+        catch (Exception ex)
+        {
+            Response.StatusCode = StatusCodes.Status400BadRequest;
+            var error = JsonSerializer.Serialize(new { error = "Chat streaming failed", detail = ex.Message });
+            await Response.WriteAsync($"data: {error}\n\n", cancellationToken);
+        }
+    }
+}

src/Umbraco.Ai.Web/Api/Management/Chat/Mapping/ChatMapDefinition.cs

@@ -0,0 +1,62 @@
+using Microsoft.Extensions.AI;
+using Umbraco.Ai.Web.Api.Management.Chat.Models;
+using Umbraco.Cms.Core.Mapping;
+
+namespace Umbraco.Ai.Web.Api.Management.Chat.Mapping;
+
+/// <summary>
+/// Map definitions for Chat models.
+/// </summary>
+public class ChatMapDefinition : IMapDefinition
+{
+    /// <inheritdoc />
+    public void DefineMaps(IUmbracoMapper mapper)
+    {
+        mapper.Define<ChatMessageModel, ChatMessage>(Map);
+        mapper.Define<ChatResponse, ChatResponseModel>((_, _) => new ChatResponseModel(), Map);
+        mapper.Define<ChatResponseUpdate, ChatStreamChunkModel>((_, _) => new ChatStreamChunkModel(), Map);
+        mapper.Define<UsageDetails, ChatUsageModel>((_, _) => new ChatUsageModel(), Map);
+    }
+
+    // Umbraco.Code.MapAll
+    private static ChatMessage Map(ChatMessageModel source, MapperContext context)
+    {
+        var role = source.Role.ToLowerInvariant() switch
+        {
+            "system" => ChatRole.System,
+            "user" => ChatRole.User,
+            "assistant" => ChatRole.Assistant,
+            _ => ChatRole.User
+        };
+
+        return new ChatMessage(role, source.Content);
+    }
+
+    // Umbraco.Code.MapAll
+    private static void Map(ChatResponse source, ChatResponseModel target, MapperContext context)
+    {
+        target.Message = new ChatMessageModel
+        {
+            Role = "assistant",
+            Content = source.Text ?? string.Empty
+        };
+        target.FinishReason = source.FinishReason?.ToString();
+        target.Usage = source.Usage is not null ? context.Map<ChatUsageModel>(source.Usage) : null;
+    }
+
+    // Umbraco.Code.MapAll
+    private static void Map(ChatResponseUpdate source, ChatStreamChunkModel target, MapperContext context)
+    {
+        target.Content = source.Text;
+        target.FinishReason = source.FinishReason?.ToString();
+        target.IsComplete = source.FinishReason is not null;
+    }
+
+    // Umbraco.Code.MapAll
+    private static void Map(UsageDetails source, ChatUsageModel target, MapperContext context)
+    {
+        target.InputTokens = source.InputTokenCount;
+        target.OutputTokens = source.OutputTokenCount;
+        target.TotalTokens = source.TotalTokenCount;
+    }
+}