Skip to content

Commit 780de97

Browse files
committed
Make xml docs more clear
1 parent 3321542 commit 780de97

File tree

6 files changed

+90
-87
lines changed

6 files changed

+90
-87
lines changed

ChatAIze.GenerativeCS/Models/FunctionResult.cs

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
namespace ChatAIze.GenerativeCS.Models;
55

66
/// <summary>
7-
/// Represents the result returned after executing a function call.
7+
/// Represents the serialized value returned to the model after executing a function call.
88
/// </summary>
99
public record FunctionResult : IFunctionResult
1010
{
@@ -16,8 +16,8 @@ public FunctionResult() { }
1616
/// <summary>
1717
/// Initializes a function result with a name and value.
1818
/// </summary>
19-
/// <param name="name">Function name.</param>
20-
/// <param name="value">Serialized result value.</param>
19+
/// <param name="name">Function name the model requested.</param>
20+
/// <param name="value">Serialized result value (typically JSON or plain text the model can read).</param>
2121
[SetsRequiredMembers]
2222
public FunctionResult(string name, string value)
2323
{
@@ -28,9 +28,9 @@ public FunctionResult(string name, string value)
2828
/// <summary>
2929
/// Initializes a function result with a tool call identifier.
3030
/// </summary>
31-
/// <param name="toolCallId">Provider-specific tool call identifier.</param>
31+
/// <param name="toolCallId">Provider-specific tool call identifier that pairs the result with the originating tool call.</param>
3232
/// <param name="name">Function name.</param>
33-
/// <param name="value">Serialized result value.</param>
33+
/// <param name="value">Serialized result value (typically JSON or plain text the model can read).</param>
3434
[SetsRequiredMembers]
3535
public FunctionResult(string toolCallId, string name, string value)
3636
{
@@ -40,17 +40,17 @@ public FunctionResult(string toolCallId, string name, string value)
4040
}
4141

4242
/// <summary>
43-
/// Gets or sets the provider-issued tool call identifier.
43+
/// Gets or sets the provider-issued tool call identifier used to correlate the result with a prior tool call.
4444
/// </summary>
4545
public string? ToolCallId { get; set; }
4646

4747
/// <summary>
48-
/// Gets or sets the function name.
48+
/// Gets or sets the function name requested by the model.
4949
/// </summary>
5050
public string Name { get; set; } = null!;
5151

5252
/// <summary>
53-
/// Gets or sets the serialized result value.
53+
/// Gets or sets the serialized result value returned to the model.
5454
/// </summary>
5555
public string Value { get; set; } = null!;
5656
}

ChatAIze.GenerativeCS/Models/ModerationResult.cs

Lines changed: 30 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,140 +3,143 @@ namespace ChatAIze.GenerativeCS.Models;
33
/// <summary>
44
/// Represents category-level flags and scores returned by the moderation endpoint.
55
/// </summary>
6+
/// <remarks>
7+
/// Boolean properties mirror the provider's category flags; score properties are confidence values between 0 and 1 where higher numbers indicate greater risk.
8+
/// </remarks>
69
public record ModerationResult
710
{
811
/// <summary>
9-
/// Gets or sets a value indicating whether any category flagged the content.
12+
/// Gets or sets a value indicating whether the provider flagged the content for any category.
1013
/// </summary>
1114
public bool IsFlagged { get; set; }
1215

1316
/// <summary>
14-
/// Gets or sets whether the content is sexual.
17+
/// Gets or sets whether the provider flagged the content as sexual.
1518
/// </summary>
1619
public bool IsSexual { get; set; }
1720

1821
/// <summary>
19-
/// Gets or sets the score for sexual content.
22+
/// Gets or sets the confidence score (0-1) for sexual content.
2023
/// </summary>
2124
public double SexualScore { get; set; }
2225

2326
/// <summary>
24-
/// Gets or sets whether the content is sexual and involves minors.
27+
/// Gets or sets whether the provider flagged the content as sexual content involving minors.
2528
/// </summary>
2629
public bool IsSexualMinors { get; set; }
2730

2831
/// <summary>
29-
/// Gets or sets the score for sexual content involving minors.
32+
/// Gets or sets the confidence score (0-1) for sexual content involving minors.
3033
/// </summary>
3134
public double SexualMinorsScore { get; set; }
3235

3336
/// <summary>
34-
/// Gets or sets whether the content is harassment.
37+
/// Gets or sets whether the provider flagged the content as harassment.
3538
/// </summary>
3639
public bool IsHarassment { get; set; }
3740

3841
/// <summary>
39-
/// Gets or sets the score for harassment.
42+
/// Gets or sets the confidence score (0-1) for harassment.
4043
/// </summary>
4144
public double HarassmentScore { get; set; }
4245

4346
/// <summary>
44-
/// Gets or sets whether the content is threatening harassment.
47+
/// Gets or sets whether the provider flagged the content as threatening harassment.
4548
/// </summary>
4649
public bool IsHarassmentThreatening { get; set; }
4750

4851
/// <summary>
49-
/// Gets or sets the score for threatening harassment.
52+
/// Gets or sets the confidence score (0-1) for threatening harassment.
5053
/// </summary>
5154
public double HarassmentThreateningScore { get; set; }
5255

5356
/// <summary>
54-
/// Gets or sets whether the content expresses hate.
57+
/// Gets or sets whether the provider flagged the content for hate.
5558
/// </summary>
5659
public bool IsHate { get; set; }
5760

5861
/// <summary>
59-
/// Gets or sets the score for hate content.
62+
/// Gets or sets the confidence score (0-1) for hate content.
6063
/// </summary>
6164
public double HateScore { get; set; }
6265

6366
/// <summary>
64-
/// Gets or sets whether the content is threatening hate.
67+
/// Gets or sets whether the provider flagged the content for threatening hate.
6568
/// </summary>
6669
public bool IsHateThreatening { get; set; }
6770

6871
/// <summary>
69-
/// Gets or sets the score for threatening hate content.
72+
/// Gets or sets the confidence score (0-1) for threatening hate content.
7073
/// </summary>
7174
public double HateThreateningScore { get; set; }
7275

7376
/// <summary>
74-
/// Gets or sets whether the content is illicit.
77+
/// Gets or sets whether the provider flagged the content as illicit.
7578
/// </summary>
7679
public bool IsIllicit { get; set; }
7780

7881
/// <summary>
79-
/// Gets or sets the score for illicit content.
82+
/// Gets or sets the confidence score (0-1) for illicit content.
8083
/// </summary>
8184
public double IllicitScore { get; set; }
8285

8386
/// <summary>
84-
/// Gets or sets whether the content is illicit and violent.
87+
/// Gets or sets whether the provider flagged the content as illicit and violent.
8588
/// </summary>
8689
public bool IsIllicitViolent { get; set; }
8790

8891
/// <summary>
89-
/// Gets or sets the score for illicit violent content.
92+
/// Gets or sets the confidence score (0-1) for illicit violent content.
9093
/// </summary>
9194
public double IllicitViolentScore { get; set; }
9295

9396
/// <summary>
94-
/// Gets or sets whether the content contains self-harm.
97+
/// Gets or sets whether the provider flagged the content for self-harm.
9598
/// </summary>
9699
public bool IsSelfHarm { get; set; }
97100

98101
/// <summary>
99-
/// Gets or sets the score for self-harm content.
102+
/// Gets or sets the confidence score (0-1) for self-harm content.
100103
/// </summary>
101104
public double SelfHarmScore { get; set; }
102105

103106
/// <summary>
104-
/// Gets or sets whether the content indicates self-harm intent.
107+
/// Gets or sets whether the provider flagged the content for self-harm intent.
105108
/// </summary>
106109
public bool IsSelfHarmIntent { get; set; }
107110

108111
/// <summary>
109-
/// Gets or sets the score for self-harm intent.
112+
/// Gets or sets the confidence score (0-1) for self-harm intent.
110113
/// </summary>
111114
public double SelfHarmIntentScore { get; set; }
112115

113116
/// <summary>
114-
/// Gets or sets whether the content contains self-harm instructions.
117+
/// Gets or sets whether the provider flagged the content for self-harm instructions.
115118
/// </summary>
116119
public bool IsSelfHarmInstruction { get; set; }
117120

118121
/// <summary>
119-
/// Gets or sets the score for self-harm instructions.
122+
/// Gets or sets the confidence score (0-1) for self-harm instructions.
120123
/// </summary>
121124
public double SelfHarmInstructionScore { get; set; }
122125

123126
/// <summary>
124-
/// Gets or sets whether the content contains violence.
127+
/// Gets or sets whether the provider flagged the content for violence.
125128
/// </summary>
126129
public bool IsViolence { get; set; }
127130

128131
/// <summary>
129-
/// Gets or sets the score for violence.
132+
/// Gets or sets the confidence score (0-1) for violence.
130133
/// </summary>
131134
public double ViolenceScore { get; set; }
132135

133136
/// <summary>
134-
/// Gets or sets whether the content contains graphic violence.
137+
/// Gets or sets whether the provider flagged the content for graphic violence.
135138
/// </summary>
136139
public bool IsViolenceGraphic { get; set; }
137140

138141
/// <summary>
139-
/// Gets or sets the score for graphic violence.
142+
/// Gets or sets the confidence score (0-1) for graphic violence.
140143
/// </summary>
141144
public double ViolenceGraphicScore { get; set; }
142145
}

ChatAIze.GenerativeCS/Options/OpenAI/ChatCompletionOptions.cs

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -19,116 +19,116 @@ public record ChatCompletionOptions<TMessage, TFunctionCall, TFunctionResult>
1919
/// <summary>
2020
/// Initializes a new set of completion options.
2121
/// </summary>
22-
/// <param name="model">Model identifier to target.</param>
23-
/// <param name="apiKey">Optional API key overriding the client default.</param>
22+
/// <param name="model">Model identifier to target (defaults to <see cref="DefaultModels.OpenAI.ChatCompletion"/>).</param>
23+
/// <param name="apiKey">Optional API key overriding the client default for chat completions.</param>
2424
public ChatCompletionOptions(string model = DefaultModels.OpenAI.ChatCompletion, string? apiKey = null)
2525
{
2626
Model = model;
2727
ApiKey = apiKey;
2828
}
2929

3030
/// <summary>
31-
/// Gets or sets the model identifier used for chat completions.
31+
/// Gets or sets the model identifier used for chat completions (defaults to <see cref="DefaultModels.OpenAI.ChatCompletion"/>).
3232
/// </summary>
3333
public string Model { get; set; } = DefaultModels.OpenAI.ChatCompletion;
3434

3535
/// <summary>
36-
/// Gets or sets an optional API key that overrides the client-level key.
36+
/// Gets or sets an optional API key that overrides the client-level key for chat completions.
3737
/// </summary>
3838
public string? ApiKey { get; set; }
3939

4040
/// <summary>
41-
/// Gets or sets an optional stable end-user identifier passed to the provider for safety, abuse, or rate limiting.
41+
/// Gets or sets an optional stable end-user identifier passed to the provider when the chat instance does not supply one.
4242
/// </summary>
4343
public string? UserTrackingId { get; set; }
4444

4545
/// <summary>
46-
/// Gets or sets the maximum number of retry attempts for a failed request.
46+
/// Gets or sets the maximum number of attempts (including the first call) before a request is treated as failed.
4747
/// </summary>
4848
public int MaxAttempts { get; set; } = 5;
4949

5050
/// <summary>
51-
/// Gets or sets the maximum number of tokens the model may generate.
51+
/// Gets or sets the maximum number of tokens the assistant may generate; null uses the provider default.
5252
/// </summary>
5353
public int? MaxOutputTokens { get; set; }
5454

5555
/// <summary>
56-
/// Gets or sets the maximum number of non-system messages to include.
56+
/// Gets or sets the maximum number of non-system messages to include; the oldest unpinned messages are trimmed first when exceeded.
5757
/// </summary>
5858
public int? MessageLimit { get; set; }
5959

6060
/// <summary>
61-
/// Gets or sets the maximum total character count across user and assistant messages.
61+
/// Gets or sets the maximum total character count across non-system message content and function results; excess content is trimmed by dropping earlier unpinned messages.
6262
/// </summary>
6363
public int? CharacterLimit { get; set; }
6464

6565
/// <summary>
66-
/// Gets or sets an optional seed for deterministic responses.
66+
/// Gets or sets an optional seed for deterministic responses when the selected model supports seeding.
6767
/// </summary>
6868
public int? Seed { get; set; }
6969

7070
/// <summary>
71-
/// Gets or sets the sampling temperature.
71+
/// Gets or sets the sampling temperature; lower values make responses more deterministic.
7272
/// </summary>
7373
public double? Temperature { get; set; }
7474

7575
/// <summary>
76-
/// Gets or sets nucleus sampling probability mass.
76+
/// Gets or sets nucleus sampling probability mass (use with or instead of temperature).
7777
/// </summary>
7878
public double? TopP { get; set; }
7979

8080
/// <summary>
81-
/// Gets or sets the frequency penalty applied to repeated tokens.
81+
/// Gets or sets the frequency penalty applied to repeated tokens to reduce repetition.
8282
/// </summary>
8383
public double? FrequencyPenalty { get; set; }
8484

8585
/// <summary>
86-
/// Gets or sets the presence penalty applied to repeated tokens.
86+
/// Gets or sets the presence penalty applied to repeated tokens to encourage new topics.
8787
/// </summary>
8888
public double? PresencePenalty { get; set; }
8989

9090
/// <summary>
91-
/// Gets or sets the desired reasoning effort for the response.
91+
/// Gets or sets the desired reasoning effort for the response on models that support this control.
9292
/// </summary>
9393
public ReasoningEffort ReasoningEffort { get; set; } = ReasoningEffort.None;
9494

9595
/// <summary>
96-
/// Gets or sets the expected verbosity level for the response.
96+
/// Gets or sets the expected verbosity level for the response on models that support this control.
9797
/// </summary>
9898
public Verbosity Verbosity { get; set; } = Verbosity.Medium;
9999

100100
/// <summary>
101-
/// Gets or sets an optional CLR type for JSON schema response formatting.
101+
/// Gets or sets an optional CLR type to serialize into a JSON schema for response_format, enabling structured JSON responses.
102102
/// </summary>
103103
public Type? ResponseType { get; set; }
104104

105105
/// <summary>
106-
/// Gets or sets a value indicating whether the model should respond with JSON mode enabled.
106+
/// Gets or sets a value indicating whether to force OpenAI's JSON object mode when no <see cref="ResponseType"/> is provided.
107107
/// </summary>
108108
public bool IsJsonMode { get; set; }
109109

110110
/// <summary>
111-
/// Gets or sets a value indicating whether the model may call multiple functions in parallel.
111+
/// Gets or sets a value indicating whether the model may call multiple functions in parallel in a single turn.
112112
/// </summary>
113113
public bool IsParallelFunctionCallingOn { get; set; } = true;
114114

115115
/// <summary>
116-
/// Gets or sets a value indicating whether the model must follow strict function schemas.
116+
/// Gets or sets a value indicating whether function calling should enforce strict schemas and disable parallel tool calls.
117117
/// </summary>
118118
public bool IsStrictFunctionCallingOn { get; set; }
119119

120120
/// <summary>
121-
/// Gets or sets a value indicating whether responses should be stored by the provider.
121+
/// Gets or sets a value indicating whether responses should be stored by the provider (sends the store flag).
122122
/// </summary>
123123
public bool IsStoringOutputs { get; set; }
124124

125125
/// <summary>
126-
/// Gets or sets a value indicating whether time metadata should be appended automatically.
126+
/// Gets or sets a value indicating whether a system message with the current time should be appended automatically.
127127
/// </summary>
128128
public bool IsTimeAware { get; set; }
129129

130130
/// <summary>
131-
/// Gets or sets a value indicating whether previous function calls should be removed before sending.
131+
/// Gets or sets a value indicating whether function call and result messages before the latest user message should be removed.
132132
/// </summary>
133133
public bool IsIgnoringPreviousFunctionCalls { get; set; }
134134

@@ -138,17 +138,17 @@ public ChatCompletionOptions(string model = DefaultModels.OpenAI.ChatCompletion,
138138
public bool IsDebugMode { get; set; }
139139

140140
/// <summary>
141-
/// Gets or sets stop words that terminate generation.
141+
/// Gets or sets stop sequences that terminate generation when produced.
142142
/// </summary>
143143
public List<string> StopWords { get; set; } = [];
144144

145145
/// <summary>
146-
/// Gets or sets functions available to the model.
146+
/// Gets or sets functions available to the model as OpenAI tool definitions.
147147
/// </summary>
148148
public List<IChatFunction> Functions { get; set; } = [];
149149

150150
/// <summary>
151-
/// Gets or sets a callback used to dynamically supply a system message.
151+
/// Gets or sets a callback used to dynamically supply a system message at request time.
152152
/// </summary>
153153
public Func<string?>? SystemMessageCallback { get; set; } = null;
154154

@@ -158,12 +158,12 @@ public ChatCompletionOptions(string model = DefaultModels.OpenAI.ChatCompletion,
158158
public Func<DateTime> TimeCallback { get; set; } = () => DateTime.Now;
159159

160160
/// <summary>
161-
/// Gets or sets a callback invoked whenever a message is added to the chat.
161+
/// Gets or sets a callback invoked whenever a message is added to the chat during request processing.
162162
/// </summary>
163163
public Func<TMessage, Task> AddMessageCallback { get; set; } = (_) => Task.CompletedTask;
164164

165165
/// <summary>
166-
/// Gets or sets the fallback function callback used when a function does not have an explicit delegate.
166+
/// Gets or sets the fallback function callback used when a function does not have an explicit delegate; should return a string or serializable object.
167167
/// </summary>
168168
public Func<string, string, CancellationToken, ValueTask<object?>> DefaultFunctionCallback { get; set; } = (_, _, _) => throw new NotImplementedException("Function callback has not been implemented.");
169169

0 commit comments

Comments
 (0)