Ad comments

Author: marcel2215

ChatAIze.GenerativeCS/Clients/GeminiClient.cs

@@ -23,6 +23,7 @@ public class GeminiClient<TChat, TMessage, TFunctionCall, TFunctionResult>
 {
     private readonly HttpClient _httpClient = new()
     {
+        // Long timeout to accommodate streaming and large uploads.
         Timeout = TimeSpan.FromMinutes(15)
     };
 
@@ -31,6 +32,7 @@ public class GeminiClient<TChat, TMessage, TFunctionCall, TFunctionResult>
     /// </summary>
     public GeminiClient()
     {
+        // Allow environment variables to supply credentials when no explicit API key is provided.
         if (string.IsNullOrWhiteSpace(ApiKey))
         {
             ApiKey = EnvironmentVariableManager.GetGeminiAPIKey();

ChatAIze.GenerativeCS/Clients/OpenAIClient.cs

@@ -24,6 +24,7 @@ public class OpenAIClient<TChat, TMessage, TFunctionCall, TFunctionResult>
 {
     private readonly HttpClient _httpClient = new()
     {
+        // Long timeout to accommodate streaming and large uploads.
         Timeout = TimeSpan.FromMinutes(15)
     };
 
@@ -32,6 +33,7 @@ public class OpenAIClient<TChat, TMessage, TFunctionCall, TFunctionResult>
     /// </summary>
     public OpenAIClient()
     {
+        // Allow environment variables to supply credentials when no explicit API key is provided.
         if (string.IsNullOrWhiteSpace(ApiKey))
         {
             ApiKey = EnvironmentVariableManager.GetOpenAIAPIKey();

ChatAIze.GenerativeCS/Constants/DefaultModels.cs

@@ -13,16 +13,19 @@ public static class OpenAI
         /// <summary>
         /// Default chat completion model.
         /// </summary>
+        /// <remarks>Used when callers omit a model identifier to favor a generally capable, up-to-date model.</remarks>
         public const string ChatCompletion = ChatCompletionModels.OpenAI.GPT51;
 
         /// <summary>
         /// Default embedding model.
         /// </summary>
+        /// <remarks>Balances cost and quality for general-purpose embeddings.</remarks>
         public const string Embedding = EmbeddingModels.OpenAI.TextEmbedding3Small;
 
         /// <summary>
         /// Default text-to-speech model.
         /// </summary>
+        /// <remarks>Chosen for latency and voice quality in typical scenarios.</remarks>
         public const string TextToSpeech = TextToSpeechModels.OpenAI.GPT4oMiniTTS;
 
         /// <summary>

ChatAIze.GenerativeCS/Models/Chat.cs

@@ -77,6 +77,7 @@ public ValueTask<TMessage> FromSystemAsync(string message, PinLocation pinLocati
     /// <param name="pinLocation">Optional pin location for message ordering.</param>
     public async void FromSystem(string message, PinLocation pinLocation = PinLocation.None)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromSystemAsync(message, pinLocation);
     }
 
@@ -109,6 +110,7 @@ public ValueTask<TMessage> FromUserAsync(string message, PinLocation pinLocation
     /// <param name="imageUrls">Optional set of image URLs attached to the message.</param>
     public async void FromUser(string message, PinLocation pinLocation = PinLocation.None, params ICollection<string> imageUrls)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromUserAsync(message, pinLocation, imageUrls);
     }
 
@@ -144,6 +146,7 @@ public ValueTask<TMessage> FromUserAsync(string userName, string message, PinLoc
     /// <param name="imageUrls">Optional set of image URLs attached to the message.</param>
     public async void FromUser(string userName, string message, PinLocation pinLocation = PinLocation.None, params ICollection<string> imageUrls)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromUserAsync(userName, message, pinLocation, imageUrls);
     }
 
@@ -173,6 +176,7 @@ public ValueTask<TMessage> FromChatbotAsync(string message, PinLocation pinLocat
     /// <param name="pinLocation">Optional pin location for message ordering.</param>
     public async void FromChatbot(string message, PinLocation pinLocation = PinLocation.None)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromChatbotAsync(message, pinLocation);
     }
 
@@ -202,6 +206,7 @@ public ValueTask<TMessage> FromChatbotAsync(TFunctionCall functionCall, PinLocat
     /// <param name="pinLocation">Optional pin location for message ordering.</param>
     public async void FromChatbot(TFunctionCall functionCall, PinLocation pinLocation = PinLocation.None)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromChatbotAsync(functionCall, pinLocation);
     }
 
@@ -231,6 +236,7 @@ public ValueTask<TMessage> FromChatbotAsync(IEnumerable<TFunctionCall> functionC
     /// <param name="pinLocation">Optional pin location for message ordering.</param>
     public async void FromChatbot(IEnumerable<TFunctionCall> functionCalls, PinLocation pinLocation = PinLocation.None)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromChatbotAsync(functionCalls, pinLocation);
     }
 
@@ -260,6 +266,7 @@ public ValueTask<TMessage> FromFunctionAsync(TFunctionResult functionResult, Pin
     /// <param name="pinLocation">Optional pin location for message ordering.</param>
     public async void FromFunction(TFunctionResult functionResult, PinLocation pinLocation = PinLocation.None)
     {
+        // Intentional fire-and-forget wrapper to keep API ergonomic for callers that don't await.
         _ = await FromFunctionAsync(functionResult, pinLocation);
     }
 }

ChatAIze.GenerativeCS/Models/FunctionCall.cs

@@ -42,6 +42,7 @@ public FunctionCall(string toolCallId, string name, string arguments)
     /// <summary>
     /// Gets or sets the provider-issued tool call identifier.
     /// </summary>
+    /// <remarks>When present, this ties a function call to its matching tool result in later messages.</remarks>
     public string? ToolCallId { get; set; }
 
     /// <summary>

ChatAIze.GenerativeCS/Models/FunctionResult.cs

@@ -42,6 +42,7 @@ public FunctionResult(string toolCallId, string name, string value)
     /// <summary>
     /// Gets or sets the provider-issued tool call identifier used to correlate the result with a prior tool call.
     /// </summary>
+    /// <remarks>Providers like OpenAI expect this to mirror the tool call id emitted in the original function call.</remarks>
     public string? ToolCallId { get; set; }
 
     /// <summary>

ChatAIze.GenerativeCS/Options/Gemini/ChatCompletionOptions.cs

@@ -69,6 +69,7 @@ public ChatCompletionOptions(string model = DefaultModels.Gemini.ChatCompletion,
     /// <summary>
     /// Gets or sets a callback used to dynamically supply a system message.
     /// </summary>
+    /// <remarks>Applied at request time so callers can inject context-sensitive instructions.</remarks>
     public Func<string?>? SystemMessageCallback { get; set; } = null;
 
     /// <summary>
@@ -79,11 +80,13 @@ public ChatCompletionOptions(string model = DefaultModels.Gemini.ChatCompletion,
     /// <summary>
     /// Gets a callback invoked whenever a message is added to the chat.
     /// </summary>
+    /// <remarks>Useful for logging or persisting transcripts as tool calls and model replies are appended.</remarks>
     public Func<TMessage, ValueTask> AddMessageCallback { get; } = (_) => ValueTask.CompletedTask;
 
     /// <summary>
     /// Gets or sets the fallback function callback used when a function does not have an explicit delegate.
     /// </summary>
+    /// <remarks>Defaults to throwing to make the absence of a callback explicit.</remarks>
     public Func<string, string, CancellationToken, ValueTask<object?>> DefaultFunctionCallback { get; set; } = (_, _, _) => throw new NotImplementedException("Function callback has not been implemented.");
 
     /// <summary>

ChatAIze.GenerativeCS/Options/OpenAI/ChatCompletionOptions.cs

@@ -130,6 +130,7 @@ public ChatCompletionOptions(string model = DefaultModels.OpenAI.ChatCompletion,
     /// <summary>
     /// Gets or sets a value indicating whether function call and result messages before the latest user message should be removed.
     /// </summary>
+    /// <remarks>Use when continuing an existing chat but wanting the model to ignore earlier tool interactions and only consider the latest user turn.</remarks>
     public bool IsIgnoringPreviousFunctionCalls { get; set; }
 
     /// <summary>
@@ -160,11 +161,13 @@ public ChatCompletionOptions(string model = DefaultModels.OpenAI.ChatCompletion,
     /// <summary>
     /// Gets or sets a callback invoked whenever a message is added to the chat during request processing.
     /// </summary>
+    /// <remarks>Useful for logging or persisting transcripts as tool calls and model replies are appended.</remarks>
     public Func<TMessage, Task> AddMessageCallback { get; set; } = (_) => Task.CompletedTask;
 
     /// <summary>
     /// Gets or sets the fallback function callback used when a function does not have an explicit delegate; should return a string or serializable object.
     /// </summary>
+    /// <remarks>Defaults to throwing to make the absence of a callback explicit.</remarks>
     public Func<string, string, CancellationToken, ValueTask<object?>> DefaultFunctionCallback { get; set; } = (_, _, _) => throw new NotImplementedException("Function callback has not been implemented.");
 
     /// <summary>

ChatAIze.GenerativeCS/Options/OpenAI/EmbeddingOptions.cs

@@ -31,6 +31,7 @@ public EmbeddingOptions(string model = DefaultModels.OpenAI.Embedding, string? a
     /// <summary>
     /// Gets or sets optional output dimensions.
     /// </summary>
+    /// <remarks>Only supported by specific models; unsupported combinations will be rejected by the provider.</remarks>
     public int? Dimensions { get; set; }
 
     /// <summary>

ChatAIze.GenerativeCS/Options/OpenAI/ModerationOptions.cs

@@ -31,5 +31,6 @@ public ModerationOptions(string model = DefaultModels.OpenAI.Moderation, string?
     /// <summary>
     /// Gets or sets the maximum number of attempts (including the first call) before a moderation request is treated as failed.
     /// </summary>
+    /// <remarks>Used by the retry helper; does not retry on client-side validation errors.</remarks>
     public int MaxAttempts { get; set; } = 5;
 }