diff --git a/source/Kagi/KagiAnswerData.cs b/source/Kagi/KagiAnswerData.cs
index d9dd686..290066b 100644
--- a/source/Kagi/KagiAnswerData.cs
+++ b/source/Kagi/KagiAnswerData.cs
@@ -8,26 +8,28 @@
namespace Kagi
{
///
- ///
+ /// Represents the response data for a
+ /// .
///
public class KagiAnswerData
{
///
- ///
+ /// The answer output.
///
[JsonPropertyName(
"output")]
public string Output { get; init; }
///
- ///
+ /// A collection of
+ /// search records that were utilized to produce the answer output.
///
[JsonPropertyName(
"references")]
public ImmutableArray References { get; init; }
///
- ///
+ /// The number of tokens processed to produce the answer output.
///
[JsonPropertyName(
"tokens")]
diff --git a/source/Kagi/KagiAnswerDataReference.cs b/source/Kagi/KagiAnswerDataReference.cs
index 1842b75..80f4f9e 100644
--- a/source/Kagi/KagiAnswerDataReference.cs
+++ b/source/Kagi/KagiAnswerDataReference.cs
@@ -6,26 +6,26 @@
namespace Kagi
{
///
- ///
+ /// Represents a search record that was utilized to produce the output for an answer.
///
public class KagiAnswerDataReference
{
///
- ///
+ /// The title of the referenced search record.
///
[JsonPropertyName(
"title")]
public string Title { get; init; }
///
- ///
+ /// The snippet of the referenced search record, if any.
///
[JsonPropertyName(
"Snippet")]
public string Snippet { get; init; }
///
- ///
+ /// The URL of the referenced search record.
///
[JsonPropertyName(
"url")]
diff --git a/source/Kagi/KagiAnswerOptions.cs b/source/Kagi/KagiAnswerOptions.cs
index 0ee93be..476b6dc 100644
--- a/source/Kagi/KagiAnswerOptions.cs
+++ b/source/Kagi/KagiAnswerOptions.cs
@@ -6,22 +6,23 @@
namespace Kagi
{
///
- ///
+ /// Represents the options for an answer operation.
///
public class KagiAnswerOptions
{
///
- ///
+ /// The query to be answered.
///
[JsonPropertyName(
"query")]
public string Query { get; init; }
///
- ///
+ /// Whether to allow cached requests and responses.
///
[JsonPropertyName(
"cache")]
- public bool AllowCaching { get; init; }
+ public bool AllowCaching { get; init; } =
+ true;
}
}
diff --git a/source/Kagi/KagiAnswerResult.cs b/source/Kagi/KagiAnswerResult.cs
index 3b9cbaa..199bc90 100644
--- a/source/Kagi/KagiAnswerResult.cs
+++ b/source/Kagi/KagiAnswerResult.cs
@@ -6,13 +6,13 @@
namespace Kagi
{
///
- ///
+ /// Represents the result of an answer operation.
///
public class KagiAnswerResult :
KagiResult
{
///
- ///
+ /// The response data for the result.
///
[JsonPropertyName(
"data")]
diff --git a/source/Kagi/KagiClient.cs b/source/Kagi/KagiClient.cs
index b2a79e7..51d5ba1 100644
--- a/source/Kagi/KagiClient.cs
+++ b/source/Kagi/KagiClient.cs
@@ -19,19 +19,19 @@ public sealed class KagiClient :
IDisposable
{
///
- ///
+ /// The base URL for the Kagi API.
///
private const string DefaultBaseUrlValue =
"https://kagi.com/api/v0/";
///
- ///
+ /// Gets the default base URL for a .
///
public static Uri DefaultBaseUrl { get; } =
new Uri(DefaultBaseUrlValue);
///
- ///
+ /// The JSON serializer options for serializing and deserializing JSON data.
///
private static JsonSerializerOptions JsonSerializerOptions { get; } =
new JsonSerializerOptions()
@@ -41,11 +41,11 @@ public sealed class KagiClient :
};
///
- ///
+ /// Creates an instance of HttpClient with the specified base URL and API key.
///
- ///
- ///
- ///
+ /// The base URL for the API.
+ /// The API key used for authorization.
+ /// A configured HttpClient instance.
private static HttpClient CreateClient(
Uri baseUrl,
string apiKey)
@@ -62,8 +62,11 @@ private static HttpClient CreateClient(
var client = new HttpClient();
+ // Set the base URL for the client to use.
client.BaseAddress =
baseUrl;
+
+ // Set the 'Authorization' header value.
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue(
"Bot",
@@ -73,20 +76,23 @@ private static HttpClient CreateClient(
}
///
- ///
+ /// Processes the HTTP response, deserializing it into a result or throwing an exception if the response contains an error.
///
- ///
- ///
- ///
- ///
- ///
+ /// Type of result expected from the response.
+ /// The HTTP response message.
+ /// Token to observe while waiting for the task to complete.
+ /// A task that represents the asynchronous operation, containing the result.
+ /// Thrown if the response contains an error.
private static async Task ProcessResponseAsync(
HttpResponseMessage response,
CancellationToken cancellationToken = default)
where TResult : KagiResult
{
+ // Check the status code for the response.
if (response.StatusCode == HttpStatusCode.OK)
{
+ // Read the successful result from the response body.
+ // TODO: Should exception handling here be more robust(?)
var result =
await response.Content
.ReadFromJsonAsync(
@@ -97,6 +103,7 @@ await response.Content
}
else
{
+ // Read the error result from the response body.
var errorResult =
await response.Content
.ReadFromJsonAsync(
@@ -114,7 +121,7 @@ await response.Content
private volatile bool isDisposed;
///
- ///
+ /// Gets the base URL used by the client.
///
public Uri BaseUrl
{
@@ -131,7 +138,7 @@ public Uri BaseUrl
}
///
- ///
+ /// Gets the authorization header value set on the client.
///
public AuthenticationHeaderValue AuthorizationHeaderValue
{
@@ -149,9 +156,10 @@ public AuthenticationHeaderValue AuthorizationHeaderValue
}
///
- ///
+ /// Initializes a new instance of the
+ /// class with the specified API key.
///
- ///
+ /// The API key for authorizing requests.
public KagiClient(
string apiKey) :
this(
@@ -160,10 +168,11 @@ public KagiClient(
{ }
///
- ///
+ /// Initializes a new instance of the
+ /// class with the specified base URL and API key.
///
- ///
- ///
+ /// The base URL for the API.
+ /// The API key for authorizing requests.
public KagiClient(
Uri baseUrl,
string apiKey) :
@@ -175,10 +184,11 @@ public KagiClient(
{ }
///
- ///
+ /// Initializes a new instance of the
+ /// class with a specified and ownership flag.
///
- ///
- ///
+ /// The instance to use.
+ /// Specifies whether the client should dispose the HttpClient instance.
public KagiClient(
HttpClient client,
bool ownsClient = false)
@@ -193,12 +203,12 @@ public KagiClient(
}
///
- ///
+ /// Sends a summarization request to Kagi.
///
- ///
- ///
- ///
- ///
+ /// The options for summarization.
+ /// Token to observe while waiting for the task to complete.
+ /// A task that represents the asynchronous operation, containing the summarization result.
+ /// Thrown if the request fails.
public async Task SummarizeAsync(
KagiSummarizeOptions options,
CancellationToken cancellationToken = default)
@@ -213,6 +223,7 @@ public async Task SummarizeAsync(
this.isDisposed,
this);
+ // Attempt to create a valid endpoint URL for the request.
if (!TryCreateSummarizeRequestUri(
out var requestUri))
{
@@ -220,6 +231,7 @@ public async Task SummarizeAsync(
$"Failed to create a valid URL for the request.");
}
+ // Serialize the provided options and POST the request...
var response =
await this.client
.PostAsJsonAsync(
@@ -228,18 +240,19 @@ await this.client
JsonSerializerOptions,
cancellationToken);
+ // ...then process the response and return the result.
return await ProcessResponseAsync(
response,
cancellationToken);
}
///
- ///
+ /// Sends an answer generation request to Kagi.
///
- ///
- ///
- ///
- ///
+ /// The options for generating the answer.
+ /// Token to observe while waiting for the task to complete.
+ /// A task that represents the asynchronous operation, containing the answer result.
+ /// Thrown if the request fails.
public async Task AnswerAsync(
KagiAnswerOptions options,
CancellationToken cancellationToken = default)
@@ -254,6 +267,7 @@ public async Task AnswerAsync(
this.isDisposed,
this);
+ // Attempt to create a valid endpoint URL for the request.
if (!TryCreateAnswerRequestUri(
out var requestUri))
{
@@ -261,6 +275,7 @@ public async Task AnswerAsync(
$"Failed to create a valid URL for the request.");
}
+ // Serialize the provided options and POST the request...
var response =
await this.client
.PostAsJsonAsync(
@@ -269,19 +284,20 @@ await this.client
JsonSerializerOptions,
cancellationToken);
+ // ...then process the response and return the result.
return await ProcessResponseAsync(
response,
cancellationToken);
}
///
- ///
+ /// Sends a search request to Kagi.
///
- ///
- ///
- ///
- ///
- ///
+ /// The search query.
+ /// Limit for the number of results returned.
+ /// Token to observe while waiting for the task to complete.
+ /// A task that represents the asynchronous operation, containing the search result.
+ /// Thrown if the request fails.
public async Task SearchAsync(
string query,
int limit,
@@ -302,6 +318,7 @@ public async Task SearchAsync(
this.isDisposed,
this);
+ // Attempt to create a valid endpoint URL for the request.
if (!TryCreateSearchRequestUri(
query,
limit,
@@ -311,24 +328,26 @@ public async Task SearchAsync(
$"Failed to create a valid URL for the request.");
}
+ // GET the request...
var response =
await this.client
.GetAsync(
requestUri,
cancellationToken);
+ // ...then process the response and return the result.
return await ProcessResponseAsync(
response,
cancellationToken);
}
///
- ///
+ /// Sends a web enrichment search request to Kagi.
///
- ///
- ///
- ///
- ///
+ /// The search query.
+ /// Token to observe while waiting for the task to complete.
+ /// A task that represents the asynchronous operation, containing the search result.
+ /// Thrown if the request fails.
public async Task SearchWebEnrichmentsAsync(
string query,
CancellationToken cancellationToken = default)
@@ -343,6 +362,7 @@ public async Task SearchWebEnrichmentsAsync(
this.isDisposed,
this);
+ // Attempt to create a valid endpoint URL for the request.
if (!TryCreateSearchWebEnrichmentsRequestUri(
query,
out var requestUri))
@@ -351,24 +371,26 @@ public async Task SearchWebEnrichmentsAsync(
$"Failed to create a valid URL for the request.");
}
+ // GET the request...
var response =
await this.client
.GetAsync(
requestUri,
cancellationToken);
+ // ...then process the response and return the result.
return await ProcessResponseAsync(
response,
cancellationToken);
}
///
- ///
+ /// Sends a news enrichment search request to Kagi.
///
- ///
- ///
- ///
- ///
+ /// The search query.
+ /// Token to observe while waiting for the task to complete.
+ /// A task that represents the asynchronous operation, containing the search result.
+ /// Thrown if the request fails.
public async Task SearchNewsEnrichmentsAsync(
string query,
CancellationToken cancellationToken = default)
@@ -383,6 +405,7 @@ public async Task SearchNewsEnrichmentsAsync(
this.isDisposed,
this);
+ // Attempt to create a valid endpoint URL for the request.
if (!TryCreateSearchNewsEnrichmentsRequestUri(
query,
out var requestUri))
@@ -391,19 +414,21 @@ public async Task SearchNewsEnrichmentsAsync(
$"Failed to create a valid URL for the request.");
}
+ // GET the request...
var response =
await this.client
.GetAsync(
requestUri,
cancellationToken);
+ // ...then process the response and return the result.
return await ProcessResponseAsync(
response,
cancellationToken);
}
///
- ///
+ /// Releases the resources used by the instance.
///
public void Dispose()
{
@@ -421,10 +446,10 @@ public void Dispose()
}
///
- ///
+ /// Tries to create a URI for the summarize request.
///
- ///
- ///
+ /// The resulting URI, if successful.
+ /// True if the URI was created successfully; otherwise, false.
private bool TryCreateSummarizeRequestUri(
out Uri result) =>
Uri.TryCreate(
@@ -433,10 +458,10 @@ private bool TryCreateSummarizeRequestUri(
out result);
///
- ///
+ /// Tries to create a URI for the answer request.
///
- ///
- ///
+ /// The resulting URI, if successful.
+ /// True if the URI was created successfully; otherwise, false.
private bool TryCreateAnswerRequestUri(
out Uri result) =>
Uri.TryCreate(
@@ -445,12 +470,12 @@ private bool TryCreateAnswerRequestUri(
out result);
///
- ///
+ /// Tries to create a URI for the search request.
///
- ///
- ///
- ///
- ///
+ /// The search query.
+ /// Limit for the number of results.
+ /// The resulting URI, if successful.
+ /// True if the URI was created successfully; otherwise, false.
private bool TryCreateSearchRequestUri(
string query,
int limit,
@@ -466,11 +491,11 @@ private bool TryCreateSearchRequestUri(
out result);
///
- ///
+ /// Tries to create a URI for the web enrichment search request.
///
- ///
- ///
- ///
+ /// The search query.
+ /// The resulting URI, if successful.
+ /// True if the URI was created successfully; otherwise, false.
private bool TryCreateSearchWebEnrichmentsRequestUri(
string query,
out Uri result) =>
@@ -484,11 +509,11 @@ private bool TryCreateSearchWebEnrichmentsRequestUri(
out result);
///
- ///
+ /// Tries to create a URI for the news enrichment search request.
///
- ///
- ///
- ///
+ /// The search query.
+ /// The resulting URI, if successful.
+ /// True if the URI was created successfully; otherwise, false.
private bool TryCreateSearchNewsEnrichmentsRequestUri(
string query,
out Uri result) =>
@@ -502,9 +527,9 @@ private bool TryCreateSearchNewsEnrichmentsRequestUri(
out result);
///
- ///
+ /// Releases the resources used by the instance.
///
- ///
+ /// True if managed resources should be disposed; otherwise, false.
private void Dispose(
bool disposing)
{
@@ -516,7 +541,7 @@ private void Dispose(
}
///
- ///
+ /// Destroys the instance.
///
~KagiClient()
{
diff --git a/source/Kagi/KagiError.cs b/source/Kagi/KagiError.cs
index 6ace14e..0f469ac 100644
--- a/source/Kagi/KagiError.cs
+++ b/source/Kagi/KagiError.cs
@@ -6,26 +6,26 @@
namespace Kagi
{
///
- ///
+ /// Represents an error that occured.
///
public class KagiError
{
///
- ///
+ /// The for the error.
///
[JsonPropertyName(
"code")]
public KagiErrorCode Code { get; init; }
///
- ///
+ /// The message for the error.
///
[JsonPropertyName(
"msg")]
public string Message { get; init; }
///
- ///
+ /// The location reference for the error, if any.
///
[JsonPropertyName(
"ref")]
diff --git a/source/Kagi/KagiErrorCode.cs b/source/Kagi/KagiErrorCode.cs
index b66c9f6..8313745 100644
--- a/source/Kagi/KagiErrorCode.cs
+++ b/source/Kagi/KagiErrorCode.cs
@@ -6,7 +6,7 @@
namespace Kagi
{
///
- ///
+ /// Enumerates the possible error codes.
///
[JsonConverter(
typeof(JsonNumberEnumConverter))]
diff --git a/source/Kagi/KagiErrorResult.cs b/source/Kagi/KagiErrorResult.cs
index 9b6582d..d388174 100644
--- a/source/Kagi/KagiErrorResult.cs
+++ b/source/Kagi/KagiErrorResult.cs
@@ -8,13 +8,13 @@
namespace Kagi
{
///
- ///
+ /// Represents the result of an errored operation.
///
public class KagiErrorResult :
KagiResult
{
///
- ///
+ /// The collection of that occurred, if any.
///
[JsonPropertyName(
"error")]
diff --git a/source/Kagi/KagiException.cs b/source/Kagi/KagiException.cs
index 49ac94a..8187317 100644
--- a/source/Kagi/KagiException.cs
+++ b/source/Kagi/KagiException.cs
@@ -5,28 +5,24 @@
namespace Kagi
{
///
- ///
+ /// Represents an exception that wraps zero or more
+ /// for a given operation.
///
public class KagiException :
Exception
{
///
- ///
+ /// The collection of for the exception.
///
public ImmutableArray Errors { get; init; }
- ///
- ///
- ///
+ ///
public KagiException() :
this(
default)
{ }
- ///
- ///
- ///
- ///
+ ///
public KagiException(
string message) :
this(
@@ -35,10 +31,11 @@ public KagiException(
{ }
///
- ///
+ /// Initializes a new instance of the
+ /// class with a specified error message and collection of .
///
- ///
- ///
+ /// The message that describes the error.
+ /// A collection of for the exception.
public KagiException(
string message,
ImmutableArray errors) :
@@ -49,11 +46,13 @@ public KagiException(
{ }
///
- ///
+ /// Initializes a new instance of the
+ /// class with a specified error message, collection of ,
+ /// and a reference to the inner exception that is the cause of this exception.
///
- ///
- ///
- ///
+ /// The message that describes the error.
+ /// A collection of for the exception.
+ /// The inner exception that is the cause of this exception.
public KagiException(
string message,
ImmutableArray errors,
diff --git a/source/Kagi/KagiRecordSearchData.cs b/source/Kagi/KagiRecordSearchData.cs
index 96903da..3c0f8e3 100644
--- a/source/Kagi/KagiRecordSearchData.cs
+++ b/source/Kagi/KagiRecordSearchData.cs
@@ -5,42 +5,40 @@
namespace Kagi
{
- ///
- ///
- ///
+ ///
public class KagiRecordSearchData :
KagiSearchData
{
///
- ///
+ /// The URL for the search record.
///
[JsonPropertyName(
"url")]
public Uri Url { get; init; }
///
- ///
+ /// The title for the search record.
///
[JsonPropertyName(
"title")]
public string Title { get; init; }
///
- ///
+ /// The snippet for the search record, if any.
///
[JsonPropertyName(
"snippet")]
public string Snippet { get; init; }
///
- ///
+ /// The publication date for the search record, if any.
///
[JsonPropertyName(
"published")]
public DateTime? PublicationDate { get; init; }
///
- ///
+ /// The image associated with the search record, if any.
///
[JsonPropertyName(
"thumbnail")]
diff --git a/source/Kagi/KagiRecordSearchDataThumbnail.cs b/source/Kagi/KagiRecordSearchDataThumbnail.cs
index 6d3ac74..358e622 100644
--- a/source/Kagi/KagiRecordSearchDataThumbnail.cs
+++ b/source/Kagi/KagiRecordSearchDataThumbnail.cs
@@ -6,7 +6,7 @@
namespace Kagi
{
///
- ///
+ /// Represents an image associated with a search record.
///
public class KagiRecordSearchDataThumbnail
{
@@ -19,8 +19,12 @@ public class KagiRecordSearchDataThumbnail
private string UrlOrProxyPathFragment { get; init; }
///
- ///
+ /// The image URL.
///
+ ///
+ /// Proxied image URLs are automatically fixed-up using
+ /// .
+ ///
[JsonIgnore]
public Uri Url =>
KagiUrlHelper.IsImageProxyPathFragment(
@@ -31,14 +35,14 @@ public class KagiRecordSearchDataThumbnail
UrlOrProxyPathFragment);
///
- ///
+ /// The width of the image, if any.
///
[JsonPropertyName(
"width")]
public int? Width { get; init; }
///
- ///
+ /// The height of the image, if any.
///
[JsonPropertyName(
"height")]
diff --git a/source/Kagi/KagiRelatedQuerySearchData.cs b/source/Kagi/KagiRelatedQuerySearchData.cs
index 34ab97e..a2c1312 100644
--- a/source/Kagi/KagiRelatedQuerySearchData.cs
+++ b/source/Kagi/KagiRelatedQuerySearchData.cs
@@ -7,14 +7,12 @@
namespace Kagi
{
- ///
- ///
- ///
+ ///
public class KagiRelatedQuerySearchData :
KagiSearchData
{
///
- ///
+ /// A collection of related search queries.
///
[JsonPropertyName(
"list")]
diff --git a/source/Kagi/KagiResult.cs b/source/Kagi/KagiResult.cs
index c5c2207..ab5a34f 100644
--- a/source/Kagi/KagiResult.cs
+++ b/source/Kagi/KagiResult.cs
@@ -6,12 +6,12 @@
namespace Kagi
{
///
- ///
+ /// Represents the result of an operation.
///
public class KagiResult
{
///
- ///
+ /// The request metadata for the result.
///
[JsonPropertyName(
"meta")]
diff --git a/source/Kagi/KagiResultMetadata.cs b/source/Kagi/KagiResultMetadata.cs
index 739fe9f..0c541db 100644
--- a/source/Kagi/KagiResultMetadata.cs
+++ b/source/Kagi/KagiResultMetadata.cs
@@ -6,33 +6,33 @@
namespace Kagi
{
///
- ///
+ /// Represents the result metadata for an operation.
///
public class KagiResultMetadata
{
///
- ///
+ /// The request ID.
///
[JsonPropertyName(
"id")]
public string RequestId { get; init; }
///
- ///
+ /// The name of the server node that serviced the request.
///
[JsonPropertyName(
"node")]
public string NodeName { get; init; }
///
- ///
+ /// The duration the server took to service the request, in milliseconds.
///
[JsonPropertyName(
"ms")]
public int DurationInMilliseconds { get; init; }
///
- ///
+ /// The remaining API balance after the request was serviced, in U.S. dollars.
///
[JsonPropertyName(
"api_balance")]
diff --git a/source/Kagi/KagiSearchData.cs b/source/Kagi/KagiSearchData.cs
index 6687d00..c65d31c 100644
--- a/source/Kagi/KagiSearchData.cs
+++ b/source/Kagi/KagiSearchData.cs
@@ -6,8 +6,14 @@
namespace Kagi
{
///
- ///
+ /// Represents the response data for a
+ /// .
///
+ ///
+ /// Response data is polymorphic and should be either
+ /// or
+ /// .
+ ///
[JsonPolymorphic(
TypeDiscriminatorPropertyName = "t")]
[JsonDerivedType(
@@ -19,7 +25,7 @@ namespace Kagi
public class KagiSearchData
{
///
- ///
+ /// The type for the search output.
///
[JsonPropertyName(
"t")]
diff --git a/source/Kagi/KagiSearchDataType.cs b/source/Kagi/KagiSearchDataType.cs
index 92162ca..a874352 100644
--- a/source/Kagi/KagiSearchDataType.cs
+++ b/source/Kagi/KagiSearchDataType.cs
@@ -6,19 +6,20 @@
namespace Kagi
{
///
- ///
+ /// Enumerates the types of response data for a
+ /// .
///
[JsonConverter(
typeof(JsonNumberEnumConverter))]
public enum KagiSearchDataType
{
///
- ///
+ /// A search result.
///
Record = 0,
///
- ///
+ /// A collection of related search queries.
///
RelatedQuery = 1,
}
diff --git a/source/Kagi/KagiSearchResult.cs b/source/Kagi/KagiSearchResult.cs
index af42c27..9d2c067 100644
--- a/source/Kagi/KagiSearchResult.cs
+++ b/source/Kagi/KagiSearchResult.cs
@@ -8,13 +8,13 @@
namespace Kagi
{
///
- ///
+ /// Represents the result of a search operation.
///
public class KagiSearchResult :
KagiResult
{
///
- ///
+ /// The response data for the result.
///
[JsonPropertyName(
"data")]
diff --git a/source/Kagi/KagiSummarizeData.cs b/source/Kagi/KagiSummarizeData.cs
index 85cd563..23664b8 100644
--- a/source/Kagi/KagiSummarizeData.cs
+++ b/source/Kagi/KagiSummarizeData.cs
@@ -6,19 +6,20 @@
namespace Kagi
{
///
- ///
+ /// Represents the response data for a
+ /// .
///
public class KagiSummarizeData
{
///
- ///
+ /// The summarize output.
///
[JsonPropertyName(
"output")]
public string Output { get; init; }
///
- ///
+ /// The number of tokens processed to produce the summarize output.
///
[JsonPropertyName(
"tokens")]
diff --git a/source/Kagi/KagiSummarizeOptions.cs b/source/Kagi/KagiSummarizeOptions.cs
index 4cf27b7..e9e7b22 100644
--- a/source/Kagi/KagiSummarizeOptions.cs
+++ b/source/Kagi/KagiSummarizeOptions.cs
@@ -6,47 +6,59 @@
namespace Kagi
{
///
- ///
+ /// Represents the options for a summarize operation.
///
public class KagiSummarizeOptions
{
///
- ///
+ /// The URL of the document to summarize.
///
+ ///
+ /// Exclusive with .
+ ///
[JsonPropertyName(
"url")]
public Uri Url { get; init; }
///
- ///
+ /// The text to summarize.
///
+ ///
+ /// Exclusive with .
+ ///
[JsonPropertyName(
"text")]
public string Text { get; init; }
///
- ///
+ /// The to use.
///
[JsonPropertyName(
"engine")]
public KagiSummaryEngine Engine { get; init; }
///
- ///
+ /// The to output.
///
[JsonPropertyName(
"summary_type")]
public KagiSummaryKind Kind { get; init; }
///
- ///
+ /// The to output.
///
+ ///
+ /// If no language is specified, the language of the document/text provided
+ /// is allowed to influence the summarizer's output. Specifying a language
+ /// will add an explicit translation step, to translate the summary to the
+ /// desired language.
+ ///
[JsonPropertyName(
"target_language")]
public KagiSummaryLanguage OutputLanguage { get; init; }
///
- ///
+ /// Whether to allow cached requests and responses.
///
[JsonPropertyName(
"cache")]
diff --git a/source/Kagi/KagiSummarizeResult.cs b/source/Kagi/KagiSummarizeResult.cs
index d57e229..f412c9b 100644
--- a/source/Kagi/KagiSummarizeResult.cs
+++ b/source/Kagi/KagiSummarizeResult.cs
@@ -6,13 +6,13 @@
namespace Kagi
{
///
- ///
+ /// Represents the result of a summarize operation.
///
public class KagiSummarizeResult :
KagiResult
{
///
- ///
+ /// The response data for the result.
///
[JsonPropertyName(
"data")]
diff --git a/source/Kagi/KagiSummaryEngine.cs b/source/Kagi/KagiSummaryEngine.cs
index 7ab71e2..f45ffc9 100644
--- a/source/Kagi/KagiSummaryEngine.cs
+++ b/source/Kagi/KagiSummaryEngine.cs
@@ -11,28 +11,28 @@
namespace Kagi
{
///
- ///
+ /// Enumerates the provided summarization engines.
///
[JsonConverter(
typeof(JsonEnumMemberEnumConverter))]
public enum KagiSummaryEngine
{
///
- ///
+ /// Provides a friendly, descriptive, fast summary.
///
[EnumMember(
Value = "cecil")]
Cecil,
///
- ///
+ /// Provides a formal, technical, analytical summary.
///
[EnumMember(
Value = "agnes")]
Agnes,
///
- ///
+ /// Provides a best-in-class summary using Kagi's enterprise-grade model.
///
[EnumMember(
Value = "muriel")]
diff --git a/source/Kagi/KagiSummaryKind.cs b/source/Kagi/KagiSummaryKind.cs
index 575f6ac..00d2091 100644
--- a/source/Kagi/KagiSummaryKind.cs
+++ b/source/Kagi/KagiSummaryKind.cs
@@ -11,21 +11,21 @@
namespace Kagi
{
///
- ///
+ /// Enumerates the different kinds of summarization.
///
[JsonConverter(
typeof(JsonEnumMemberEnumConverter))]
public enum KagiSummaryKind
{
///
- ///
+ /// A paragraph or more of summary prose.
///
[EnumMember(
Value = "summary")]
Summary,
///
- ///
+ /// A bulleted list of key points.
///
[EnumMember(
Value = "takeaway")]
diff --git a/source/Kagi/KagiSummaryLanguage.cs b/source/Kagi/KagiSummaryLanguage.cs
index 3fc6935..4f3385f 100644
--- a/source/Kagi/KagiSummaryLanguage.cs
+++ b/source/Kagi/KagiSummaryLanguage.cs
@@ -11,217 +11,217 @@
namespace Kagi
{
///
- ///
+ /// Enumerates the supported output languages for summarization.
///
[JsonConverter(
typeof(JsonEnumMemberEnumConverter))]
public enum KagiSummaryLanguage
{
///
- ///
+ /// The Bulgarian language.
///
[EnumMember(
Value = "BG")]
Bulgarian,
///
- ///
+ /// The Czech language.
///
[EnumMember(
Value = "CS")]
Czech,
///
- ///
+ /// The Danish language.
///
[EnumMember(
Value = "DA")]
Danish,
///
- ///
+ /// The German language.
///
[EnumMember(
Value = "DE")]
German,
///
- ///
+ /// The Greek language.
///
[EnumMember(
Value = "EL")]
Greek,
///
- ///
+ /// The English language.
///
[EnumMember(
Value = "EN")]
English,
///
- ///
+ /// The Spanish language.
///
[EnumMember(
Value = "ES")]
Spanish,
///
- ///
+ /// The Estonian language.
///
[EnumMember(
Value = "ET")]
Estonian,
///
- ///
+ /// The Finnish language.
///
[EnumMember(
Value = "FI")]
Finnish,
///
- ///
+ /// The French language.
///
[EnumMember(
Value = "FR")]
French,
///
- ///
+ /// The Hungarian language.
///
[EnumMember(
Value = "HU")]
Hungarian,
///
- ///
+ /// The Indonesian language.
///
[EnumMember(
Value = "ID")]
Indonesian,
///
- ///
+ /// The Italian language.
///
[EnumMember(
Value = "IT")]
Italian,
///
- ///
+ /// The Japanese language.
///
[EnumMember(
Value = "JA")]
Japanese,
///
- ///
+ /// The Korean language.
///
[EnumMember(
Value = "KO")]
Korean,
///
- ///
+ /// The Lithuanian language.
///
[EnumMember(
Value = "LT")]
Lithuanian,
///
- ///
+ /// The Latvian language.
///
[EnumMember(
Value = "LV")]
Latvian,
///
- ///
+ /// The Norwegian language.
///
[EnumMember(
Value = "NB")]
Norwegian,
///
- ///
+ /// The Dutch language.
///
[EnumMember(
Value = "NL")]
Dutch,
///
- ///
+ /// The Polish language.
///
[EnumMember(
Value = "PL")]
Polish,
///
- ///
+ /// The Portuguese language.
///
[EnumMember(
Value = "PT")]
Portuguese,
///
- ///
+ /// The Romanian language.
///
[EnumMember(
Value = "RO")]
Romanian,
///
- ///
+ /// The Russian language.
///
[EnumMember(
Value = "RU")]
Russian,
///
- ///
+ /// The Slovak language.
///
[EnumMember(
Value = "SK")]
Slovak,
///
- ///
+ /// The Slovenian language.
///
[EnumMember(
Value = "SL")]
Slovenian,
///
- ///
+ /// The Swedish language.
///
[EnumMember(
Value = "SV")]
Swedish,
///
- ///
+ /// The Turkish language.
///
[EnumMember(
Value = "TR")]
Turkish,
///
- ///
+ /// The Ukrainian language.
///
[EnumMember(
Value = "UK")]
Ukrainian,
///
- ///
+ /// The Chinese (simplified) language.
///
[EnumMember(
Value = "ZH")]
ChineseSimplified,
///
- ///
+ /// The Chinese (traditional) language.
///
[EnumMember(
Value = "ZH-HANT")]
diff --git a/source/Kagi/KagiUrlHelper.cs b/source/Kagi/KagiUrlHelper.cs
index da108a5..90cbe55 100644
--- a/source/Kagi/KagiUrlHelper.cs
+++ b/source/Kagi/KagiUrlHelper.cs
@@ -3,33 +3,39 @@
namespace Kagi
{
///
- ///
+ /// Provides -related helper functionality.
///
public static class KagiUrlHelper
{
///
- ///
+ /// The prefix that proxied image URL path fragments start with.
///
private const string ImageProxyPathFragment =
"/proxy";
///
- ///
+ /// The proxy image base URL i.e. what a proxied image URL
+ /// path fragment requires to be a complete URL.
///
private const string ImageProxyBaseUrlValue =
"https://kagi.com/";
///
- ///
+ /// Gets the proxy image base URL i.e. what a proxied image URL
+ /// path fragment requires to be a complete URL.
///
public static Uri ImageProxyBaseUrl { get; } =
new Uri(ImageProxyBaseUrlValue);
///
- ///
+ /// Returns whether the specified path fragment is an image proxy URL path fragment.
///
- ///
+ /// The path fragment specified.
///
+ ///
+ /// Used internally when fixing-up .
+ /// You will probably have no use for this method.
+ ///
public static bool IsImageProxyPathFragment(
string value)
{
@@ -44,11 +50,17 @@ public static bool IsImageProxyPathFragment(
}
///
- ///
+ /// Returns a complete image proxy URL for the specified image proxy URL path fragment.
///
- ///
+ /// The image proxy URL path fragment specified.
///
- ///
+ ///
+ /// Thrown when a image proxy URL cannot be created.
+ ///
+ ///
+ /// Used internally when fixing-up .
+ /// You will probably have no use for this method.
+ ///
public static Uri ToImageProxyUrl(
string value)
{