CopilotChat: Options pattern and best practices

samples/apps/copilot-chat-app/README.md

@@ -132,4 +132,4 @@ the complete list of current models supporting chat completions.
 
 ## Additional resources
 
-1. [Import Document Application](./importdocument/README.md): Ingest a document to memory.
+1. [Import Document Application](./importdocument/README.md): Import a document to the memory store.

samples/apps/copilot-chat-app/webapi/Config/AIServiceOptions.cs

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel.DataAnnotations;
+
+namespace SemanticKernel.Service.Config;
+
+/// <summary>
+/// Configuration options for AI services, such as Azure OpenAI and OpenAI.
+/// </summary>
+public sealed class AIServiceOptions
+{
+    public const string CompletionPropertyName = "Completion";
+    public const string EmbeddingPropertyName = "Embedding";
+
+    public enum AIServiceType
+    {
+        AzureOpenAI,
+        OpenAI
+    }
+
+    /// <summary>
+    /// Label used for referencing the AI service in Semantic Kernel.
+    /// </summary>
+    [Required, NotEmptyOrWhitespace]
+    public string Label { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Type of AI service.
+    /// </summary>
+    [Required]
+    public AIServiceType AIService { get; set; } = AIServiceType.AzureOpenAI;
+
+    /// <summary>
+    /// Azure OpenAI deployment name or OpenAI model name.
+    /// </summary>
+    [Required, NotEmptyOrWhitespace]
+    public string DeploymentOrModelId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// (Azure OpenAI only) Azure OpenAI endpoint.
+    /// </summary>
+    [RequiredOnPropertyValue(nameof(AIService), AIServiceType.AzureOpenAI)]
+    [NotEmptyOrWhitespace]
+    public string Endpoint { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Key to access the AI service.
+    /// </summary>
+    [Required, NotEmptyOrWhitespace]
+    public string Key { get; set; } = string.Empty;
+
+    // TODO support OpenAI's orgID
+}

samples/apps/copilot-chat-app/webapi/Config/AuthorizationOptions.cs

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel.DataAnnotations;
+using Microsoft.Identity.Web;
+
+namespace SemanticKernel.Service.Config;
+
+/// <summary>
+/// Configuration options for authorizing to the service.
+/// </summary>
+public class AuthorizationOptions
+{
+    public const string PropertyName = "Authorization";
+
+    public enum AuthorizationType
+    {
+        None,
+        ApiKey,
+        AzureAd
+    }
+
+    /// <summary>
+    /// Type of authorization.
+    /// </summary>
+    public AuthorizationType Type { get; set; } = AuthorizationType.None;
+
+    /// <summary>
+    /// When <see cref="Type"/> is <see cref="AuthorizationType.ApiKey"/>, this is the API key to use.
+    /// </summary>
+    [Required, NotEmptyOrWhitespace]
+    public string ApiKey { get; set; } = string.Empty;
+
+    /// <summary>
+    /// When <see cref="Type"/> is <see cref="AuthorizationType.AzureAd"/>, these are the Azure AD options to use.
+    /// </summary>
+    [RequiredOnPropertyValue(nameof(Type), AuthorizationType.AzureAd)]
+    public AzureAdOptions? AzureAd { get; set; }
+
+    /// <summary>
+    /// Configuration options for Azure Active Directory (AAD) authorization.
+    /// </summary>
+    public class AzureAdOptions
+    {
+        /// <summary>
+        /// AAD instance url, i.e., https://login.microsoftonline.com/
+        /// </summary>
+        [Required, NotEmptyOrWhitespace]
+        public string Instance { get; set; } = string.Empty;
+
+        /// <summary>
+        /// Tenant (directory) ID
+        /// </summary>
+        [Required, NotEmptyOrWhitespace]
+        public string TenantId { get; set; } = string.Empty;
+
+        /// <summary>
+        /// Application (client) ID
+        /// </summary>
+        [Required, NotEmptyOrWhitespace]
+        public string ClientId { get; set; } = string.Empty;
+
+        /// <summary>
+        /// Required scopes.
+        /// </summary>
+        [Required]
+        public string? Scopes { get; set; } = string.Empty;
+    }
+}

samples/apps/copilot-chat-app/webapi/Config/AzureSpeechOptions.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel.DataAnnotations;
+
+namespace SemanticKernel.Service.Config;
+
+/// <summary>
+/// Configuration options for Azure speech recognition.
+/// </summary>
+public sealed class AzureSpeechOptions
+{
+    public const string PropertyName = "AzureSpeech";
+
+    /// <summary>
+    /// Location of the Azure speech service to use (e.g. "South Central US")
+    /// </summary>
+    [Required, NotEmptyOrWhitespace]
+    public string? Region { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Key to access the Azure speech service.
+    /// </summary>
+    [Required, NotEmptyOrWhitespace]
+    public string Key { get; set; } = string.Empty;
+}

samples/apps/copilot-chat-app/webapi/Config/BotSchemaConfig.cs → samples/apps/copilot-chat-app/webapi/Config/BotSchemaOptions.cs

@@ -1,19 +1,25 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.ComponentModel.DataAnnotations;
+
 namespace SemanticKernel.Service.Config;
 
 /// <summary>
-/// Configuration settings for the bot file schema that is supported by this application.
+/// Configuration options for the bot file schema that is supported by this application.
 /// </summary>
-public class BotSchemaConfig
+public class BotSchemaOptions
 {
+    public const string PropertyName = "BotSchema";
+
     /// <summary>
     /// The name of the schema.
     /// </summary>
+    [Required, NotEmptyOrWhitespace]
     public string Name { get; set; } = string.Empty;
 
     /// <summary>
     /// The version of the schema.
     /// </summary>
-    public int Version { get; set; } = -1;
+    [Range(0, int.MaxValue)]
+    public int Version { get; set; }
 }

samples/apps/copilot-chat-app/webapi/Config/ChatStoreConfig.cs → samples/apps/copilot-chat-app/webapi/Config/ChatStoreOptions.cs

@@ -1,12 +1,16 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using static SemanticKernel.Service.Config.AuthorizationOptions;
+
 namespace SemanticKernel.Service.Config;
 
 /// <summary>
 /// Configuration settings for the chat store.
 /// </summary>
-public class ChatStoreConfig
+public class ChatStoreOptions
 {
+    public const string PropertyName = "ChatStore";
+
     /// <summary>
     /// The type of chat store to use.
     /// </summary>
@@ -36,10 +40,12 @@ public enum ChatStoreType
     /// <summary>
     /// Gets or sets the configuration for the file system chat store.
     /// </summary>
-    public FileSystemConfig? Filesystem { get; set; }
+    [RequiredOnPropertyValue(nameof(Type), ChatStoreType.Filesystem)]
+    public FileSystemOptions? Filesystem { get; set; }
 
     /// <summary>
     /// Gets or sets the configuration for the Azure CosmosDB chat store.
     /// </summary>
-    public CosmosConfig? Cosmos { get; set; }
+    [RequiredOnPropertyValue(nameof(Type), ChatStoreType.Cosmos)]
+    public CosmosOptions? Cosmos { get; set; }
 }