Add basic specification (#1)

Author: SommerEngineering

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);