Added an information view to all data sources (#273)

2026-10-13 06:33:48 +00:00 · 2025-02-09 12:36:37 +01:00
1 parent 9d71978feb
commit c836bd7f33
@@ -0,0 +1,13 @@
+namespace AIStudio.Tools.ERIClient.DataModel;
+
+/// <summary>
+/// An authentication field.
+/// </summary>
+public enum AuthField
+{
+    NONE,
+    USERNAME,
+    PASSWORD,
+    TOKEN,
+    KERBEROS_TICKET,
+}
@@ -0,0 +1,8 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,9 @@
+namespace AIStudio.Tools.ERIClient.DataModel;
+
+public enum AuthMethod
+{
+    NONE,
+    KERBEROS,
+    USERNAME_PASSWORD,
+    TOKEN,
+}
@@ -0,0 +1,9 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,9 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,7 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,12 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,16 @@
+namespace AIStudio.Tools.ERIClient.DataModel;
+
+/// <summary>
+/// The type of content.
+/// </summary>
+public enum ContentType
+{
+    NONE,
+    UNKNOWN,
+    
+    TEXT,
+    IMAGE,
+    VIDEO,
+    AUDIO,
+    SPEECH,
+}
@@ -0,0 +1,27 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,9 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,20 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,22 @@
+namespace AIStudio.Tools.ERIClient.DataModel;
+
+/// <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,
+}
@@ -0,0 +1,13 @@
+namespace AIStudio.Tools.ERIClient.DataModel;
+
+public static class ProviderTypeExtensions
+{
+    public static string Explain(this ProviderType providerType) => providerType switch
+    {
+        ProviderType.NONE => "The related data is not allowed to be sent to any LLM provider. This means that this data source cannot be used at the moment.",
+        ProviderType.ANY => "The related data can be sent to any provider, regardless of where it is hosted (cloud or self-hosted).",
+        ProviderType.SELF_HOSTED => "The related data can be sent to a provider that is hosted by the same organization, either on-premises or locally. Cloud-based providers are not allowed.",
+        
+        _ => "Unknown configuration. This data source cannot be used at the moment.",
+    };
+}
@@ -0,0 +1,20 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,25 @@
+namespace AIStudio.Tools.ERIClient.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);
@@ -0,0 +1,15 @@
+namespace AIStudio.Tools.ERIClient.DataModel;
+
+/// <summary>
+/// Possible roles of any chat thread.
+/// </summary>
+public enum Role
+{
+    NONE,
+    UNKNOW,
+    
+    SYSTEM,
+    USER,
+    AI,
+    AGENT,
+}
@@ -0,0 +1,7 @@
+namespace AIStudio.Tools.ERIClient.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);