Skip to content

Commit

Permalink
improve XML documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@jochenkirstaetter
jochenkirstaetter committed Mar 29, 2024
1 parent ba34bb5 commit 754266b
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 33 deletions.
47 changes: 24 additions & 23 deletions src/Mscc.GenerativeAI/GenerativeModel.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,8 +171,9 @@ public string? ProjectId
}

/// <summary>
/// Default constructor attempts to read environment variables and
/// sets default values, if available
/// Initializes a new instance of the <see cref="GenerativeModel"/> class.
/// The default constructor attempts to read <c>.env</c> file and environment variables.
/// Sets default values, if available.
/// </summary>
public GenerativeModel()
{
Expand All @@ -193,13 +194,13 @@ public GenerativeModel()
}

/// <summary>
/// Constructor to initialize access to Google AI Gemini API.
/// Initializes a new instance of the <see cref="GenerativeModel"/> class with access to Google AI Gemini API.
/// </summary>
/// <param name="apiKey">API key provided by Google AI Studio</param>
/// <param name="model">Model to use (default: "gemini-pro")</param>
/// <param name="generationConfig">Optional. Configuration options for model generation and outputs.</param>
/// <param name="safetySettings">Optional. A list of unique SafetySetting instances for blocking unsafe content.</param>
public GenerativeModel(string? apiKey = null,
internal GenerativeModel(string? apiKey = null,
string? model = null,
GenerationConfig? generationConfig = null,
List<SafetySetting>? safetySettings = null) : this()
Expand All @@ -211,7 +212,7 @@ public GenerativeModel(string? apiKey = null,
}

/// <summary>
/// Constructor to initialize access to Vertex AI Gemini API.
/// Initializes a new instance of the <see cref="GenerativeModel"/> class with access to Vertex AI Gemini API.
/// </summary>
/// <param name="projectId">Identifier of the Google Cloud project</param>
/// <param name="region">Region to use</param>
Expand Down Expand Up @@ -332,7 +333,7 @@ public async Task<CreateTunedModelResponse> CreateTunedModel(CreateTunedModelReq
/// </summary>
/// <param name="model">Required. The resource name of the model. Format: tunedModels/my-model-id</param>
/// <returns>If successful, the response body is empty.</returns>
/// <exception cref="ArgumentNullException">Thrown when the model is null or empty.</exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="model"/> is null or empty.</exception>
/// <exception cref="NotSupportedException">Thrown when the functionality is not supported by the model.</exception>
public async Task<string> DeleteTunedModel(string model)
{
Expand All @@ -359,7 +360,7 @@ public async Task<string> DeleteTunedModel(string model)
/// <param name="tunedModel">The tuned model to update.</param>
/// <param name="updateMask">Required. The list of fields to update. This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".</param>
/// <returns></returns>
/// <exception cref="ArgumentNullException">Thrown when the model is null or empty.</exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="model"/> is null or empty.</exception>
/// <exception cref="NotSupportedException">Thrown when the functionality is not supported by the model.</exception>
public async Task<ModelResponse> PatchTunedModel(string model, ModelResponse tunedModel, string? updateMask = null)
{
Expand Down Expand Up @@ -403,7 +404,7 @@ public async Task<ModelResponse> PatchTunedModel(string model, ModelResponse tun
/// <param name="model">Required. The resource name of the tuned model to transfer ownership. Format: tunedModels/my-model-id</param>
/// <param name="emailAddress">Required. The email address of the user to whom the tuned model is being transferred to.</param>
/// <returns>If successful, the response body is empty.</returns>
/// <exception cref="ArgumentNullException">Thrown when the model is null or empty.</exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="model"/> or <paramref name="emailAddress"/> is null or empty.</exception>
/// <exception cref="NotSupportedException">Thrown when the functionality is not supported by the model.</exception>
public async Task<string> TransferOwnership(string model, string emailAddress)
{
Expand Down Expand Up @@ -431,7 +432,7 @@ public async Task<string> TransferOwnership(string model, string emailAddress)
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async Task<GenerateContentResponse> GenerateContent(GenerateContentRequest? request)
{
if (request == null) throw new ArgumentNullException(nameof(request));
Expand Down Expand Up @@ -470,7 +471,7 @@ public async Task<GenerateContentResponse> GenerateContent(GenerateContentReques
return await Deserialize<GenerateContentResponse>(response);
}

/// <remarks/>
/// <inheritdoc cref="M:GenerativeModel.GenerateContent(request)"/>
public async Task<GenerateContentResponse> GenerateContent(string? prompt,
GenerationConfig? generationConfig = null,
List<SafetySetting>? safetySettings = null,
Expand Down Expand Up @@ -509,7 +510,7 @@ public async Task<GenerateContentResponse> GenerateContent(List<IPart>? parts,
/// <param name="request">The request to send to the API.</param>
/// <param name="cancellationToken"></param>
/// <returns>Stream of GenerateContentResponse with chunks asynchronously.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async IAsyncEnumerable<GenerateContentResponse> GenerateContentStream(GenerateContentRequest? request,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
Expand Down Expand Up @@ -595,7 +596,7 @@ public IAsyncEnumerable<GenerateContentResponse> GenerateContentStream(List<IPar
/// </summary>
/// <param name="request"></param>
/// <returns>Response from the model for a grounded answer.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<GenerateAnswerResponse> GenerateAnswer(GenerateAnswerRequest? request)
{
Expand Down Expand Up @@ -655,7 +656,7 @@ public async Task<GenerateAnswerResponse> GenerateAnswer(string? prompt,
/// <param name="taskType">Optional. Optional task type for which the embeddings will be used. Can only be set for models/embedding-001.</param>
/// <param name="title">Optional. An optional title for the text. Only applicable when TaskType is RETRIEVAL_DOCUMENT. Note: Specifying a title for RETRIEVAL_DOCUMENT provides better quality embeddings for retrieval.</param>
/// <returns>Embeddings of the content as a list of floating numbers.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<EmbedContentResponse> EmbedContent(EmbedContentRequest request, TaskType? taskType = null, string? title = null)
{
Expand All @@ -680,7 +681,7 @@ public async Task<EmbedContentResponse> EmbedContent(EmbedContentRequest request
/// <param name="taskType">Optional. Optional task type for which the embeddings will be used. Can only be set for models/embedding-001.</param>
/// <param name="title">Optional. An optional title for the text. Only applicable when TaskType is RETRIEVAL_DOCUMENT. Note: Specifying a title for RETRIEVAL_DOCUMENT provides better quality embeddings for retrieval.</param>
/// <returns>Embeddings of the content as a list of floating numbers.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="prompt"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<EmbedContentResponse> EmbedContent(string? prompt, TaskType? taskType = null, string? title = null)
{
Expand All @@ -703,7 +704,7 @@ public async Task<EmbedContentResponse> EmbedContent(string? prompt, TaskType? t
/// </summary>
/// <param name="requests">Required. Embed requests for the batch. The model in each of these requests must match the model specified BatchEmbedContentsRequest.model.</param>
/// <returns>List of Embeddings of the content as a list of floating numbers.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="requests"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<EmbedContentResponse> BatchEmbedContent(List<EmbedContentRequest> requests)
{
Expand All @@ -726,7 +727,7 @@ public async Task<EmbedContentResponse> BatchEmbedContent(List<EmbedContentReque
/// </summary>
/// <param name="request"></param>
/// <returns>Number of tokens.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async Task<CountTokensResponse> CountTokens(GenerateContentRequest? request)
{
if (request == null) throw new ArgumentNullException(nameof(request));
Expand Down Expand Up @@ -800,7 +801,7 @@ public ChatSession StartChat(List<ContentResponse>? history = null,
/// </summary>
/// <param name="request">The request to send to the API.</param>
/// <returns></returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<GenerateTextResponse> GenerateText(GenerateTextRequest? request)
{
Expand Down Expand Up @@ -832,7 +833,7 @@ public async Task<GenerateTextResponse> GenerateText(string prompt)
/// </summary>
/// <param name="request"></param>
/// <returns>Number of tokens.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async Task<CountTokensResponse> CountTokens(GenerateTextRequest? request)
{
if (request == null) throw new ArgumentNullException(nameof(request));
Expand All @@ -851,7 +852,7 @@ public async Task<CountTokensResponse> CountTokens(GenerateTextRequest? request)
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async Task<GenerateMessageResponse> GenerateMessage(GenerateMessageRequest? request)
{
if (request == null) throw new ArgumentNullException(nameof(request));
Expand Down Expand Up @@ -882,7 +883,7 @@ public async Task<GenerateMessageResponse> GenerateMessage(string prompt)
/// </summary>
/// <param name="request"></param>
/// <returns>Number of tokens.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async Task<CountTokensResponse> CountTokens(GenerateMessageRequest request)
{
if (request == null) throw new ArgumentNullException(nameof(request));
Expand All @@ -901,7 +902,7 @@ public async Task<CountTokensResponse> CountTokens(GenerateMessageRequest reques
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<EmbedTextResponse> EmbedText(EmbedTextRequest request)
{
Expand Down Expand Up @@ -938,7 +939,7 @@ public async Task<EmbedTextResponse> EmbedText(string prompt)
/// </summary>
/// <param name="request"></param>
/// <returns>Number of tokens.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
public async Task<CountTokensResponse> CountTokens(EmbedTextRequest request)
{
if (request == null) throw new ArgumentNullException(nameof(request));
Expand All @@ -957,7 +958,7 @@ public async Task<CountTokensResponse> CountTokens(EmbedTextRequest request)
/// </summary>
/// <param name="request">Required. Embed requests for the batch. The model in each of these requests must match the model specified BatchEmbedContentsRequest.model.</param>
/// <returns>List of Embeddings of the content as a list of floating numbers.</returns>
/// <exception cref="ArgumentNullException"></exception>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="request"/> is <see langword="null"/>.</exception>
/// <exception cref="NotSupportedException"></exception>
public async Task<EmbedTextResponse> BatchEmbedText(BatchEmbedTextRequest request)
{
Expand Down
8 changes: 4 additions & 4 deletions src/Mscc.GenerativeAI/GoogleAI.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ public sealed class GoogleAI : IGenerativeAI
private GenerativeModel? _generativeModel;

/// <summary>
/// Default constructor attempts to read <c>.env</c> file and environment variables.
/// Initializes a new instance of the <see cref="GoogleAI"/> class with access to Google AI Gemini API.
/// The default constructor attempts to read <c>.env</c> file and environment variables.
/// Sets default values, if available.
/// </summary>
/// <remarks>The following environment variables are used:
Expand All @@ -30,13 +31,12 @@ public sealed class GoogleAI : IGenerativeAI
private GoogleAI()
{
GenerativeAIExtensions.ReadDotEnv();

_apiKey = Environment.GetEnvironmentVariable("GOOGLE_API_KEY");
_accessToken = Environment.GetEnvironmentVariable("GOOGLE_ACCESS_TOKEN");
}

/// <summary>
/// Initialize access to Google AI Gemini API.
/// Initializes a new instance of the <see cref="GoogleAI"/> class with access to Google AI Gemini API.
/// Either API key or access token is required.
/// </summary>
/// <param name="apiKey">Identifier of the Google Cloud project</param>
Expand All @@ -53,7 +53,7 @@ public GoogleAI(string? apiKey = null, string? accessToken = null) : this()
/// <param name="model">Model to use (default: "gemini-1.0-pro")</param>
/// <param name="generationConfig">Optional. Configuration options for model generation and outputs.</param>
/// <param name="safetySettings">Optional. A list of unique SafetySetting instances for blocking unsafe content.</param>
/// <exception cref="ArgumentNullException">Thrown when either API key or access token is null.</exception>
/// <exception cref="ArgumentNullException">Thrown when both <paramref name="apiKey"/> and <paramref name="accessToken"/> are <see langword="null"/>.</exception>
/// <returns>Generative model instance.</returns>
public GenerativeModel GenerativeModel(string model = Model.Gemini10Pro,
GenerationConfig? generationConfig = null,
Expand Down
2 changes: 1 addition & 1 deletion src/Mscc.GenerativeAI/IGenerativeAI.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ namespace Mscc.GenerativeAI
public interface IGenerativeAI
{
/// <summary>
/// Create a generative model to use.
/// Create an instance of a generative model to use.
/// </summary>
/// <param name="model">Model to use (default: "gemini-1.0-pro")</param>
/// <param name="generationConfig">Optional. Configuration options for model generation and outputs.</param>
Expand Down
10 changes: 5 additions & 5 deletions src/Mscc.GenerativeAI/VertexAI.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ public sealed class VertexAI : IGenerativeAI
private GenerativeModel? _generativeModel;

/// <summary>
/// Default constructor attempts to read <c>.env</c> file and environment variables.
/// Initializes a new instance of the <see cref="VertexAI"/> class with access to Vertex AI Gemini API.
/// The default constructor attempts to read <c>.env</c> file and environment variables.
/// Sets default values, if available.
/// </summary>
/// <remarks>The following environment variables are used:
Expand All @@ -30,17 +31,16 @@ public sealed class VertexAI : IGenerativeAI
private VertexAI()
{
GenerativeAIExtensions.ReadDotEnv();

_projectId = Environment.GetEnvironmentVariable("GOOGLE_PROJECT_ID");
_region = Environment.GetEnvironmentVariable("GOOGLE_REGION") ?? _region;
}

/// <summary>
/// Initialize access to Vertex AI Gemini API.
/// Initializes a new instance of the <see cref="VertexAI"/> class with access to Vertex AI Gemini API.
/// </summary>
/// <param name="projectId">Identifier of the Google Cloud project.</param>
/// <param name="region">Region to use (default: "us-central1").</param>
/// <exception cref="ArgumentNullException">Thrown when projectId is null.</exception>
/// <exception cref="ArgumentNullException">Thrown when <paramref name="projectId"/> is <see langword="null"/>.</exception>
public VertexAI(string projectId, string? region = null) : this()
{
_projectId ??= projectId ?? throw new ArgumentNullException(nameof(projectId));
Expand All @@ -53,7 +53,7 @@ public VertexAI(string projectId, string? region = null) : this()
/// <param name="model">Model to use (default: "gemini-1.0-pro")</param>
/// <param name="generationConfig">Optional. Configuration options for model generation and outputs.</param>
/// <param name="safetySettings">Optional. A list of unique SafetySetting instances for blocking unsafe content.</param>
/// <exception cref="ArgumentNullException">Thrown when projectId or region is null.</exception>
/// <exception cref="ArgumentNullException">Thrown when <paramref name="projectId"/> or <paramref name="region"/> is <see langword="null"/>.</exception>
/// <returns>Generative model instance.</returns>
public GenerativeModel GenerativeModel(string model = Model.Gemini10Pro,
GenerationConfig? generationConfig = null,
Expand Down

0 comments on commit 754266b

Please sign in to comment.