Add basic specification (#1)

DemoServer/DataModel/AuthFieldMapping.cs

@@ -0,0 +1,10 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// The mapping between an AuthField and the field name in the authentication request.
+/// </summary>
+/// <param name="AuthField">The AuthField that is mapped to the field name.</param>
+/// <param name="FieldName">The field name in the authentication request.</param>
+public record AuthFieldMapping(
+    AuthField AuthField,
+    string FieldName);

DemoServer/DataModel/AuthResponse.cs

@@ -0,0 +1,12 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// The response to an authentication request.
+/// </summary>
+/// <param name="Success">True, when the authentication was successful.</param>
+/// <param name="Token">The token to use for further requests.</param>
+/// <param name="Message">When the authentication was not successful, this contains the reason.</param>
+public readonly record struct AuthResponse(
+    bool Success,
+    string? Token,
+    string? Message);

DemoServer/DataModel/AuthScheme.cs

@@ -0,0 +1,11 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// Describes one authentication scheme for this data source. 
+/// </summary>
+/// <param name="AuthMethod">The method used for authentication, e.g., "API Key," "Username/Password," etc.</param>
+/// <param name="AuthFieldMappings">A list of field mappings for the authentication method. The client must know,
+/// e.g., how the password field is named in the request.</param> 
+public readonly record struct AuthScheme(
+    AuthMethod AuthMethod,
+    List<AuthFieldMapping> AuthFieldMappings);

DemoServer/DataModel/ChatThread.cs

@@ -0,0 +1,7 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// A chat thread, which is a list of content blocks.
+/// </summary>
+/// <param name="ContentBlocks">The content blocks in this chat thread.</param>
+public readonly record struct ChatThread(List<ContentBlock> ContentBlocks);

DemoServer/DataModel/ContentBlock.cs

@@ -0,0 +1,15 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// A block of content of a chat thread.
+/// </summary>
+/// <remarks>
+/// Images and other media are base64 encoded.
+/// </remarks>
+/// <param name="Content">The content of the block. Remember that images and other media are base64 encoded.</param>
+/// <param name="Role">The role of the content in the chat thread.</param>
+/// <param name="Type">The type of the content, e.g., text, image, video, etc.</param>
+public readonly record struct ContentBlock(
+    string Content,
+    Role Role,
+    ContentType Type);

DemoServer/DataModel/Context.cs

@@ -0,0 +1,27 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// Matching context returned by the data source as a result of a retrieval request.
+/// </summary>
+/// <param name="Name">The name of the source, e.g., a document name, database name,
+/// collection name, etc.</param>
+/// <param name="Category">What are the contents of the source? For example, is it a
+/// dictionary, a book chapter, business concept, a paper, etc.</param>
+/// <param name="Path">The path to the content, e.g., a URL, a file path, a path in a
+/// graph database, etc.</param>
+/// <param name="Type">The type of the content, e.g., text, image, video, audio, speech, etc.</param>
+/// <param name="MatchedContent">The content that matched the user prompt. For text, you
+/// return the matched text and, e.g., three words before and after it.</param>
+/// <param name="SurroundingContent">The surrounding content of the matched content.
+/// For text, you may return, e.g., one sentence or paragraph before and after
+/// the matched content.</param>
+/// <param name="Links">Links to related content, e.g., links to Wikipedia articles,
+/// links to sources, etc.</param>
+public readonly record struct Context(
+    string Name,
+    string Category,
+    string? Path,
+    ContentType Type,
+    string MatchedContent,
+    string[] SurroundingContent,
+    string[] Links);

DemoServer/DataModel/DataSourceInfo.cs

@@ -0,0 +1,11 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// Information about the data source.
+/// </summary>
+/// <param name="Name">The name of the data source, e.g., "Internal Organization Documents."</param>
+/// <param name="Description">A short description of the data source. What kind of data does it contain?
+/// What is the data source used for?</param>
+public readonly record struct DataSourceInfo(
+    string Name,
+    string Description);

DemoServer/DataModel/EmbeddingInfo.cs

@@ -0,0 +1,20 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// Represents information about the used embedding for this data source. The purpose of this information is to give the
+/// interested user an idea of what kind of embedding is used and what it does.
+/// </summary>
+/// <param name="EmbeddingType">What kind of embedding is used. For example, "Transformer Embedding," "Contextual Word
+/// Embedding," "Graph Embedding," etc.</param>
+/// <param name="EmbeddingName">Name the embedding used. This can be a library, a framework, or the name of the used
+/// algorithm.</param>
+/// <param name="Description">A short description of the embedding. Describe what the embedding is doing.</param>
+/// <param name="UsedWhen">Describe when the embedding is used. For example, when the user prompt contains certain
+/// keywords, or anytime?</param>
+/// <param name="Link">A link to the embedding's documentation or the source code. Might be null.</param>
+public readonly record struct EmbeddingInfo(
+    string EmbeddingType,
+    string EmbeddingName,
+    string Description,
+    string UsedWhen,
+    string? Link);

DemoServer/DataModel/RetrievalInfo.cs

@@ -0,0 +1,20 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// Information about a retrieval process, which this data source implements.
+/// </summary>
+/// <param name="Id">A unique identifier for the retrieval process. This can be a GUID, a unique name, or an increasing integer.</param>
+/// <param name="Name">The name of the retrieval process, e.g., "Keyword-Based Wikipedia Article Retrieval".</param>
+/// <param name="Description">A short description of the retrieval process. What kind of retrieval process is it?</param>
+/// <param name="Link">A link to the retrieval process's documentation, paper, Wikipedia article, or the source code. Might be null.</param>
+/// <param name="ParametersDescription">A dictionary that describes the parameters of the retrieval process. The key is the parameter name,
+/// and the value is a description of the parameter. Although each parameter will be sent as a string, the description should indicate the
+/// expected type and range, e.g., 0.0 to 1.0 for a float parameter.</param>
+/// <param name="Embeddings">A list of embeddings used in this retrieval process. It might be empty in case no embedding is used.</param>
+public readonly record struct RetrievalInfo(
+    string Id,
+    string Name,
+    string Description,
+    string? Link,
+    Dictionary<string, string>? ParametersDescription,
+    List<EmbeddingInfo> Embeddings);

DemoServer/DataModel/RetrievalRequest.cs

@@ -0,0 +1,25 @@
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// The retrieval request sent by AI Studio.
+/// </summary>
+/// <remarks>
+/// Images and other media are base64 encoded.
+/// </remarks>
+/// <param name="LatestUserPrompt">The latest user prompt that AI Studio received.</param>
+/// <param name="LatestUserPromptType">The type of the latest user prompt, e.g., text, image, etc.</param>
+/// <param name="Thread">The chat thread that the user is currently in.</param>
+/// <param name="RetrievalProcessId">Optional. The ID of the retrieval process that the data source should use.
+/// When null, the data source chooses an appropriate retrieval process. Selecting a retrieval process is optional
+/// for AI Studio users. Most users do not specify a retrieval process.</param>
+/// <param name="Parameters">A dictionary of parameters that the data source should use for the retrieval process.
+/// Although each parameter will be sent as a string, the retrieval process specifies the expected type and range.</param>
+/// <param name="MaxMatches">The maximum number of matches that the data source should return. AI Studio uses
+/// any value below 1 to indicate that the data source should return as many matches as appropriate.</param>
+public readonly record struct RetrievalRequest(
+    string LatestUserPrompt,
+    ContentType LatestUserPromptType,
+    ChatThread Thread,
+    string? RetrievalProcessId,
+    Dictionary<string, string>? Parameters,
+    int MaxMatches);

DemoServer/DataModel/SecurityRequirements.cs

@@ -0,0 +1,9 @@
+// ReSharper disable NotAccessedPositionalProperty.Global
+
+namespace DemoServer.DataModel;
+
+/// <summary>
+/// Represents the security requirements for this data source.
+/// </summary>
+/// <param name="AllowedProviderType">Which provider types are allowed to process the data?</param>
+public readonly record struct SecurityRequirements(ProviderType AllowedProviderType);

DemoServer/DemoServer.csproj

@@ -4,12 +4,13 @@
         <TargetFramework>net9.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
-        <NoDefaultLaunchSettingsFile>True</NoDefaultLaunchSettingsFile>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>CS1591</NoWarn>
     </PropertyGroup>
 
     <ItemGroup>
         <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0-rc.2.24474.3"/>
-        <PackageReference Include="Scalar.AspNetCore" Version="1.2.16" />
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="6.9.0" />
     </ItemGroup>
 
 </Project>

DemoServer/EnumSchemaFilter.cs

@@ -0,0 +1,25 @@
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace DemoServer;
+
+public sealed class EnumSchemaFilter : ISchemaFilter
+{
+    public void Apply(OpenApiSchema model, SchemaFilterContext context)
+    {
+        if (context.Type.IsEnum)
+        {
+            model.Enum.Clear();
+            Enum.GetNames(context.Type)
+                .ToList()
+                .ForEach(n =>
+                {
+                    model.Enum.Add(new OpenApiString(n)); 
+                    model.Type = "string";
+                    model.Format = null;
+                });
+        }
+    }
+}

DemoServer/Enums/AuthField.cs

@@ -0,0 +1,13 @@
+namespace DemoServer.Enums;
+
+/// <summary>
+/// An authentication field.
+/// </summary>
+public enum AuthField
+{
+    NONE,
+    USERNAME,
+    PASSWORD,
+    TOKEN,
+    KERBEROS_TICKET,
+}

DemoServer/Enums/AuthMethod.cs

@@ -0,0 +1,9 @@
+namespace DemoServer.Enums;
+
+public enum AuthMethod
+{
+    NONE,
+    KERBEROS,
+    USERNAME_PASSWORD,
+    TOKEN,
+}

DemoServer/Enums/ContentType.cs

@@ -0,0 +1,16 @@
+namespace DemoServer.Enums;
+
+/// <summary>
+/// The type of content.
+/// </summary>
+public enum ContentType
+{
+    NONE,
+    UNKNOWN,
+
+    TEXT,
+    IMAGE,
+    VIDEO,
+    AUDIO,
+    SPEECH,
+}

DemoServer/Enums/ProviderType.cs

@@ -0,0 +1,22 @@
+namespace DemoServer.Enums;
+
+/// <summary>
+/// Known types of providers that can process data.
+/// </summary>
+public enum ProviderType
+{
+    /// <summary>
+    /// The related data is not allowed to be sent to any provider.
+    /// </summary>
+    NONE,
+
+    /// <summary>
+    /// The related data can be sent to any provider.
+    /// </summary>
+    ANY,
+
+    /// <summary>
+    /// The related data can be sent to a provider that is hosted by the same organization, either on-premises or locally.
+    /// </summary>
+    SELF_HOSTED,
+}

DemoServer/Enums/Role.cs

@@ -0,0 +1,15 @@
+namespace DemoServer.Enums;
+
+/// <summary>
+/// Possible roles of any chat thread.
+/// </summary>
+public enum Role
+{
+    NONE,
+    UNKNOW,
+
+    SYSTEM,
+    USER,
+    AI,
+    AGENT,
+}

DemoServer/ExampleData.cs

@@ -0,0 +1,16 @@
+namespace DemoServer;
+
+/// <summary>
+/// This is a simple demonstration for a data source. In fact, you would want to
+/// connect a graph database or a document database or a server's file system instead:
+/// </summary>
+public static class ExampleData
+{
+    public static readonly WikipediaArticle[] EXAMPLE_DATA = {
+        new("Strategic foresight", "https://en.wikipedia.org/wiki/Strategic_foresight"),
+        new("Scenario planning", "https://en.wikipedia.org/wiki/Scenario_planning"),
+        new("Futures studies", "https://en.wikipedia.org/wiki/Futures_studies"),
+        new("Futures techniques", "https://en.wikipedia.org/wiki/Futures_techniques"),
+        new("Delphi method", "https://en.wikipedia.org/wiki/Delphi_method"),       
+    };
+}

DemoServer/GlobalUsings.cs

@@ -0,0 +1,4 @@
+// Global using directives
+
+global using DemoServer;
+global using DemoServer.Enums;