diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiService.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiService.java index 7155074f..a65e96af 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiService.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiService.java @@ -6,10 +6,18 @@ import javax.annotation.Nullable; +/** + * Makes a Gemini service available to the Semantic Kernel. + */ public class GeminiService implements AIService { private final VertexAI client; private final String modelId; + /** + * Creates a new Gemini service. + * @param client The VertexAI client + * @param modelId The Gemini model ID + */ protected GeminiService(VertexAI client, String modelId) { this.client = client; this.modelId = modelId; @@ -27,6 +35,10 @@ public String getServiceId() { return null; } + /** + * Gets the VertexAI client. + * @return The VertexAI client + */ protected VertexAI getClient() { return client; } diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiServiceBuilder.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiServiceBuilder.java index c5d3f658..3312299c 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiServiceBuilder.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/GeminiServiceBuilder.java @@ -7,6 +7,8 @@ /** * Builder for a Gemini service. + * @param The type of the service + * @param The type of the builder */ public abstract class GeminiServiceBuilder> implements SemanticKernelBuilder { diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiChatCompletion.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiChatCompletion.java index 8ba16bc4..e226b4c6 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiChatCompletion.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiChatCompletion.java @@ -50,10 +50,18 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; +/** + * A chat completion service that uses the Gemini model to generate chat completions. + */ public class GeminiChatCompletion extends GeminiService implements ChatCompletionService { private static final Logger LOGGER = LoggerFactory.getLogger(GeminiChatCompletion.class); + /** + * Constructor for {@link GeminiChatCompletion}. + * @param client The VertexAI client + * @param modelId The model ID + */ public GeminiChatCompletion(VertexAI client, String modelId) { super(client, modelId); } @@ -391,6 +399,13 @@ private Tool getTool(@Nullable Kernel kernel, @Nullable ToolCallBehavior toolCal return toolBuilder.build(); } + /** + * Invoke the Gemini function call. + * @param kernel The semantic kernel + * @param invocationContext Additional context for the invocation + * @param geminiFunction The Gemini function call + * @return The result of the function call + */ public Mono performFunctionCall(@Nullable Kernel kernel, @Nullable InvocationContext invocationContext, GeminiFunctionCall geminiFunction) { if (kernel == null) { @@ -433,6 +448,9 @@ public Mono performFunctionCall(@Nullable Kernel kernel, .map(result -> new GeminiFunctionCall(geminiFunction.getFunctionCall(), result)); } + /** + * Builder for {@link GeminiChatCompletion}. + */ public static class Builder extends GeminiServiceBuilder { @Override diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiFunctionCall.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiFunctionCall.java index fc64c830..0a6e87d4 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiFunctionCall.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiFunctionCall.java @@ -9,6 +9,9 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; +/** + * Represents a function call in Gemini. + */ public class GeminiFunctionCall { @Nonnull private final FunctionCall functionCall; @@ -17,6 +20,11 @@ public class GeminiFunctionCall { private final String pluginName; private final String functionName; + /** + * Creates a new Gemini function call. + * @param functionCall The function call + * @param functionResult The result of the function invocation + */ @SuppressFBWarnings("EI_EXPOSE_REP2") public GeminiFunctionCall( @Nonnull FunctionCall functionCall, @@ -29,19 +37,35 @@ public GeminiFunctionCall( this.functionName = name[1]; } + /** + * Gets the plugin name. + * @return The plugin name + */ public String getPluginName() { return pluginName; } + /** + * Gets the function name. + * @return The function name + */ public String getFunctionName() { return functionName; } + /** + * Gets the function call. + * @return The function call + */ @SuppressFBWarnings("EI_EXPOSE_REP") public FunctionCall getFunctionCall() { return functionCall; } + /** + * Gets the function result. + * @return The function result + */ @Nullable public FunctionResult getFunctionResult() { return functionResult; diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiRole.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiRole.java index 74590723..03983553 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiRole.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiRole.java @@ -1,6 +1,9 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.aiservices.google.chatcompletion; +/** + * Represents the role of a message in a Gemini conversation. + */ public enum GeminiRole { /** * A user message is a message generated by the user. diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiStreamingChatMessageContent.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiStreamingChatMessageContent.java index 45aed993..e6f0d551 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiStreamingChatMessageContent.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiStreamingChatMessageContent.java @@ -27,6 +27,7 @@ public class GeminiStreamingChatMessageContent extends GeminiChatMessageConte * @param innerContent The inner content. * @param encoding The encoding. * @param metadata The metadata. + * @param id The id of the message. * @param geminiFunctionCalls The function calls. */ public GeminiStreamingChatMessageContent(AuthorRole authorRole, String content, diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiXMLPromptParser.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiXMLPromptParser.java index afde9a33..e43032dc 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiXMLPromptParser.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/chatcompletion/GeminiXMLPromptParser.java @@ -17,15 +17,26 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Parses an XML prompt for a Gemini chat. + */ public class GeminiXMLPromptParser { private static final Logger LOGGER = LoggerFactory.getLogger(GeminiXMLPromptParser.class); + /** + * Represents a parsed prompt for Gemini chat. + */ public static class GeminiParsedPrompt { private final ChatHistory chatHistory; private final List functions; + /** + * Creates a new parsed prompt. + * @param parsedChatHistory The chat history + * @param parsedFunctions The functions declarations. + */ protected GeminiParsedPrompt( ChatHistory parsedChatHistory, @Nullable List parsedFunctions) { @@ -36,10 +47,18 @@ protected GeminiParsedPrompt( this.functions = parsedFunctions; } + /** + * Gets the chat history. + * @return A copy of the chat history. + */ public ChatHistory getChatHistory() { return new ChatHistory(chatHistory.getMessages()); } + /** + * Gets the functions declarations. + * @return A copy of the functions declarations. + */ public List getFunctions() { return Collections.unmodifiableList(functions); } @@ -131,6 +150,11 @@ public ChatPromptParseVisitor reset() { } } + /** + * Create a GeminiParsedPrompt by parsing a raw prompt. + * @param rawPrompt the raw prompt to parse. + * @return The parsed prompt. + */ public static GeminiParsedPrompt parse(String rawPrompt) { ChatPromptParseVisitor visitor = ChatXMLPromptParser.parse( rawPrompt, diff --git a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/textcompletion/GeminiTextGenerationService.java b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/textcompletion/GeminiTextGenerationService.java index beec7d2c..5e555116 100644 --- a/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/textcompletion/GeminiTextGenerationService.java +++ b/aiservices/google/src/main/java/com/microsoft/semantickernel/aiservices/google/textcompletion/GeminiTextGenerationService.java @@ -28,14 +28,27 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; +/** + * A Gemini service for text generation. + * @see TextGenerationService + */ public class GeminiTextGenerationService extends GeminiService implements TextGenerationService { private static final Logger LOGGER = LoggerFactory.getLogger(GeminiTextGenerationService.class); + /** + * Creates a new Gemini text generation service. + * @param client The VertexAI client + * @param modelId The Gemini model ID + */ public GeminiTextGenerationService(VertexAI client, String modelId) { super(client, modelId); } + /** + * Creates a new builder for a Gemini text generation service. + * @return The builder + */ public static Builder builder() { return new Builder(); } @@ -121,6 +134,9 @@ private GenerativeModel getGenerativeModel( return modelBuilder.build(); } + /** + * Builder for a Gemini text generation service. + */ public static class Builder extends GeminiServiceBuilder { diff --git a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/HuggingFaceClient.java b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/HuggingFaceClient.java index 93fe64fd..4e8f9bb4 100644 --- a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/HuggingFaceClient.java +++ b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/HuggingFaceClient.java @@ -19,12 +19,21 @@ import reactor.core.publisher.Mono; import javax.annotation.Nullable; +/** + * A client for the Hugging Face API. + */ public class HuggingFaceClient { private final KeyCredential key; private final String endpoint; private final HttpClient httpClient; + /** + * Creates a new Hugging Face client. + * @param key The key credential for endpoint authentication. + * @param endpoint The endpoint for the Hugging Face API. + * @param httpClient The HTTP client to use for requests. + */ public HuggingFaceClient( KeyCredential key, String endpoint, @@ -74,6 +83,12 @@ public GeneratedTextItemList( } + /** + * Gets the text contents from the Hugging Face API. + * @param modelId The model ID. + * @param textGenerationRequest The text generation request. + * @return The generated text items. + */ public Mono> getTextContentsAsync( String modelId, TextGenerationRequest textGenerationRequest) { @@ -131,10 +146,17 @@ private Mono performRequest(String modelId, return responseBody; } + /** + * Creates a new builder for a Hugging Face client. + * @return The builder + */ public static Builder builder() { return new Builder(); } + /** + * Builder for a Hugging Face client. + */ public static class Builder { @Nullable @@ -144,6 +166,10 @@ public static class Builder { @Nullable private HttpClient httpClient = null; + /** + * Builds the Hugging Face client. + * @return The client + */ public HuggingFaceClient build() { if (httpClient == null) { httpClient = HttpClient.createDefault(); @@ -160,16 +186,31 @@ public HuggingFaceClient build() { httpClient); } + /** + * Sets the key credential for the client. + * @param key The key credential + * @return The builder + */ public Builder credential(KeyCredential key) { this.key = key; return this; } + /** + * Sets the endpoint for the client. + * @param endpoint The endpoint + * @return The builder + */ public Builder endpoint(String endpoint) { this.endpoint = endpoint; return this; } + /** + * Sets the HTTP client for the client. + * @param httpClient The HTTP client + * @return The builder + */ public Builder httpClient(HttpClient httpClient) { this.httpClient = httpClient; return this; diff --git a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/GeneratedTextItem.java b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/GeneratedTextItem.java index 6f4125c6..12ed5be6 100644 --- a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/GeneratedTextItem.java +++ b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/GeneratedTextItem.java @@ -8,6 +8,9 @@ import java.util.List; import javax.annotation.Nullable; +/** + * Represents a generated text item deserialized from a JSON response. + */ public class GeneratedTextItem { @Nullable @@ -18,6 +21,11 @@ public class GeneratedTextItem { @JsonProperty("details") private final TextGenerationDetails details; + /** + * Constructor used by Jackson to deserialize a generated text item. + * @param generatedText The generated text. + * @param details The details of the generation. + */ @JsonCreator public GeneratedTextItem( @JsonProperty("generated_text") @Nullable String generatedText, @@ -26,16 +34,27 @@ public GeneratedTextItem( this.details = details; } + /** + * Gets the generated text. + * @return The generated text. + */ @Nullable public String getGeneratedText() { return generatedText; } + /** + * Gets the details of the generation. + * @return The details of the generation. + */ @Nullable public TextGenerationDetails getDetails() { return details; } + /** + * Represents the details of a text generation deserialized from a JSON response. + */ public static class TextGenerationDetails { @Nullable @@ -57,6 +76,14 @@ public static class TextGenerationDetails { @JsonProperty("tokens") private final List tokens; + /** + * Constructor used by Jackson to deserialize text generation details. + * @param finishReason The reason the generation finished. + * @param generatedTokens The number of tokens generated. + * @param seed The seed used for generation. + * @param prefill The prefill tokens. + * @param tokens The generated tokens. + */ @JsonCreator public TextGenerationDetails( @JsonProperty("finish_reason") @Nullable String finishReason, @@ -79,31 +106,54 @@ public TextGenerationDetails( } } + /** + * Gets the reason the generation finished. + * @return The reason the generation finished. + */ @Nullable public String getFinishReason() { return finishReason; } + /** + * Gets the number of tokens generated. + * @return The number of tokens generated. + */ public int getGeneratedTokens() { return generatedTokens; } + /** + * Gets the seed used for generation. + * @return The seed used for generation. + */ @Nullable public Long getSeed() { return seed; } + /** + * Gets the prefill tokens. + * @return The prefill tokens. + */ @Nullable public List getPrefill() { return Collections.unmodifiableList(prefill); } + /** + * Gets the generated tokens. + * @return The generated tokens. + */ @Nullable public List getTokens() { return Collections.unmodifiableList(tokens); } } + /** + * Represents a prefill token deserialized from a JSON response. + */ public static class TextGenerationPrefillToken { @JsonProperty("id") @@ -116,6 +166,12 @@ public static class TextGenerationPrefillToken { @JsonProperty("logprob") private final double logProb; + /** + * Constructor used by Jackson to deserialize a prefill token. + * @param id The token ID. + * @param text The token text. + * @param logProb The log probability of the token. + */ @JsonCreator public TextGenerationPrefillToken( @JsonProperty("id") int id, @@ -126,25 +182,47 @@ public TextGenerationPrefillToken( this.logProb = logProb; } + /** + * Gets the token ID. + * @return The token ID. + */ public int getId() { return id; } + /** + * Gets the token text. + * @return The token text. + */ @Nullable public String getText() { return text; } + /** + * Gets the log probability of the token. + * @return The log probability of the token. + */ public double getLogProb() { return logProb; } } + /** + * Represents a generated token deserialized from a JSON response. + */ public static class TextGenerationToken extends TextGenerationPrefillToken { @JsonProperty("special") private final boolean special; + /** + * Constructor used by Jackson to deserialize a generated token. + * @param special Whether the token is special. + * @param id The token ID. + * @param text The token text. + * @param logProb The log probability of the token. + */ @JsonCreator public TextGenerationToken( @JsonProperty("special") boolean special, @@ -155,6 +233,10 @@ public TextGenerationToken( this.special = special; } + /** + * Gets whether the token is special. + * @return Whether the token is special. + */ public boolean isSpecial() { return special; } diff --git a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/TextGenerationRequest.java b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/TextGenerationRequest.java index fd0b6077..0e52b568 100644 --- a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/TextGenerationRequest.java +++ b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/models/TextGenerationRequest.java @@ -1,7 +1,6 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.aiservices.huggingface.models; -import com.fasterxml.jackson.annotation.JsonIgnore; import com.fasterxml.jackson.annotation.JsonInclude; import com.fasterxml.jackson.annotation.JsonInclude.Include; import com.fasterxml.jackson.annotation.JsonProperty; @@ -11,6 +10,9 @@ import java.util.Arrays; import java.util.List; +/** + * Represents a request to generate text using the Hugging Face API. + */ @JsonInclude(Include.NON_NULL) public class TextGenerationRequest { @@ -42,6 +44,13 @@ public class TextGenerationRequest { @JsonProperty("options") private final HuggingFaceTextOptions options; + /** + * Create a new instance of TextGenerationRequest. + * @param inputs The input string to generate text for. + * @param stream Enable streaming. + * @param parameters Parameters used by the model for generation. + * @param options Options used by the model for generation. + */ public TextGenerationRequest( @Nullable String inputs, boolean stream, @@ -53,6 +62,12 @@ public TextGenerationRequest( this.options = options; } + /** + * Create a new instance of TextGenerationRequest. + * @param prompt The prompt to generate text for. + * @param executionSettings The settings for executing the prompt. + * @return A new instance of TextGenerationRequest. + */ public static TextGenerationRequest fromPromptAndExecutionSettings(String prompt, HuggingFacePromptExecutionSettings executionSettings) { return new TextGenerationRequest( @@ -72,6 +87,9 @@ public static TextGenerationRequest fromPromptAndExecutionSettings(String prompt new HuggingFaceTextOptions()); } + /** + * Parameters used by the model for generation. + */ public static class HuggingFaceTextParameters { /// @@ -156,6 +174,19 @@ public static class HuggingFaceTextParameters { @JsonProperty("details") private final Boolean details; + /** + * Creator method for jackson deserialization. + * @param topK The number of top tokens considered within the sample operation to create new text. + * @param topP The tokens that are within the sample operation of text generation. + * @param temperature The temperature of the sampling operation. + * @param repetitionPenalty The repetition penalty. + * @param maxNewTokens The amount of new tokens to be generated. + * @param maxTime The amount of time in seconds that the query should take maximum. + * @param returnFullText A value indicating whether the return results will contain the original query. + * @param numReturnSequences The number of propositions to be returned. + * @param doSample A value indicating whether to use sampling. + * @param details A value indicating whether to include the details of the generation. + */ public HuggingFaceTextParameters( @JsonProperty("top_k") @Nullable Integer topK, @JsonProperty("top_p") @Nullable Double topP, @@ -179,56 +210,99 @@ public HuggingFaceTextParameters( this.details = details; } + /** + * Gets the number of top tokens considered within the sample operation to create new text. + * @return The number of top tokens considered within the sample operation to create new text. + */ @Nullable public Integer getTopK() { return topK; } + /** + * Gets the tokens that are within the sample operation of text generation. + * @return The tokens that are within the sample operation of text generation. + */ @Nullable public Double getTopP() { return topP; } + /** + * Gets the temperature of the sampling operation. + * @return The temperature of the sampling operation. + */ @Nullable public Double getTemperature() { return temperature; } + /** + * Gets the repetition penalty. + * @return The repetition penalty. + */ @Nullable public Double getRepetitionPenalty() { return repetitionPenalty; } + /** + * Gets the amount of new tokens to be generated. + * @return The amount of new tokens to be generated. + */ @Nullable public Integer getMaxNewTokens() { return maxNewTokens; } + /** + * Gets the amount of time in seconds that the query should take maximum. + * @return The amount of time in seconds that the query should take maximum. + */ @Nullable public Double getMaxTime() { return maxTime; } + /** + * Gets a value indicating whether the return results will contain the original query. + * @return A value indicating whether the return results will contain the original query. + */ public boolean isReturnFullText() { return returnFullText; } + /** + * Gets the number of propositions to be returned. + * @return The number of propositions to be returned. + */ @Nullable public Integer getNumReturnSequences() { return numReturnSequences; } + /** + * Gets a value indicating whether to use sampling. + * @return A value indicating whether to use sampling. + */ @Nullable public Boolean getDoSample() { return doSample; } + /** + * Gets a value indicating whether to include the details of the generation. + * @return A value indicating whether to include the details of the generation. + */ @Nullable public Boolean getDetails() { return details; } } + /** + * Options used by the model for generation. + */ @SuppressFBWarnings("SS_SHOULD_BE_STATIC") public static class HuggingFaceTextOptions { @@ -249,10 +323,18 @@ public static class HuggingFaceTextOptions { @JsonProperty("wait_for_model") private final boolean waitForModel = false; + /** + * Gets a value indicating whether to use the cache layer on the inference API. + * @return A value indicating whether to use the cache layer on the inference API. + */ public boolean isUseCache() { return useCache; } + /** + * Gets a value indicating whether to wait for the model if it is not ready. + * @return A value indicating whether to wait for the model if it is not ready. + */ public boolean isWaitForModel() { return waitForModel; } diff --git a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFacePromptExecutionSettings.java b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFacePromptExecutionSettings.java index be6cd2ca..adcabe7c 100644 --- a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFacePromptExecutionSettings.java +++ b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFacePromptExecutionSettings.java @@ -8,6 +8,9 @@ import java.util.Objects; import javax.annotation.Nullable; +/** + * Represents the settings for executing a prompt with the Hugging Face API. + */ public class HuggingFacePromptExecutionSettings extends PromptExecutionSettings { @Nullable @@ -25,6 +28,11 @@ public class HuggingFacePromptExecutionSettings extends PromptExecutionSettings @Nullable private final Long seed; + /** + * Create a new instance of HuggingFacePromptExecutionSettings. + * + * @param copy The PromptExecutionSettings to copy. + */ public HuggingFacePromptExecutionSettings(PromptExecutionSettings copy) { super( copy.getServiceId(), @@ -65,6 +73,13 @@ public HuggingFacePromptExecutionSettings(PromptExecutionSettings copy) { * @param stopSequences The stop sequences to use for prompt execution. * @param tokenSelectionBiases The token selection biases to use for prompt execution. * @param responseFormat The response format to use for prompt execution + * @param topK The topK setting for prompt execution. + * @param repetitionPenalty The repetition penalty setting for prompt execution. + * @param maxTime The max time setting for prompt execution. + * @param details The details setting for prompt execution. + * @param logProbs The logprobs setting for prompt execution. + * @param topLogProbs The top log probs setting for prompt execution. + * @param seed The seed setting for prompt execution */ public HuggingFacePromptExecutionSettings( String serviceId, @@ -100,6 +115,14 @@ public HuggingFacePromptExecutionSettings( this.seed = seed; } + /** + * Create a new instance of PromptExecutionSettings from a PromptExecutionSettings. + * This method handles the whether the PromptExecutionSettings is already a + * HuggingFacePromptExecutionSettings or a new instance needs to be created + * from the provided PromptExecutionSettings. + * @param promptExecutionSettings The PromptExecutionSettings to copy. + * @return The PromptExecutionSettings mapped to a HuggingFacePromptExecutionSettings. + */ public static HuggingFacePromptExecutionSettings fromExecutionSettings( PromptExecutionSettings promptExecutionSettings) { if (promptExecutionSettings instanceof HuggingFacePromptExecutionSettings) { @@ -131,36 +154,64 @@ public static HuggingFacePromptExecutionSettings fromExecutionSettings( null); } + /** + * Gets the topK setting for prompt execution. + * @return The topK setting for prompt execution + */ @Nullable public Integer getTopK() { return topK; } + /** + * Gets the repetition penalty setting for prompt execution. + * @return The repetition penalty setting for prompt execution + */ @Nullable public Double getRepetitionPenalty() { return repetitionPenalty; } + /** + * Gets the max time setting for prompt execution. + * @return The max time setting for prompt execution + */ @Nullable public Double getMaxTime() { return maxTime; } + /** + * Gets the details setting for prompt execution. + * @return The details setting for prompt execution + */ @Nullable public Boolean getDetails() { return details; } + /** + * Gets the logprobs setting for prompt execution. + * @return The logprobs setting for prompt execution + */ @Nullable public Boolean getLogprobs() { return logProbs; } + /** + * Gets the top log probs setting for prompt execution. + * @return The top log probs setting for prompt execution + */ @Nullable public Integer getTopLogProbs() { return topLogProbs; } + /** + * Gets the seed setting for prompt execution. + * @return The seed setting for prompt execution + */ @Nullable public Long getSeed() { return seed; diff --git a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFaceTextGenerationService.java b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFaceTextGenerationService.java index 0f5260d3..a08b4232 100644 --- a/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFaceTextGenerationService.java +++ b/aiservices/huggingface/src/main/java/com/microsoft/semantickernel/aiservices/huggingface/services/HuggingFaceTextGenerationService.java @@ -19,12 +19,21 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; +/** + * A service that generates text using the Hugging Face API. + */ public class HuggingFaceTextGenerationService implements TextGenerationService { private final String modelId; private final String serviceId; private final HuggingFaceClient client; + /** + * Create a new instance of HuggingFaceTextGenerationService. + * @param modelId The model ID. + * @param serviceId The service ID. + * @param client The Hugging Face client. + */ public HuggingFaceTextGenerationService( String modelId, String serviceId, @@ -34,6 +43,13 @@ public HuggingFaceTextGenerationService( this.client = client; } + /** + * Get the response to a prompt. + * @param prompt The prompt. + * @param huggingFacePromptExecutionSettings The settings for executing the prompt. + * @param kernel The semantic kernel. + * @return The response to the prompt. + */ public Mono> getTextContentsAsync( String prompt, @Nullable HuggingFacePromptExecutionSettings huggingFacePromptExecutionSettings, @@ -117,10 +133,17 @@ public String getServiceId() { return serviceId; } + /** + * Create a new builder for HuggingFaceTextGenerationService. + * @return The builder. + */ public static Builder builder() { return new Builder(); } + /** + * A builder for HuggingFaceTextGenerationService. + */ public static class Builder { @Nullable @@ -152,11 +175,20 @@ public Builder withServiceId(String serviceId) { return this; } + /** + * Sets the HuggingFaceClient for the service + * @param client The HuggingFaceClient + * @return The builder + */ public Builder withHuggingFaceClient(HuggingFaceClient client) { this.client = client; return this; } + /** + * Builds the HuggingFaceTextGenerationService + * @return The HuggingFaceTextGenerationService + */ public HuggingFaceTextGenerationService build() { if (this.modelId == null) { diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/OpenAiService.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/OpenAiService.java index 4a7a196b..0edee476 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/OpenAiService.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/OpenAiService.java @@ -6,6 +6,7 @@ /** * Provides OpenAI service. + * @param the client type */ public abstract class OpenAiService implements AIService { @@ -38,10 +39,18 @@ public String getServiceId() { return serviceId; } + /** + * Gets the client. + * @return the client + */ protected Client getClient() { return client; } + /** + * Gets the deployment name. + * @return the deployment name + */ public String getDeploymentName() { return deploymentName; } diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiAudioToTextService.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiAudioToTextService.java index 631f2cac..7a126f6d 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiAudioToTextService.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiAudioToTextService.java @@ -28,6 +28,7 @@ public class OpenAiAudioToTextService extends OpenAiService * * @param client OpenAI client. * @param modelId The model ID. + * @param deploymentName The deployment name. */ public OpenAiAudioToTextService( OpenAIAsyncClient client, diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiTextToAudioService.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiTextToAudioService.java index c698fab3..dc748af7 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiTextToAudioService.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiTextToAudioService.java @@ -27,6 +27,7 @@ public class OpenAiTextToAudioService extends OpenAiService * * @param client OpenAI client. * @param modelId The model ID. + * @param deploymentName The deployment name. */ public OpenAiTextToAudioService( OpenAIAsyncClient client, @@ -79,7 +80,6 @@ public static Builder builder() { /** * Represents a builder for OpenAi text to audio service. */ - public static class Builder extends TextToAudioService.Builder { /** diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/OpenAIStreamingChatMessageContent.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/OpenAIStreamingChatMessageContent.java index 21162c8f..c919f5c6 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/OpenAIStreamingChatMessageContent.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/OpenAIStreamingChatMessageContent.java @@ -8,11 +8,28 @@ import java.util.List; import javax.annotation.Nullable; +/** + * Represents the content of a chat message. + * + * @param The type of the inner content. + */ public class OpenAIStreamingChatMessageContent extends OpenAIChatMessageContent implements StreamingChatContent { private final String id; + /** + * Creates a new instance of the {@link OpenAIChatMessageContent} class. + * + * @param id The id of the message. + * @param authorRole The author role that generated the content. + * @param content The content. + * @param modelId The model id. + * @param innerContent The inner content. + * @param encoding The encoding. + * @param metadata The metadata. + * @param toolCall The tool call. + */ public OpenAIStreamingChatMessageContent( String id, AuthorRole authorRole, diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/ChatCompletionsJsonSchemaResponseFormat.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/ChatCompletionsJsonSchemaResponseFormat.java index 96fa2526..f5a3b1c4 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/ChatCompletionsJsonSchemaResponseFormat.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/ChatCompletionsJsonSchemaResponseFormat.java @@ -6,19 +6,29 @@ import com.microsoft.semantickernel.orchestration.responseformat.JsonResponseSchema; import java.io.IOException; +/** + * Represents a response format for chat completions that uses a JSON schema. + */ public class ChatCompletionsJsonSchemaResponseFormat extends ChatCompletionsResponseFormat { private final JsonResponseSchema schema; private String type = "json_schema"; + /** + * Creates a new instance of the {@link ChatCompletionsJsonSchemaResponseFormat} class. + * + * @param schema The JSON schema. + */ public ChatCompletionsJsonSchemaResponseFormat(JsonResponseSchema schema) { this.schema = schema; } + @Override public String getType() { return this.type; } + @Override public JsonWriter toJson(JsonWriter jsonWriter) throws IOException { jsonWriter.writeStartObject(); jsonWriter.writeStringField("type", this.type); diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/JacksonResponseFormatGenerator.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/JacksonResponseFormatGenerator.java index 93ea5b5f..97060cab 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/JacksonResponseFormatGenerator.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/responseformat/JacksonResponseFormatGenerator.java @@ -12,10 +12,16 @@ import com.github.victools.jsonschema.module.jackson.JacksonModule; import com.microsoft.semantickernel.orchestration.responseformat.ResponseSchemaGenerator; +/** + * Represents a response format generator that uses Jackson. + */ public class JacksonResponseFormatGenerator implements ResponseSchemaGenerator { private final SchemaGenerator generator; + /** + * Creates a new instance of the {@link JacksonResponseFormatGenerator} class. + */ public JacksonResponseFormatGenerator() { JacksonModule module = new JacksonModule(); SchemaGeneratorConfigBuilder builder = new SchemaGeneratorConfigBuilder( @@ -31,6 +37,11 @@ public JacksonResponseFormatGenerator() { generator = new SchemaGenerator(builder.build()); } + /** + * Creates a new instance of the {@link JacksonResponseFormatGenerator} class. + * + * @param generator The schema generator. + */ public JacksonResponseFormatGenerator(SchemaGenerator generator) { this.generator = generator; } diff --git a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/textembedding/OpenAITextEmbeddingGenerationService.java b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/textembedding/OpenAITextEmbeddingGenerationService.java index f8ccaeb0..89b52831 100644 --- a/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/textembedding/OpenAITextEmbeddingGenerationService.java +++ b/aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/textembedding/OpenAITextEmbeddingGenerationService.java @@ -29,7 +29,15 @@ public class OpenAITextEmbeddingGenerationService extends OpenAiService3.2.5 3.9.3 2.16.2 + 3.7.0 5.10.0 0.9.1 6.55.0 diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/Kernel.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/Kernel.java index 4ab1553f..57e46165 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/Kernel.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/Kernel.java @@ -163,6 +163,15 @@ public FunctionInvocation invokePromptAsync(@Nonnull String prompt) { return invokeAsync(KernelFunction.createFromPrompt(prompt).build()); } + /** + * Invokes a Prompt. + * + * @param The return type of the prompt. + * @param prompt The prompt to invoke. + * @param arguments The arguments to pass to the prompt. + * @return The result of the prompt invocation. + * @see KernelFunction#invokeAsync(Kernel) + */ public FunctionInvocation invokePromptAsync(@Nonnull String prompt, @Nonnull KernelFunctionArguments arguments) { KernelFunction function = KernelFunction.createFromPrompt(prompt).build(); @@ -171,6 +180,17 @@ public FunctionInvocation invokePromptAsync(@Nonnull String prompt, .withArguments(arguments); } + /** + * Invokes a Prompt. + * + * @param The return type of the prompt. + * @param prompt The prompt to invoke. + * @param arguments The arguments to pass to the prompt. + * @param invocationContext Additional context to used when invoking the prompt. + * @return The result of the prompt invocation. + * @see KernelFunction#invokeAsync(Kernel) + */ + public FunctionInvocation invokePromptAsync(@Nonnull String prompt, @Nonnull KernelFunctionArguments arguments, @Nonnull InvocationContext invocationContext) { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypeConverter.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypeConverter.java index ac1b9dd2..22d53ec0 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypeConverter.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypeConverter.java @@ -25,8 +25,19 @@ public class ContextVariableTypeConverter { private static final Logger LOGGER = LoggerFactory.getLogger( ContextVariableTypeConverter.class); + /** + * A function to convert ContextVariable to a prompt string. + * @param the type of ContextVariable to convert + */ public interface ToPromptStringFunction { + /** + * Convert the type to a prompt string. + * + * @param types the context variable types + * @param t the type to convert + * @return the prompt string + */ String toPromptString(ContextVariableTypes types, T t); } @@ -116,6 +127,7 @@ public ContextVariableTypeConverter( * Use this converter to convert the object to the type of the context variable. * * @param the type to convert to + * @param types the context variable types * @param t the object to convert * @param clazz the class of the type to convert to * @return the converted object @@ -129,10 +141,11 @@ public U toObject(ContextVariableTypes types, @Nullable Object t, Class c /** * Use this converter to convert the object to the type of the context variable. * - * @param the type to convert to + * @param types the context variable types * @param t the object to convert * @param clazz the class of the type to convert to * @param logWarnings whether to log warnings + * @param the type to convert to * @return the converted object */ @Nullable @@ -314,6 +327,7 @@ public static Builder builder(Class clazz) { /** * A builder for a context variable type converter. + * @param the type of the context variable */ public static class Builder { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypes.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypes.java index 76ed87fa..dd12bb70 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypes.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/ContextVariableTypes.java @@ -94,6 +94,14 @@ public ContextVariableTypes() { variableTypes = new HashMap<>(); } + /** + * Get the globally available collectors, which is the + * default collection of context variable types and those that + * have been added with + * {@link #addGlobalConverter(ContextVariableTypeConverter)}. + * + * @return The collection of globally available converters. + */ public static ContextVariableTypes getGlobalTypes() { return new ContextVariableTypes(DEFAULT_TYPES); } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/CollectionVariableContextVariableTypeConverter.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/CollectionVariableContextVariableTypeConverter.java index 5a5c14cf..d7bf72e0 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/CollectionVariableContextVariableTypeConverter.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/CollectionVariableContextVariableTypeConverter.java @@ -15,12 +15,15 @@ * A {@link ContextVariableTypeConverter} for {@code java.util.Collection} variables. Use * {@code ContextVariableTypes.getGlobalVariableTypeForClass(String.class)} to get an instance of * this class. - * * @see ContextVariableTypes#getGlobalVariableTypeForClass(Class) */ public class CollectionVariableContextVariableTypeConverter extends ContextVariableTypeConverter { + /** + * Creates a new instance of the {@link CollectionVariableContextVariableTypeConverter} class. + * @param delimiter The delimiter to use joining elements of the collection. + */ @SuppressFBWarnings("CT_CONSTRUCTOR_THROW") public CollectionVariableContextVariableTypeConverter(String delimiter) { super( @@ -35,12 +38,16 @@ public CollectionVariableContextVariableTypeConverter(String delimiter) { /** * Creates a new instance of the {@link CollectionVariableContextVariableTypeConverter} class. */ - @SuppressFBWarnings("CT_CONSTRUCTOR_THROW") public CollectionVariableContextVariableTypeConverter() { this(","); } + /** + * Gets a function that converts a collection to a string. + * @param delimiter The delimiter to use joining elements of the collection. + * @return A function that converts a collection to a string. + */ @SuppressWarnings("NullAway") public static ToPromptStringFunction getString(String delimiter) { return (types, collection) -> { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/PrimitiveVariableContextVariableTypeConverter.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/PrimitiveVariableContextVariableTypeConverter.java index d41b3a33..310ceab0 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/PrimitiveVariableContextVariableTypeConverter.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/PrimitiveVariableContextVariableTypeConverter.java @@ -25,6 +25,7 @@ public class PrimitiveVariableContextVariableTypeConverter extends * @param clazz the class * @param fromPromptString the function to convert from a prompt string * @param fromObject the function to convert from an object to primitive + * @param toPromptString the function to convert to a prompt string */ public PrimitiveVariableContextVariableTypeConverter( Class clazz, diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/StringVariableContextVariableTypeConverter.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/StringVariableContextVariableTypeConverter.java index 4a431e60..3e303bff 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/StringVariableContextVariableTypeConverter.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/StringVariableContextVariableTypeConverter.java @@ -29,6 +29,14 @@ public StringVariableContextVariableTypeConverter() { s -> s); } + /** + * Converts the specified object to a string. + * Has special handling for {@link ContextVariable} objects and + * for objects that look like an object reference + * @param s the object to convert + * @return the string representation of the object, or {@code null} + * if the object cannot be converted to a string or is an object reference. + */ @Nullable public static String convertToString(@Nullable Object s) { String converted = convert(s, String.class); diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/TextContentVariableContextVariableTypeConverter.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/TextContentVariableContextVariableTypeConverter.java index e43ed0f0..920ac4a1 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/TextContentVariableContextVariableTypeConverter.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/contextvariables/converters/TextContentVariableContextVariableTypeConverter.java @@ -29,6 +29,12 @@ public TextContentVariableContextVariableTypeConverter() { }); } + /** + * Escapes the XML string value. + * @param value The value containing the content to escape. + * @return The escaped XML string value. + * @see ContextVariableTypeConverter#escapeXmlString(String) + */ @Nullable public static String escapeXmlStringValue(@Nullable TextContent value) { if (value == null) { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKCheckedException.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKCheckedException.java index 7b8364ea..07390692 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKCheckedException.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKCheckedException.java @@ -37,32 +37,40 @@ public SKCheckedException(@Nullable String message, @Nullable Throwable cause) { super(message, cause); } - public SKCheckedException(Throwable e) { - super(e); + /** + * Initializes a new instance of the {@code SKCheckedException} class with its + * message set to {@code null} and the cause set to {@code e}. + * + * @param cause The exception that is the cause of the current exception. + */ + public SKCheckedException(Throwable cause) { + super(cause); } /** - * Forms a checked exception, if the exception is already an SK exception, it will be unwrapped + * Forms a checked exception, if the exception is already an SK exception, it + * will be unwrapped * and the cause extracted. * * @param message The message to be displayed - * @param e The exception to be thrown + * @param cause The exception that is the cause of the current exception. * @return A checked exception */ public static SKCheckedException build( String message, - @Nullable Exception e) { + @Nullable Exception cause) { - if (e == null) { + if (cause == null) { return new SKCheckedException(message); } - Throwable cause = e.getCause(); + Throwable wrappedCause = cause.getCause(); - if ((e instanceof SKCheckedException || e instanceof SKException) && cause != null) { - return new SKCheckedException(message, cause); + if ((cause instanceof SKCheckedException || cause instanceof SKException) + && wrappedCause != null) { + return new SKCheckedException(message, wrappedCause); } else { - return new SKCheckedException(message, e); + return new SKCheckedException(message, cause); } } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKException.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKException.java index 99aef056..3f14a2f5 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKException.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/SKException.java @@ -37,8 +37,14 @@ public SKException(@Nullable String message, @Nullable Throwable cause) { super(message, cause); } - public SKException(Throwable e) { - super(e); + /** + * Initializes a new instance of the {@code SKException} class with its + * message set to {@code null} and the cause set to {@code e}. + * + * @param cause The exception that is the cause of the current exception. + */ + public SKException(Throwable cause) { + super(cause); } /** @@ -46,23 +52,24 @@ public SKException(Throwable e) { * unwrapped and the cause extracted. * * @param message The message to be displayed - * @param e The exception to be thrown + * @param cause The exception that is the cause of the current exception. * @return An unchecked exception */ public static SKException build( String message, - @Nullable Exception e) { + @Nullable Exception cause) { - if (e == null) { + if (cause == null) { return new SKException(message); } - Throwable cause = e.getCause(); + Throwable wrappedCause = cause.getCause(); - if ((e instanceof SKCheckedException || e instanceof SKException) && cause != null) { - return new SKException(message, cause); + if ((cause instanceof SKCheckedException || cause instanceof SKException) + && wrappedCause != null) { + return new SKException(message, wrappedCause); } else { - return new SKException(message, e); + return new SKException(message, cause); } } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PreToolCallEvent.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PreToolCallEvent.java index 9ef0d16c..c991efca 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PreToolCallEvent.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PreToolCallEvent.java @@ -38,12 +38,20 @@ public PreToolCallEvent( this.contextVariableTypes = contextVariableTypes; } + /** + * Gets the tool call arguments. + * @return The tool call arguments. + */ @SuppressFBWarnings("EI_EXPOSE_REP") @Nullable public KernelFunctionArguments getArguments() { return arguments; } + /** + * Get the tool call function. + * @return The tool call function. + */ @SuppressFBWarnings("EI_EXPOSE_REP2") public KernelFunction getFunction() { return function; diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/localization/SemanticKernelResources.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/localization/SemanticKernelResources.java index 405c32a1..2ebc9c41 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/localization/SemanticKernelResources.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/localization/SemanticKernelResources.java @@ -6,6 +6,9 @@ import java.util.PropertyResourceBundle; import java.util.ResourceBundle; +/** + * Provides access to the resources used by the Semantic Kernel. + */ public class SemanticKernelResources { private static final String RESOURCE_BUNDLE_CLASS = "com.microsoft.semantickernel.localization.ResourceBundle"; @@ -20,6 +23,13 @@ public class SemanticKernelResources { RESOURCE_BUNDLE = setResourceBundle(LOCALE); } + /** + * Load the localized resource bundle for the Semantic Kernel. + * If there is no resource bundle for the specified locale, the default + * resource bundle will be loaded. + * @param locale The locale to use. + * @return the resource bundle. + */ public static ResourceBundle setResourceBundle(Locale locale) { ResourceBundle resourceBundle; try { @@ -33,12 +43,24 @@ public static ResourceBundle setResourceBundle(Locale locale) { return resourceBundle; } + /** + * Set the locale for the Semantic Kernel. As a side effect, + * the localized resource bundle will be loaded. + * @param locale The locale to use. + * @return the locale. + */ public static Locale setLocale(Locale locale) { LOCALE = locale; setResourceBundle(locale); return locale; } + /** + * Get the string for the specified id from the resource bundle. + * @param id The id of the string. + * @param defaultValue The default value to return if the string is not found. + * @return the localized string, or the default value if the string is not found. + */ public static String localize(String id, String defaultValue) { if (RESOURCE_BUNDLE.containsKey(id)) { return RESOURCE_BUNDLE.getString(id); @@ -47,8 +69,13 @@ public static String localize(String id, String defaultValue) { } } - public static String getString(String s) { - return localize(s, s); + /** + * Get the string for the specified id from the resource bundle. + * @param id The id of the string. + * @return the localized string, or the id if the string is not found. + */ + public static String getString(String id) { + return localize(id, id); } } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionResultMetadata.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionResultMetadata.java index f9e79c7f..9bb55d11 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionResultMetadata.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionResultMetadata.java @@ -12,6 +12,7 @@ * Metadata about the result of a function invocation. *

* This class is used to return metadata about the result of a function invocation. + * @param The result type of the function invocation. */ public class FunctionResultMetadata { @@ -50,6 +51,8 @@ public FunctionResultMetadata(CaseInsensitiveMap> metadata) { /** * Create a new instance of FunctionResultMetadata. + * @param id The id of the result of the function invocation. + * @return A new instance of FunctionResultMetadata. */ public static FunctionResultMetadata build(String id) { return build(id, null, null); @@ -61,6 +64,7 @@ public static FunctionResultMetadata build(String id) { * @param id The id of the result of the function invocation. * @param usage The usage of the result of the function invocation. * @param createdAt The time the result was created. + * @param The result type of the function invocation. * @return A new instance of FunctionResultMetadata. */ public static FunctionResultMetadata build( diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/InvocationReturnMode.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/InvocationReturnMode.java index 1f03f22d..48c279f2 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/InvocationReturnMode.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/InvocationReturnMode.java @@ -1,6 +1,9 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.orchestration; +/** + * Represents the mode in which a function invocation should return its results. + */ public enum InvocationReturnMode { /** * Function invocations that build upon a history of previous invocations, such as Chat diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/ToolCallBehavior.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/ToolCallBehavior.java index affa13ac..6454a7fd 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/ToolCallBehavior.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/ToolCallBehavior.java @@ -70,6 +70,9 @@ public static ToolCallBehavior allowOnlyKernelFunctions(boolean autoInvoke, } private static final int DEFAULT_MAXIMUM_AUTO_INVOKE_ATTEMPTS = 5; + /** + * The separator between the plugin name and the function name. + */ public static final String FUNCTION_NAME_SEPARATOR = "-"; private final int maximumAutoInvokeAttempts; diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonObjectResponseFormat.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonObjectResponseFormat.java index 6d9a107a..dde82691 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonObjectResponseFormat.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonObjectResponseFormat.java @@ -3,8 +3,15 @@ import com.fasterxml.jackson.annotation.JsonCreator; +/** + * A response represented in a JSON format. + */ public class JsonObjectResponseFormat extends ResponseFormat { + /** + * Used by Jackson deserialization to create a new instance + * of the {@link JsonObjectResponseFormat} class. + */ @JsonCreator public JsonObjectResponseFormat() { super(Type.JSON_OBJECT); diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonResponseSchema.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonResponseSchema.java index be92d417..c952cfea 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonResponseSchema.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonResponseSchema.java @@ -4,12 +4,23 @@ import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonProperty; +/** + * The schema for a response in JSON format. + */ public class JsonResponseSchema extends ResponseSchema { private final String name; private final String schema; private final boolean strict; + /** + * Used by Jackson deserialization to create a new + * instance of the {@link JsonResponseSchema} class. + * + * @param name The name of the schema. + * @param schema The schema. + * @param strict Whether the schema is strict. + */ @JsonCreator public JsonResponseSchema( @JsonProperty("name") String name, @@ -20,14 +31,26 @@ public JsonResponseSchema( this.strict = strict; } + /** + * Gets the name of the schema. + * @return The name of the schema. + */ public String getName() { return name; } + /** + * Gets the schema. + * @return The schema. + */ public String getSchema() { return schema; } + /** + * Gets whether the schema is strict. + * @return Whether the schema is strict. + */ public boolean isStrict() { return strict; } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonSchemaResponseFormat.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonSchemaResponseFormat.java index 68547d3a..ebc43b93 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonSchemaResponseFormat.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/JsonSchemaResponseFormat.java @@ -6,10 +6,18 @@ import com.microsoft.semantickernel.exceptions.SKException; import javax.annotation.Nullable; +/** + * A response represented in a JSON schema format. + */ public class JsonSchemaResponseFormat extends ResponseFormat { private final JsonResponseSchema jsonSchema; + /** + * Used by Jackson deserialization to create a new instance + * of the {@link JsonSchemaResponseFormat} class. + * @param jsonSchema The JSON schema. + */ @JsonCreator public JsonSchemaResponseFormat( @JsonProperty("json_schema") JsonResponseSchema jsonSchema) { @@ -17,15 +25,26 @@ public JsonSchemaResponseFormat( this.jsonSchema = jsonSchema; } + /** + * Gets the JSON schema. + * @return The JSON schema. + */ @JsonProperty("json_schema") public JsonResponseSchema getJsonSchema() { return jsonSchema; } + /** + * Creates a new instance of the {@link JsonSchemaResponseFormat} class. + * @return The new instance. + */ public static Builder builder() { return new Builder(); } + /** + * A builder for the {@link JsonSchemaResponseFormat} class. + */ public static class Builder { @Nullable @@ -36,38 +55,74 @@ public static class Builder { private String name = null; private boolean strict = true; + /** + * Sets the response format. + * @param clazz The class. + * @param responseSchemaGenerator The response schema generator. + * @return The builder. + */ public Builder setResponseFormat(Class clazz, ResponseSchemaGenerator responseSchemaGenerator) { name = clazz.getSimpleName(); return setJsonSchema(responseSchemaGenerator.generateSchema(clazz)); } + /** + * Sets the response format. Uses Jackson to generate the schema + * from the {@code clazz} + * @param clazz The class. + * @return The builder. + */ public Builder setResponseFormat(Class clazz) { name = clazz.getSimpleName(); setJsonSchema(ResponseSchemaGenerator.jacksonGenerator().generateSchema(clazz)); return this; } + /** + * Sets the JSON response schema. + * @param jsonResponseSchema The JSON response schema. + * @return The builder. + */ public Builder setJsonResponseSchema(JsonResponseSchema jsonResponseSchema) { this.jsonResponseSchema = jsonResponseSchema; return this; } + /** + * Sets the JSON schema. + * @param jsonSchema The JSON schema. + * @return The builder. + */ public Builder setJsonSchema(String jsonSchema) { this.jsonSchema = jsonSchema; return this; } + /** + * Sets the name of the JSON schema. + * @param name The schema name. + * @return The builder. + */ public Builder setName(String name) { this.name = name; return this; } + /** + * Sets whether the schema is strict. + * @param strict Whether the schema is strict. + * @return The builder. + */ public Builder setStrict(boolean strict) { this.strict = strict; return this; } + /** + * Builds the {@link JsonSchemaResponseFormat} instance. + * @return The {@link JsonSchemaResponseFormat} instance. + */ public JsonSchemaResponseFormat build() { if (jsonResponseSchema != null) { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseFormat.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseFormat.java index beb68760..9ebcbd66 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseFormat.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseFormat.java @@ -7,6 +7,9 @@ import com.fasterxml.jackson.annotation.JsonTypeInfo.As; import com.fasterxml.jackson.annotation.JsonTypeInfo.Id; +/** + * Base class for response formats. + */ @JsonTypeInfo(use = Id.NAME, include = As.EXISTING_PROPERTY, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(value = JsonSchemaResponseFormat.class, name = "json_schema", names = { @@ -15,23 +18,44 @@ "TEXT" }), @JsonSubTypes.Type(value = JsonObjectResponseFormat.class, name = "json_object", names = { "json_object", "JSON_OBJECT" }), + }) public abstract class ResponseFormat { + /** + * The type of the response format. + */ public static enum Type { + /** + * Only valid for openai chat completion, with GPT-4 and gpt-3.5-turbo-1106+ models. + */ JSON_OBJECT, /** * Only valid for openai chat completion, with GPT-4 and gpt-3.5-turbo-1106+ models. */ - JSON_SCHEMA, TEXT; + JSON_SCHEMA, + /** + * The response is in text format. + */ + TEXT; } private final Type type; + /** + * Creates a new instance of the {@link ResponseFormat} class. + * + * @param type The type of the response format. + */ public ResponseFormat(Type type) { this.type = type; } + /** + * Gets the type of the response format. + * + * @return The type. + */ @JsonProperty("type") public Type getType() { return type; diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseSchemaGenerator.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseSchemaGenerator.java index f9f66849..676f2872 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseSchemaGenerator.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/ResponseSchemaGenerator.java @@ -39,6 +39,13 @@ public static ResponseSchemaGenerator jacksonGenerator() { } } + /** + * Load a response schema generator based on the given class name. + * The class must implement the {@link ResponseSchemaGenerator} interface. + * + * @param className The class name of the generator. + * @return The response schema generator. + */ public static ResponseSchemaGenerator loadGenerator(String className) { return ServiceLoadUtil .findServiceLoader(ResponseSchemaGenerator.class, diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/TextResponseFormat.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/TextResponseFormat.java index daf0e021..45214f31 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/TextResponseFormat.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/responseformat/TextResponseFormat.java @@ -3,8 +3,15 @@ import com.fasterxml.jackson.annotation.JsonCreator; +/** + * Represents a text response format. + */ public class TextResponseFormat extends ResponseFormat { + /** + * Used by Jackson to creates a new instance of the + * {@link TextResponseFormat} class. + */ @JsonCreator public TextResponseFormat() { super(Type.TEXT); diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelPluginFactory.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelPluginFactory.java index a6a23c3b..afa31cb0 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelPluginFactory.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelPluginFactory.java @@ -428,6 +428,7 @@ private static KernelFunction getKernelFunction( } /** + * Imports a plugin from a resource directory on the filesystem. * @param parentDirectory The parent directory containing the plugin directories. * @param pluginDirectoryName The name of the plugin directory. * @param functionName The name of the function to import. diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/HandlebarsPromptTemplateFactory.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/HandlebarsPromptTemplateFactory.java index 786df87c..2a9b991f 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/HandlebarsPromptTemplateFactory.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/HandlebarsPromptTemplateFactory.java @@ -18,6 +18,12 @@ public class HandlebarsPromptTemplateFactory implements PromptTemplateFactory { */ public static final String HANDLEBARS_TEMPLATE_FORMAT = "handlebars"; + /** + * Initializes a new instance of the {@link HandlebarsPromptTemplateFactory} class. + */ + public HandlebarsPromptTemplateFactory() { + } + @Override public PromptTemplate tryCreate(@NonNull PromptTemplateConfig templateConfig) { if (templateConfig.getTemplateFormat() != null && diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/InputVariable.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/InputVariable.java index a819b2ee..80042263 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/InputVariable.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/InputVariable.java @@ -79,6 +79,7 @@ public InputVariable(String name) { * @param type the type of the input variable * @param description the description of the input variable * @param defaultValue the default value of the input variable + * @param enumValues the enum values of the input variable * @param required whether the input variable is required * @return a new instance of {@link InputVariable} */ diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunction.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunction.java index 8dd31b6e..70f33bd7 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunction.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunction.java @@ -99,6 +99,7 @@ public static FromPromptBuilder createFromPrompt( } /** + * Get the plugin name of the function. * @return The name of the plugin that this function is within */ @Nullable @@ -107,6 +108,7 @@ public String getPluginName() { } /** + * Get the name of the function. * @return The name of this function */ public String getName() { @@ -114,6 +116,7 @@ public String getName() { } /** + * Get the description of the function. * @return A description of the function */ @Nullable diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromMethod.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromMethod.java index 9a67b575..680d93c0 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromMethod.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromMethod.java @@ -148,6 +148,13 @@ private static MethodDetails getMethodDetails( method.getReturnType())); } + /** + * Gets the function from the method. + * @param method the method to invoke + * @param instance the instance to invoke the method on + * @param the return type of the function + * @return the function representing the method + */ @SuppressWarnings("unchecked") public static ImplementationFunc getFunction(Method method, Object instance) { return (kernel, function, arguments, variableType, invocationContext) -> { @@ -683,6 +690,11 @@ private static InputVariable toKernelParameterMetadata(Parameter parameter) { isRequired); } + /** + * Gets the constants from an enum type. + * @param type the type to get the enum constants from + * @return a list of the enum constants or {@code null} if the type is not an enum + */ public static @Nullable List getEnumOptions(Class type) { List enumValues = null; if (type.isEnum()) { @@ -719,6 +731,7 @@ public Mono> invokeAsync( /** * Concrete implementation of the abstract method in KernelFunction. + * @param the return type of the function */ public interface ImplementationFunc { @@ -762,6 +775,7 @@ default FunctionResult invoke( /** * A builder for {@link KernelFunction}. + * @param the return type of the function */ public static class Builder { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromPrompt.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromPrompt.java index 697da535..adcea185 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromPrompt.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromPrompt.java @@ -450,6 +450,5 @@ public KernelFunction build() { return new KernelFunctionFromPrompt<>(temp, config, executionSettings); } - } } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelPromptTemplateFactory.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelPromptTemplateFactory.java index b10c6fb9..45dd8428 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelPromptTemplateFactory.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelPromptTemplateFactory.java @@ -16,6 +16,12 @@ */ public class KernelPromptTemplateFactory implements PromptTemplateFactory { + /** + * Initializes a new instance of the {@code KernelPromptTemplateFactory} class. + */ + public KernelPromptTemplateFactory() { + } + @Override public PromptTemplate tryCreate(@Nonnull PromptTemplateConfig templateConfig) { if (templateConfig.getTemplate() == null) { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/OutputVariable.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/OutputVariable.java index 8871c03f..833aef17 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/OutputVariable.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/OutputVariable.java @@ -9,6 +9,7 @@ /** * Metadata for an output variable of a kernel function. + * @param The type of the output variable. */ public class OutputVariable { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateConfig.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateConfig.java index 93df46f3..cbc0478b 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateConfig.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateConfig.java @@ -408,7 +408,7 @@ private Builder(PromptTemplateConfig promptTemplateConfig) { * Set the name of the prompt template config. * * @param name The name of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withName(String name) { this.name = name; @@ -419,7 +419,7 @@ public Builder withName(String name) { * Add an input variable to the prompt template config. * * @param inputVariable The input variable to add. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder addInputVariable(InputVariable inputVariable) { inputVariables.add(inputVariable); @@ -430,7 +430,7 @@ public Builder addInputVariable(InputVariable inputVariable) { * Set the template of the prompt template config. * * @param template The template of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withTemplate(String template) { this.template = template; @@ -441,7 +441,7 @@ public Builder withTemplate(String template) { * Set the description of the prompt template config. * * @param description The description of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withDescription(String description) { this.description = description; @@ -452,13 +452,18 @@ public Builder withDescription(String description) { * Set the template format of the prompt template config. * * @param templateFormat The template format of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withTemplateFormat(String templateFormat) { this.templateFormat = templateFormat; return this; } + /** + * Set the prompt template options. + * @param option The prompt template option to add. + * @return {@code this} builder. + */ public Builder addPromptTemplateOption(PromptTemplateOption option) { promptTemplateOptions.add(option); return this; @@ -468,7 +473,7 @@ public Builder addPromptTemplateOption(PromptTemplateOption option) { * Set the inputVariables of the prompt template config. * * @param inputVariables The input variables of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withInputVariables(List inputVariables) { this.inputVariables = new ArrayList<>(inputVariables); @@ -479,7 +484,7 @@ public Builder withInputVariables(List inputVariables) { * Set the output variable of the prompt template config. * * @param outputVariable The output variable of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withOutputVariable(OutputVariable outputVariable) { this.outputVariable = outputVariable; @@ -490,7 +495,7 @@ public Builder withOutputVariable(OutputVariable outputVariable) { * Set the prompt execution settings of the prompt template config. * * @param executionSettings The prompt execution settings of the prompt template config. - * @return {@code this} prompt template config. + * @return {@code this} builder */ public Builder withExecutionSettings( Map executionSettings) { diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateOption.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateOption.java index 5d244613..56f5a2e2 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateOption.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateOption.java @@ -1,6 +1,9 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.semanticfunctions; +/** + * Options to customize the behavior of a prompt. + */ public enum PromptTemplateOption { /** * Allow methods on objects provided as arguments to an invocation, to be invoked when rendering diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/KernelContent.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/KernelContent.java index 2a7ddf00..6c8c80bc 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/KernelContent.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/KernelContent.java @@ -11,16 +11,18 @@ */ public interface KernelContent { - /* + /** * The inner content representation. Use this to bypass the current * abstraction. The usage of this property is considered "unsafe". * Use it only if strictly necessary. + * @return The inner content. */ @Nullable T getInnerContent(); /** * The metadata associated with the content. + * @return The metadata. */ @Nullable FunctionResultMetadata getMetadata(); diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/StreamingKernelContent.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/StreamingKernelContent.java index 02d9d737..dd1dcffe 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/StreamingKernelContent.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/StreamingKernelContent.java @@ -1,6 +1,10 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.services; +/** + * Base class which represents the content returned by an AI service. + * @param The type of the content. + */ public interface StreamingKernelContent extends KernelContent { } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/AudioToTextService.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/AudioToTextService.java index 871d4cb4..deeec0f6 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/AudioToTextService.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/AudioToTextService.java @@ -24,6 +24,10 @@ Mono getTextContentsAsync( AudioContent content, @Nullable AudioToTextExecutionSettings executionSettings); + /** + * Builder for the AudioToTextService. + * @return The builder. + */ static Builder builder() { return ServiceLoadUtil.findServiceLoader(Builder.class, "com.microsoft.semantickernel.aiservices.openai.audio.OpenAiAudioToTextService$Builder") diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/TextToAudioExecutionSettings.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/TextToAudioExecutionSettings.java index c367e37f..f85659c5 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/TextToAudioExecutionSettings.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/audio/TextToAudioExecutionSettings.java @@ -126,6 +126,9 @@ public TextToAudioExecutionSettings build() { } return new TextToAudioExecutionSettings(voice, responseFormat, speed); } + + private Builder() { + } } } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/ChatHistory.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/ChatHistory.java index ea910c01..25cd8ea8 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/ChatHistory.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/ChatHistory.java @@ -83,6 +83,7 @@ public void addAll(ChatHistory value) { /** * Create an {@code Iterator} from the chat history. + * @return An {@code Iterator} from the chat history. */ @Override public Iterator> iterator() { @@ -101,6 +102,7 @@ public void forEach(Consumer> action) { /** * Create a {@code Spliterator} from the chat history + * @return A {@code Spliterator} from the chat history */ @Override public Spliterator> spliterator() { @@ -114,6 +116,7 @@ public Spliterator> spliterator() { * @param content The content of the message * @param encoding The encoding of the message * @param metadata The metadata of the message + * @return {@code this} ChatHistory */ public ChatHistory addMessage(AuthorRole authorRole, String content, Charset encoding, FunctionResultMetadata metadata) { @@ -132,6 +135,7 @@ public ChatHistory addMessage(AuthorRole authorRole, String content, Charset enc * * @param authorRole The role of the author of the message * @param content The content of the message + * @return {@code this} ChatHistory */ public ChatHistory addMessage(AuthorRole authorRole, String content) { chatMessageContents.add( @@ -146,6 +150,7 @@ public ChatHistory addMessage(AuthorRole authorRole, String content) { * Add a message to the chat history * * @param content The content of the message + * @return {@code this} ChatHistory */ public ChatHistory addMessage(ChatMessageContent content) { chatMessageContents.add(content); @@ -156,6 +161,7 @@ public ChatHistory addMessage(ChatMessageContent content) { * Add a user message to the chat history * * @param content The content of the user message + * @return {@code this} ChatHistory */ public ChatHistory addUserMessage(String content) { return addMessage(AuthorRole.USER, content); @@ -165,6 +171,7 @@ public ChatHistory addUserMessage(String content) { * Add an assistant message to the chat history * * @param content The content of the assistant message + * @return {@code this} ChatHistory */ public ChatHistory addAssistantMessage(String content) { return addMessage(AuthorRole.ASSISTANT, content); @@ -174,11 +181,17 @@ public ChatHistory addAssistantMessage(String content) { * Add an system message to the chat history * * @param content The content of the system message + * @return {@code this} ChatHistory */ public ChatHistory addSystemMessage(String content) { return addMessage(AuthorRole.SYSTEM, content); } + /** + * Add all messages to the chat history + * @param messages The messages to add to the chat history + * @return {@code this} ChatHistory + */ public ChatHistory addAll(List> messages) { chatMessageContents.addAll(messages); return this; diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/StreamingChatContent.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/StreamingChatContent.java index 46182913..52bb4131 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/StreamingChatContent.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/StreamingChatContent.java @@ -3,7 +3,15 @@ import com.microsoft.semantickernel.services.StreamingKernelContent; +/** + * Base class which represents the content returned by a chat completion service. + * @param The type of the content. + */ public interface StreamingChatContent extends StreamingKernelContent { + /** + * Gets the ID of the content. + * @return The ID. + */ public String getId(); } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageImageContent.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageImageContent.java index e87f7fcc..75ab0a3d 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageImageContent.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageImageContent.java @@ -9,10 +9,21 @@ import java.util.Base64; import javax.annotation.Nullable; +/** + * Represents an image content in a chat message. + * + * @param the type of the inner content within the message + */ public class ChatMessageImageContent extends ChatMessageContent { private final ImageDetail detail; + /** + * Create a new instance of the {@link ChatMessageImageContent} class. + * @param content The chat message content + * @param modelId The LLM id to use for the chat + * @param detail The detail level of the image to include in the chat message + */ public ChatMessageImageContent( String content, @Nullable String modelId, @@ -69,6 +80,10 @@ public static Builder builder() { return new Builder<>(); } + /** + * Builder for the {@link ChatMessageImageContent} class. + * @param the type of the inner content within the message + */ public static class Builder implements SemanticKernelBuilder> { @Nullable @@ -82,7 +97,7 @@ public static class Builder implements SemanticKernelBuilder withModelId(String modelId) { this.modelId = modelId; @@ -90,10 +105,11 @@ public Builder withModelId(String modelId) { } /** + * Set the image content to include in the chat message. * @param imageType For instance jpg or png. For known types known to OpenAI see: docs. * @param content the image content - * @return this builder + * @return {@code this} builder */ public Builder withImage( String imageType, @@ -108,7 +124,7 @@ public Builder withImage( * Set the URL of the image to include in the chat message. * * @param url the URL of the image - * @return this builder + * @return {@code this} builder */ public Builder withImageUrl(String url) { this.content = url; @@ -119,7 +135,7 @@ public Builder withImageUrl(String url) { * Set the URL of the image to include in the chat message. * * @param url the URL of the image - * @return this builder + * @return {@code this} builder */ public Builder withImageUrl(URL url) { this.content = url.toString(); @@ -130,7 +146,7 @@ public Builder withImageUrl(URL url) { * Set the detail level of the image to include in the chat message. * * @param detail the detail level of the image - * @return this builder + * @return {@code this} builder */ public Builder withDetail(ImageDetail detail) { this.detail = detail; diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageTextContent.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageTextContent.java index ccce7e4d..f065ed2f 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageTextContent.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/chatcompletion/message/ChatMessageTextContent.java @@ -81,6 +81,9 @@ public static ChatMessageTextContent systemMessage(String content) { return buildContent(AuthorRole.SYSTEM, content); } + /** + * Builder for the {@link ChatMessageTextContent} class. + */ public static class Builder implements SemanticKernelBuilder { @Nullable diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/Embedding.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/Embedding.java index 66ea2791..dcdce1c6 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/Embedding.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/Embedding.java @@ -15,6 +15,10 @@ public class Embedding { private static final Embedding EMPTY = new Embedding(); + /** + * Returns an empty {@code Embedding} instance. + * @return An empty {@code Embedding} instance. + */ public static Embedding empty() { return EMPTY; } diff --git a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/EmbeddingGenerationService.java b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/EmbeddingGenerationService.java index 79ce998e..561dbe1d 100644 --- a/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/EmbeddingGenerationService.java +++ b/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/textembedding/EmbeddingGenerationService.java @@ -6,7 +6,8 @@ import reactor.core.publisher.Mono; /** - * Interface for text embedding generation services + * Interface for text embedding generation services + * @param The type of the data to generate embeddings for */ public interface EmbeddingGenerationService extends AIService { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStore.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStore.java index adbbdb87..e1e64048 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStore.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStore.java @@ -13,6 +13,9 @@ import javax.annotation.Nullable; import reactor.core.publisher.Mono; +/** + * Represents an Azure AI Search vector store. + */ public class AzureAISearchVectorStore implements VectorStore { private final SearchIndexAsyncClient searchIndexAsyncClient; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreCollectionCreateMapping.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreCollectionCreateMapping.java index 7afe3c35..996790f3 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreCollectionCreateMapping.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreCollectionCreateMapping.java @@ -21,6 +21,9 @@ import java.util.List; import javax.annotation.Nonnull; +/** + * Maps vector store record fields to Azure AI Search fields. + */ class AzureAISearchVectorStoreCollectionCreateMapping { private static String getVectorSearchProfileName(VectorStoreRecordVectorField vectorField) { @@ -71,12 +74,24 @@ private static VectorSearchAlgorithmConfiguration getAlgorithmConfig( } } + /** + * Maps a key field to a search field. + * + * @param keyField The key field. + * @return The search field. + */ public static SearchField mapKeyField(VectorStoreRecordKeyField keyField) { return new SearchField(keyField.getEffectiveStorageName(), SearchFieldDataType.STRING) .setKey(true) .setFilterable(true); } + /** + * Maps a data field to a search field. + * + * @param dataField The data field. + * @return The search field. + */ public static SearchField mapDataField(VectorStoreRecordDataField dataField) { if (dataField.getFieldType() == null) { throw new SKException( @@ -89,6 +104,12 @@ public static SearchField mapDataField(VectorStoreRecordDataField dataField) { .setSearchable(dataField.isFullTextSearchable()); } + /** + * Maps a vector field to a search field. + * + * @param vectorField The vector field. + * @return The search field. + */ public static SearchField mapVectorField(VectorStoreRecordVectorField vectorField) { return new SearchField(vectorField.getEffectiveStorageName(), SearchFieldDataType.collection(SearchFieldDataType.SINGLE)) @@ -97,6 +118,13 @@ public static SearchField mapVectorField(VectorStoreRecordVectorField vectorFiel .setVectorSearchProfileName(getVectorSearchProfileName(vectorField)); } + /** + * Updates the vector search parameters for the specified vector field. + * + * @param algorithms The list of vector search algorithms. + * @param profiles The list of vector search profiles. + * @param vectorField The vector field. + */ public static void updateVectorSearchParameters( List algorithms, List profiles, @@ -110,6 +138,12 @@ public static void updateVectorSearchParameters( getVectorSearchProfileName(vectorField), getAlgorithmConfigName(vectorField))); } + /** + * Gets the search field data type for the specified field type. + * + * @param fieldType The field type. + * @return The search field data type. + */ public static SearchFieldDataType getSearchFieldDataType(Class fieldType) { if (fieldType == String.class) { return SearchFieldDataType.STRING; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreOptions.java index db3b7ab6..2a5d71b8 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreOptions.java @@ -3,6 +3,9 @@ import javax.annotation.Nullable; +/** + * Represents the options for the Azure AI Search vector store. + */ public class AzureAISearchVectorStoreOptions { @Nullable diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollection.java index b01a0a76..02971935 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollection.java @@ -43,6 +43,11 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; +/** + * Represents an Azure AI Search vector store record collection. + * + * @param The type of the record. + */ public class AzureAISearchVectorStoreRecordCollection implements VectorStoreRecordCollection, VectorizedSearch, @@ -83,6 +88,13 @@ public class AzureAISearchVectorStoreRecordCollection implements private final List nonVectorFields = new ArrayList<>(); private final String firstVectorFieldName; + /** + * Creates a new instance of {@link AzureAISearchVectorStoreRecordCollection}. + * + * @param searchIndexAsyncClient The Azure AI Search client. + * @param collectionName The name of the collection. + * @param options The options for the collection. + */ @SuppressFBWarnings("EI_EXPOSE_REP2") public AzureAISearchVectorStoreRecordCollection( @Nonnull SearchIndexAsyncClient searchIndexAsyncClient, diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionFactory.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionFactory.java index b0acf545..6856b3c1 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionFactory.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionFactory.java @@ -16,6 +16,7 @@ public interface AzureAISearchVectorStoreRecordCollectionFactory { * @param collectionName The name of the collection. * @param recordClass The class type of the record. * @param recordDefinition The record definition. + * @param The record type. * @return The new Azure AI Search vector store record collection. */ AzureAISearchVectorStoreRecordCollection createVectorStoreRecordCollection( diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionOptions.java index d1fad192..e62f1020 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/azureaisearch/AzureAISearchVectorStoreRecordCollectionOptions.java @@ -95,6 +95,11 @@ public static class Builder { @Nullable private VectorStoreRecordDefinition recordDefinition; + /** + * Sets the record class. + * @param recordClass the record Class + * @return the builder + */ public Builder withRecordClass(Class recordClass) { this.recordClass = recordClass; return this; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/hsqldb/HSQLDBVectorStoreQueryProvider.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/hsqldb/HSQLDBVectorStoreQueryProvider.java index 85b33d1f..730458a5 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/hsqldb/HSQLDBVectorStoreQueryProvider.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/hsqldb/HSQLDBVectorStoreQueryProvider.java @@ -25,6 +25,10 @@ import java.util.stream.Collectors; import javax.sql.DataSource; +/** + * The HSQLDB vector store query provider. + * Provides the necessary methods to interact with a HSQLDB vector store and vector store collections. + */ public class HSQLDBVectorStoreQueryProvider extends JDBCVectorStoreQueryProvider { private final ObjectMapper objectMapper; @@ -121,7 +125,6 @@ private void setUpsertStatementValues(PreparedStatement statement, Object record @Override @SuppressFBWarnings("SQL_PREPARED_STATEMENT_GENERATED_FROM_NONCONSTANT_STRING") // SQL query is generated dynamically with valid identifiers - public void upsertRecords(String collectionName, List records, VectorStoreRecordDefinition recordDefinition, UpsertRecordOptions options) { validateSQLidentifier(getCollectionTableName(collectionName)); @@ -176,6 +179,9 @@ public static Builder builder() { return new Builder(); } + /** + * The builder for the HSQLDB vector store query provider. + */ public static class Builder extends JDBCVectorStoreQueryProvider.Builder { @@ -185,6 +191,12 @@ public static class Builder private int defaultVarCharLength = 255; private ObjectMapper objectMapper = new ObjectMapper(); + /** + * Sets the data source. + * + * @param dataSource the data source + * @return the builder + */ @SuppressFBWarnings("EI_EXPOSE_REP2") public Builder withDataSource(DataSource dataSource) { this.dataSource = dataSource; @@ -213,6 +225,12 @@ public Builder withPrefixForCollectionTables(String prefixForCollectionTables) { return this; } + /** + * Sets the default VARCHAR length. + * + * @param defaultVarCharLength the default VARCHAR length + * @return the builder + */ public Builder setDefaultVarCharLength(int defaultVarCharLength) { this.defaultVarCharLength = defaultVarCharLength; return this; @@ -230,6 +248,11 @@ public Builder withObjectMapper(ObjectMapper objectMapper) { return this; } + /** + * Builds the HSQLDB vector store query provider. + * + * @return the HSQLDB vector store query provider + */ public HSQLDBVectorStoreQueryProvider build() { if (dataSource == null) { throw new SKException("DataSource is required"); diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStore.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStore.java index 4e349eb1..3d045e58 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStore.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStore.java @@ -102,6 +102,7 @@ public VectorStoreRecordCollection getCollection( * @param collectionName The name of the collection. * @param recordClass The class type of the record. * @param recordDefinition The record definition. + * @param The record type. * @return The collection. */ public VectorStoreRecordCollection getCollection( diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreOptions.java index 58e2c85e..db2e6c8d 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreOptions.java @@ -5,6 +5,9 @@ import javax.annotation.Nullable; +/** + * Options for the JDBC vector store. + */ public class JDBCVectorStoreOptions { @Nullable private final JDBCVectorStoreRecordCollectionFactory vectorStoreRecordCollectionFactory; @@ -15,6 +18,8 @@ public class JDBCVectorStoreOptions { * Creates a new instance of the JDBC vector store options. * * @param vectorStoreRecordCollectionFactory The vector store record collection factory. + * @param queryProvider The query provider. + * */ @SuppressFBWarnings("EI_EXPOSE_REP2") // DataSource in queryProvider is not exposed public JDBCVectorStoreOptions( @@ -63,7 +68,6 @@ public JDBCVectorStoreRecordCollectionFactory getVectorStoreRecordCollectionFact /** * Builder for JDBC vector store options. - * */ public static class Builder { @Nullable diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreQueryProvider.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreQueryProvider.java index dfa0d0f6..f33374aa 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreQueryProvider.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreQueryProvider.java @@ -36,6 +36,9 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * A JDBC vector store query provider. + */ public class JDBCVectorStoreQueryProvider implements SQLVectorStoreQueryProvider, SQLVectorStoreFilterQueryProvider { @@ -84,6 +87,15 @@ protected JDBCVectorStoreQueryProvider( supportedVectorTypes.put(Collection.class, "TEXT"); } + /** + * Creates a new instance of the JDBCVectorStoreQueryProvider class. + * @param dataSource the data source + * @param collectionsTable the collections table + * @param prefixForCollectionTables the prefix for collection tables + * @param supportedKeyTypes the supported key types + * @param supportedDataTypes the supported data types + * @param supportedVectorTypes the supported vector types + */ public JDBCVectorStoreQueryProvider( @SuppressFBWarnings("EI_EXPOSE_REP2") @Nonnull DataSource dataSource, @Nonnull String collectionsTable, @@ -573,6 +585,13 @@ public String formatQuery(String query, String... args) { return String.format(query, (Object[]) args); } + /** + * Gets the filter query string for the given vector search filter and record definition. + * + * @param filter The filter to get the filter string for. + * @param recordDefinition The record definition to get the filter string for. + * @return The filter string. + */ @Override public String getFilter(VectorSearchFilter filter, VectorStoreRecordDefinition recordDefinition) { @@ -601,14 +620,21 @@ public String getFilter(VectorSearchFilter filter, }).collect(Collectors.joining(" AND ")); } + /** + * Gets the filter parameters for the given vector search filter to associate with the filter string + * generated by the getFilter method. + * + * @param filter The filter to get the filter parameters for. + * @return The filter parameters. + */ @Override - public List getFilterParameters(VectorSearchFilter vectorSearchFilter) { - if (vectorSearchFilter == null - || vectorSearchFilter.getFilterClauses().isEmpty()) { + public List getFilterParameters(VectorSearchFilter filter) { + if (filter == null + || filter.getFilterClauses().isEmpty()) { return Collections.emptyList(); } - return vectorSearchFilter.getFilterClauses().stream().map(filterClause -> { + return filter.getFilterClauses().stream().map(filterClause -> { if (filterClause instanceof EqualToFilterClause) { EqualToFilterClause equalToFilterClause = (EqualToFilterClause) filterClause; return equalToFilterClause.getValue(); diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollection.java index f43fca6e..31b25bef 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollection.java @@ -27,6 +27,14 @@ import reactor.core.publisher.Mono; import reactor.core.scheduler.Schedulers; +/** + * The JDBCVectorStoreRecordCollection class represents a collection of records + * in a JDBC vector store. It implements the SQLVectorStoreRecordCollection + * interface and provides methods for managing the collection, such as creating, + * deleting, and upserting records. + * + * @param the type of the records in the collection + */ public class JDBCVectorStoreRecordCollection implements SQLVectorStoreRecordCollection { @@ -313,6 +321,10 @@ public Mono>> searchAsync(List vector, .subscribeOn(Schedulers.boundedElastic()); } + /** + * Builder for a JDBCVectorStoreRecordCollection. + * @param the type of the records in the collection + */ public static class Builder implements SemanticKernelBuilder> { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionFactory.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionFactory.java index 14cdcc27..50063627 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionFactory.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionFactory.java @@ -17,6 +17,7 @@ public interface JDBCVectorStoreRecordCollectionFactory { * @param collectionName The name of the collection. * @param recordClass The class type of the * @param recordDefinition The record definition. + * @param The type of record in the collection. * @return The new JDBC vector store record collection. */ JDBCVectorStoreRecordCollection createVectorStoreRecordCollection( diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionOptions.java index 8ae826d4..5d2e439c 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollectionOptions.java @@ -13,6 +13,10 @@ import static com.microsoft.semantickernel.connectors.data.jdbc.SQLVectorStoreQueryProvider.DEFAULT_COLLECTIONS_TABLE; import static com.microsoft.semantickernel.connectors.data.jdbc.SQLVectorStoreQueryProvider.DEFAULT_PREFIX_FOR_COLLECTION_TABLES; +/** + * Options for a JDBC vector store record collection. + * @param the record type + */ public class JDBCVectorStoreRecordCollectionOptions implements VectorStoreRecordCollectionOptions { private final Class recordClass; @@ -105,6 +109,10 @@ public SQLVectorStoreQueryProvider getQueryProvider() { return queryProvider; } + /** + * Builder for JDBC vector store record collection options. + * @param the record type + */ public static class Builder { private Class recordClass; private VectorStoreRecordDefinition recordDefinition; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordMapper.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordMapper.java index 7db33984..880d93df 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordMapper.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordMapper.java @@ -21,6 +21,11 @@ import java.sql.SQLException; import java.util.function.BiFunction; +/** + * Maps a JDBC result set to a record. + * + * @param the record type + */ public class JDBCVectorStoreRecordMapper extends VectorStoreRecordMapper { @@ -52,6 +57,11 @@ public ResultSet mapRecordToStorageModel(Record record) { throw new UnsupportedOperationException("Not implemented"); } + /** + * Builder for {@link JDBCVectorStoreRecordMapper}. + * + * @param the record type + */ public static class Builder implements SemanticKernelBuilder> { private Class recordClass; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStore.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStore.java index ee45f8be..5fc68a64 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStore.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStore.java @@ -4,6 +4,9 @@ import com.microsoft.semantickernel.data.vectorstorage.VectorStore; import reactor.core.publisher.Mono; +/** + * Represents a SQL vector store. + */ public interface SQLVectorStore extends VectorStore { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreQueryProvider.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreQueryProvider.java index 8ae9c1ea..747e3c84 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreQueryProvider.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreQueryProvider.java @@ -102,6 +102,7 @@ public interface SQLVectorStoreQueryProvider { * @param recordDefinition the record definition * @param mapper the mapper * @param options the options + * @param the record type * @return the records */ List getRecords(String collectionName, List keys, diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreRecordCollection.java index 711344fa..120d0273 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/SQLVectorStoreRecordCollection.java @@ -4,6 +4,12 @@ import com.microsoft.semantickernel.data.vectorstorage.VectorStoreRecordCollection; import reactor.core.publisher.Mono; +/** + * Represents a SQL vector store record collection. + * + * @param the key type + * @param the record type + */ public interface SQLVectorStoreRecordCollection extends VectorStoreRecordCollection { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/mysql/MySQLVectorStoreQueryProvider.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/mysql/MySQLVectorStoreQueryProvider.java index 54a379cc..89e8f857 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/mysql/MySQLVectorStoreQueryProvider.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/mysql/MySQLVectorStoreQueryProvider.java @@ -22,6 +22,11 @@ import java.util.List; import java.util.stream.Collectors; +/** + * The MySQL vector store query provider. + * Provides the necessary methods to interact with a MySQL + * vector store and vector store collections. + */ public class MySQLVectorStoreQueryProvider extends JDBCVectorStoreQueryProvider implements SQLVectorStoreQueryProvider { @@ -115,6 +120,9 @@ public void upsertRecords(String collectionName, List records, } } + /** + * The MySQL vector store query provider builder. + */ public static class Builder extends JDBCVectorStoreQueryProvider.Builder { private DataSource dataSource; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorDistanceFunction.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorDistanceFunction.java index 001a5499..669f3652 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorDistanceFunction.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorDistanceFunction.java @@ -3,9 +3,26 @@ import com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction; +/** + * Represents a PostgreSQL vector distance function. + */ public enum PostgreSQLVectorDistanceFunction { - L2("vector_l2_ops", "<->"), COSINE("vector_cosine_ops", "<=>"), INNER_PRODUCT("vector_ip_ops", - "<#>"), UNDEFINED(null, null); + /** + * Euclidean L2 distance function. + */ + L2("vector_l2_ops", "<->"), + /** + * The cosine distance function. + */ + COSINE("vector_cosine_ops", "<=>"), + /** + * The inner product distance function. + */ + INNER_PRODUCT("vector_ip_ops", "<#>"), + /** + * The distance function is undefined. + */ + UNDEFINED(null, null); private final String value; private final String operator; @@ -15,14 +32,27 @@ public enum PostgreSQLVectorDistanceFunction { this.operator = operator; } + /** + * Gets the value of the distance function. + * @return the value of the distance function + */ public String getValue() { return value; } + /** + * Gets the operator of the distance function. + * @return the operator of the distance function + */ public String getOperator() { return operator; } + /** + * Converts a distance function to a PostgreSQL vector distance function. + * @param function the distance function + * @return the PostgreSQL vector distance function + */ public static PostgreSQLVectorDistanceFunction fromDistanceFunction(DistanceFunction function) { switch (function) { case EUCLIDEAN_DISTANCE: diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorIndexKind.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorIndexKind.java index 1a04fb18..6681ef83 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorIndexKind.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorIndexKind.java @@ -3,8 +3,22 @@ import com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind; +/** + * Represents a PostgreSQL vector index kind. + */ public enum PostgreSQLVectorIndexKind { - HNSW("hnsw"), IVFFLAT("ivfflat"), UNDEFINED(null); + /** + * The vector is indexed using an HNSW algorithm. + */ + HNSW("hnsw"), + /** + * The vector is indexed using a Flat algorithm. + */ + IVFFLAT("ivfflat"), + /** + * The indexing algorithm is undefined. + */ + UNDEFINED(null); private final String value; @@ -12,10 +26,19 @@ public enum PostgreSQLVectorIndexKind { this.value = value; } + /** + * Gets the pgvector value of the index kind. + * @return the pgvector value of the index kind + */ public String getValue() { return value; } + /** + * Converts an index kind to a PostgreSQL vector index kind. + * @param indexKind the index kind + * @return the PostgreSQL vector index kind + */ public static PostgreSQLVectorIndexKind fromIndexKind(IndexKind indexKind) { switch (indexKind) { case HNSW: diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreQueryProvider.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreQueryProvider.java index 3778d74a..6be72981 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreQueryProvider.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreQueryProvider.java @@ -38,6 +38,11 @@ import java.util.Map; import java.util.stream.Collectors; +/** + * The MySQL vector store query provider. + * Provides the necessary methods to interact with a MySQL + * vector store and vector store collections. + */ public class PostgreSQLVectorStoreQueryProvider extends JDBCVectorStoreQueryProvider implements SQLVectorStoreQueryProvider { private final String collectionsTable; @@ -405,14 +410,21 @@ public List> search(String collectionName, } } + /** + * Gets the filter parameters for the given vector search filter to associate with the filter string + * generated by the getFilter method. + * + * @param filter The filter to get the filter parameters for. + * @return The filter parameters. + */ @Override - public List getFilterParameters(VectorSearchFilter vectorSearchFilter) { - if (vectorSearchFilter == null - || vectorSearchFilter.getFilterClauses().isEmpty()) { + public List getFilterParameters(VectorSearchFilter filter) { + if (filter == null + || filter.getFilterClauses().isEmpty()) { return Collections.emptyList(); } - return vectorSearchFilter.getFilterClauses().stream().map(filterClause -> { + return filter.getFilterClauses().stream().map(filterClause -> { if (filterClause instanceof EqualToFilterClause) { EqualToFilterClause equalToFilterClause = (EqualToFilterClause) filterClause; return equalToFilterClause.getValue(); @@ -434,6 +446,9 @@ public String getAnyTagEqualToFilter(AnyTagEqualToFilterClause filterClause) { return String.format("%s @> ?::jsonb", fieldName); } + /** + * A builder for the PostgreSQLVectorStoreQueryProvider class. + */ public static class Builder extends JDBCVectorStoreQueryProvider.Builder { private DataSource dataSource; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreRecordMapper.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreRecordMapper.java index 410f708e..4b784a0a 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreRecordMapper.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/postgres/PostgreSQLVectorStoreRecordMapper.java @@ -21,6 +21,11 @@ import java.util.List; import java.util.function.BiFunction; +/** + * A mapper to convert between a record and a PostgreSQL storage model. + * + * @param the record type + */ public class PostgreSQLVectorStoreRecordMapper extends VectorStoreRecordMapper { @@ -44,6 +49,11 @@ public static Builder builder() { return new Builder<>(); } + /** + * A builder for the PostgreSQLVectorStoreRecordMapper. + * + * @param the record type + */ public static class Builder implements SemanticKernelBuilder> { private Class recordClass; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollection.java index 71cc79aa..b65fe9f9 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollection.java @@ -39,6 +39,11 @@ import java.util.Map; import java.util.stream.Collectors; +/** + * RedisHashSetVectorStoreRecordCollection is a class that represents a + * collection of records stored in Redis using the Hash Set data structure. + * @param The record type. + */ public class RedisHashSetVectorStoreRecordCollection implements VectorStoreRecordCollection, VectorizedSearch { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollectionOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollectionOptions.java index 52dc404b..071f40fc 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollectionOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordCollectionOptions.java @@ -13,6 +13,10 @@ import java.util.Map; import java.util.Map.Entry; +/** + * Options for a Redis hash set vector store record collection. + * @param the record type + */ public class RedisHashSetVectorStoreRecordCollectionOptions implements VectorStoreRecordCollectionOptions { private final Class recordClass; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordMapper.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordMapper.java index 2f91ea11..25678ef2 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordMapper.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisHashSetVectorStoreRecordMapper.java @@ -30,6 +30,10 @@ import static com.microsoft.semantickernel.connectors.data.redis.RedisHashSetVectorStoreRecordCollection.stringToBytes; +/** + * A mapper to convert between a record and a Redis hash set storage model. + * @param the record type + */ public class RedisHashSetVectorStoreRecordMapper extends VectorStoreRecordMapper>> { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollection.java index 0a7c2c15..4af97846 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollection.java @@ -47,6 +47,11 @@ import redis.clients.jedis.search.Schema; import redis.clients.jedis.search.SearchResult; +/** + * Represents a Redis vector store record collection. + * + * @param The type of record in the collection. + */ public class RedisJsonVectorStoreRecordCollection implements VectorStoreRecordCollection, VectorizedSearch { @@ -72,6 +77,7 @@ public class RedisJsonVectorStoreRecordCollection * Creates a new instance of the RedisVectorRecordStore. * * @param client The Redis client. + * @param collectionName The name of the collection. * @param options The options for the store. */ @SuppressFBWarnings("EI_EXPOSE_REP2") diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollectionOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollectionOptions.java index 9702e185..cd2da3b9 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollectionOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordCollectionOptions.java @@ -12,6 +12,11 @@ import javax.annotation.Nullable; import java.util.Map.Entry; +/** + * Options for a Redis vector store record collection. + * + * @param the record type + */ public class RedisJsonVectorStoreRecordCollectionOptions implements VectorStoreRecordCollectionOptions { private final Class recordClass; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordMapper.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordMapper.java index c71389cf..ecb449fb 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordMapper.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisJsonVectorStoreRecordMapper.java @@ -17,6 +17,10 @@ import java.util.function.Function; import javax.annotation.Nullable; +/** + * A mapper to convert between a record and a Redis JSON storage model. + * @param the record type + */ public class RedisJsonVectorStoreRecordMapper extends VectorStoreRecordMapper> { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStore.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStore.java index b9bf20b9..aa901e02 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStore.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStore.java @@ -14,6 +14,9 @@ import reactor.core.publisher.Mono; import redis.clients.jedis.JedisPooled; +/** + * Represents a Redis vector store. + */ public class RedisVectorStore implements VectorStore { private final JedisPooled client; @@ -36,6 +39,9 @@ public RedisVectorStore(@Nonnull JedisPooled client, * Gets a collection from the vector store. * * @param collectionName The name of the collection. + * @param options The options for the collection. + * @param The type of key in the collection. + * @param The type of record in the collection. * @return The collection. */ public VectorStoreRecordCollection getCollection( @@ -82,12 +88,16 @@ public Mono> getCollectionNamesAsync() { } /** - * Builder for the Redis vector store. + * Create a builder for the Redis vector store. + * @return A new builder */ public static Builder builder() { return new Builder(); } + /** + * Builder for the Redis vector store. + */ public static class Builder implements SemanticKernelBuilder { @Nullable diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionCreateMapping.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionCreateMapping.java index a9d7a329..46a4c09b 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionCreateMapping.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionCreateMapping.java @@ -16,6 +16,9 @@ import com.microsoft.semantickernel.exceptions.SKException; import redis.clients.jedis.search.Schema; +/** + * Maps a vector store record collection to a Redis schema. + */ public class RedisVectorStoreCollectionCreateMapping { private static final HashSet> supportedFilterableNumericTypes = new HashSet<>( Arrays.asList( @@ -72,6 +75,13 @@ private static String getRedisPath(String name, boolean withRedisJsonRoot) { return withRedisJsonRoot ? "$." + name : name; } + /** + * Maps a vector store record collection to a Redis schema. + * + * @param fields the fields + * @param storageType the Redis storage type + * @return the schema + */ public static Schema mapToSchema(List fields, RedisStorageType storageType) { Schema schema = new Schema(); diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionSearchMapping.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionSearchMapping.java index 0b792996..de51b8e7 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionSearchMapping.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreCollectionSearchMapping.java @@ -18,6 +18,9 @@ import redis.clients.jedis.args.SortingOrder; import redis.clients.jedis.search.FTSearchParams; +/** + * A mapping for searching a collection of vector records in Redis. + */ public class RedisVectorStoreCollectionSearchMapping implements FilterMapping { static final String VECTOR_SCORE_FIELD = "vector_score"; @@ -33,6 +36,14 @@ static RedisVectorStoreCollectionSearchMapping getInstance() { return RedisVectorStoreCollectionSearchMappingHolder.INSTANCE; } + /** + * Builds a query for searching a collection of vector records in Redis. + * @param vector the vector to search for + * @param options the search options + * @param recordDefinition the record definition + * @param storageType the storage type + * @return the query and search parameters + */ public Pair buildQuery(List vector, VectorSearchOptions options, VectorStoreRecordDefinition recordDefinition, @@ -79,6 +90,11 @@ public Pair buildQuery(List vector, return Pair.of(knn, searchParams); } + /** + * Converts a list of floats to a byte array. + * @param embeddings the embeddings + * @return the byte array + */ public static byte[] convertListToByteArray(List embeddings) { ByteBuffer bytes = ByteBuffer.allocate(Float.BYTES * embeddings.size()); bytes.order(ByteOrder.LITTLE_ENDIAN); @@ -86,6 +102,11 @@ public static byte[] convertListToByteArray(List embeddings) { return bytes.array(); } + /** + * Converts a byte array to a list of floats. + * @param bytes the byte array + * @return the list of floats + */ public static List convertByteArrayToList(byte[] bytes) { ByteBuffer buffer = ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN); List embeddings = new java.util.ArrayList<>(); diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreOptions.java index 2f09e930..338cf193 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreOptions.java @@ -6,6 +6,9 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; +/** + * Options for the Redis vector store. + */ public class RedisVectorStoreOptions { @Nullable private final RedisVectorStoreRecordCollectionFactory vectorStoreRecordCollectionFactory; @@ -15,7 +18,7 @@ public class RedisVectorStoreOptions { /** * Creates a new instance of the Redis vector store options. - * + * @param storageType The storage type. * @param vectorStoreRecordCollectionFactory The vector store record collection factory. */ public RedisVectorStoreOptions( diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreRecordCollectionFactory.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreRecordCollectionFactory.java index 0752493c..f47fb4c8 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreRecordCollectionFactory.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/redis/RedisVectorStoreRecordCollectionFactory.java @@ -17,6 +17,7 @@ public interface RedisVectorStoreRecordCollectionFactory { * @param collectionName The name of the collection. * @param recordClass The class type of the record. * @param recordDefinition The record definition. + * @param The type of the records in the collection. * @return The collection. */ VectorStoreRecordCollection createVectorStoreRecordCollection( diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/sqlite/SQLiteVectorStoreQueryProvider.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/sqlite/SQLiteVectorStoreQueryProvider.java index 35d38150..b9776f19 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/sqlite/SQLiteVectorStoreQueryProvider.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/sqlite/SQLiteVectorStoreQueryProvider.java @@ -22,6 +22,9 @@ import java.util.List; import java.util.stream.Collectors; +/** + * A query provider for a vector store in SQLite. + */ public class SQLiteVectorStoreQueryProvider extends JDBCVectorStoreQueryProvider implements SQLVectorStoreQueryProvider { @@ -110,6 +113,9 @@ public void upsertRecords(String collectionName, List records, } } + /** + * A builder for {@code SQLiteVectorStoreQueryProvider}. + */ public static class Builder extends JDBCVectorStoreQueryProvider.Builder { private DataSource dataSource; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStore.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStore.java index 0cf1044a..dbb56da4 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStore.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStore.java @@ -13,10 +13,18 @@ import com.microsoft.semantickernel.exceptions.SKException; import reactor.core.publisher.Mono; +/** + * Represents a volatile vector store. + * A volatile vector store is an in-memory vector store + * that does not persist data. + */ public class VolatileVectorStore implements VectorStore { private final Map> collections; + /** + * Creates a new instance of the volatile vector store. + */ public VolatileVectorStore() { this.collections = new ConcurrentHashMap<>(); } diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreCollectionSearchMapping.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreCollectionSearchMapping.java index 79a1326d..3a5eab6a 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreCollectionSearchMapping.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreCollectionSearchMapping.java @@ -13,8 +13,21 @@ import java.util.List; import java.util.stream.Collectors; +/** + * Provides methods to filter records based on a {@link VectorSearchFilter}. + */ public class VolatileVectorStoreCollectionSearchMapping { + /** + * Filters the records based on the given {@link VectorSearchFilter}. + * + * @param records The records to filter. + * @param filter The filter to apply. + * @param recordDefinition The record definition. + * @param objectMapper The object mapper. + * @param The record type. + * @return The filtered records. + */ public static List filterRecords(List records, VectorSearchFilter filter, VectorStoreRecordDefinition recordDefinition, ObjectMapper objectMapper) { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollection.java index 3b40c16b..7d6031d4 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollection.java @@ -32,6 +32,11 @@ import reactor.core.publisher.Mono; import reactor.core.scheduler.Schedulers; +/** + * Represents a volatile vector store record collection. + * + * @param The type of record in the collection. + */ public class VolatileVectorStoreRecordCollection implements VectorStoreRecordCollection { @@ -43,6 +48,12 @@ public class VolatileVectorStoreRecordCollection implements private final VectorStoreRecordDefinition recordDefinition; private final ObjectMapper objectMapper; + /** + * Creates a new instance of the volatile vector store record collection. + * + * @param collectionName The name of the collection. + * @param options The options for the collection. + */ public VolatileVectorStoreRecordCollection(String collectionName, VolatileVectorStoreRecordCollectionOptions options) { this.collectionName = collectionName; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollectionOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollectionOptions.java index 592e7653..0b5779df 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollectionOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/VolatileVectorStoreRecordCollectionOptions.java @@ -9,6 +9,11 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; +/** + * Represents the options for a volatile vector store record collection. + * + * @param the record type + */ public class VolatileVectorStoreRecordCollectionOptions implements VectorStoreRecordCollectionOptions { private final Class recordClass; @@ -22,6 +27,7 @@ public class VolatileVectorStoreRecordCollectionOptions * * @param recordClass The record class. * @param recordDefinition The record definition. + * @param objectMapper An instanc of Jackson ObjectMapper. */ @SuppressFBWarnings("EI_EXPOSE_REP2") // ObjectMapper only has package visibility public VolatileVectorStoreRecordCollectionOptions(@Nonnull Class recordClass, diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/AnyTagEqualToFilterClause.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/AnyTagEqualToFilterClause.java index ab1a8754..81eea80b 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/AnyTagEqualToFilterClause.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/AnyTagEqualToFilterClause.java @@ -1,11 +1,19 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.data.filter; +/** + * A filter clause that filters on any tag equal to a value. + */ public class AnyTagEqualToFilterClause implements FilterClause { private final String fieldName; private final Object value; + /** + * Creates a new instance of the AnyTagEqualToFilterClause class. + * @param fieldName The field name to filter on. + * @param value The value to filter on. + */ public AnyTagEqualToFilterClause(String fieldName, Object value) { this.fieldName = fieldName; this.value = value; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/EqualToFilterClause.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/EqualToFilterClause.java index 68b0b5ec..c75b04dc 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/EqualToFilterClause.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/EqualToFilterClause.java @@ -1,10 +1,19 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.data.filter; +/** + * A filter clause that filters on a field equal to a value. + */ public class EqualToFilterClause implements FilterClause { private final String fieldName; private final Object value; + /** + * Initializes a new instance of the EqualToFilterClause class. + * + * @param fieldName The field name to filter on. + * @param value The value to filter on. + */ public EqualToFilterClause(String fieldName, Object value) { this.fieldName = fieldName; this.value = value; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/FilterClause.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/FilterClause.java index 2c309922..8e9a6e60 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/FilterClause.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/filter/FilterClause.java @@ -1,5 +1,8 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.data.filter; +/** + * A filter clause for a query. + */ public interface FilterClause { } diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorOperations.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorOperations.java index 485c16c3..4f90faa8 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorOperations.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorOperations.java @@ -17,6 +17,9 @@ import java.util.stream.Collectors; import java.util.stream.Stream; +/** + * Operations for working with vectors. + */ public final class VectorOperations { /** diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchFilter.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchFilter.java index 18a2b7e9..7006135f 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchFilter.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchFilter.java @@ -9,6 +9,9 @@ import java.util.Collections; import java.util.List; +/** + * A vector search filter. + */ public class VectorSearchFilter { /** @@ -22,6 +25,9 @@ public static VectorSearchFilter createDefault() { private final List filterClauses; + /** + * Creates a new instance of the VectorSearchFilter class. + */ public VectorSearchFilter() { this(Collections.emptyList()); } @@ -44,10 +50,18 @@ public List getFilterClauses() { return filterClauses; } + /** + * Creates a {@link Builder} for the VectorSearchFilter class. + * + * @return A new instance of the VectorSearchFilter Builder. + */ public static Builder builder() { return new Builder(); } + /** + * A builder for the VectorSearchFilter class. + */ public static class Builder { private final List filterClauses = new ArrayList<>(); @@ -75,6 +89,11 @@ public Builder anyTagEqualTo(String fieldName, Object value) { return this; } + /** + * Builds the VectorSearchFilter. + * + * @return The VectorSearchFilter. + */ public VectorSearchFilter build() { return new VectorSearchFilter(filterClauses); } diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchResult.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchResult.java index 6e508669..e1f26bee 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchResult.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorSearchResult.java @@ -1,6 +1,10 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.data.vectorsearch; +/** + * Represents a vector search result. + * @param The type of the record. + */ public class VectorSearchResult { private final Record record; private final double score; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizableTextSearch.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizableTextSearch.java index ab7c779e..00046444 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizableTextSearch.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizableTextSearch.java @@ -6,6 +6,11 @@ import java.util.List; +/** + * A vectorizable text search. + * + * @param The record type. + */ public interface VectorizableTextSearch { /** * Vectorizable text search. This method searches for records that are similar to the given text. diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizedSearch.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizedSearch.java index 1c9274a9..59010730 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizedSearch.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorsearch/VectorizedSearch.java @@ -6,6 +6,11 @@ import java.util.List; +/** + * A vectorized search. + * + * @param The record type. + */ public interface VectorizedSearch { /** diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStore.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStore.java index 26e20c15..de548be4 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStore.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStore.java @@ -16,6 +16,8 @@ public interface VectorStore { * * @param collectionName The name of the collection. * @param options The options for the collection. + * @param The key type. + * @param The record type. * @return The collection. */ VectorStoreRecordCollection getCollection( diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollection.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollection.java index 38655fbc..1eb6124d 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollection.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollection.java @@ -8,6 +8,12 @@ import java.util.List; import reactor.core.publisher.Mono; +/** + * Represents a collection of records in a vector store. + * + * @param The type of the key of the records in the collection. + * @param The type of the records in the collection. + */ public interface VectorStoreRecordCollection extends VectorizedSearch { /** diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollectionOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollectionOptions.java index 5782b7b0..926bd984 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollectionOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordCollectionOptions.java @@ -3,6 +3,12 @@ import com.microsoft.semantickernel.data.vectorstorage.definition.VectorStoreRecordDefinition; +/** + * Represents the options for a collection of vector store records. + * + * @param the type of the key + * @param the type of the record + */ public interface VectorStoreRecordCollectionOptions { /** * Gets the key class. diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordMapper.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordMapper.java index 8e3e7ae2..85b14d61 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordMapper.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/VectorStoreRecordMapper.java @@ -64,6 +64,7 @@ public StorageModel mapRecordToStorageModel(Record record) { * Converts a storage model to a record. * * @param storageModel the storage model to convert + * @param options the options * @return the record */ public Record mapStorageModelToRecord(StorageModel storageModel, GetRecordOptions options) { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordData.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordData.java index b27423ce..532cffdb 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordData.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordData.java @@ -16,16 +16,19 @@ * Storage name of the field. * This value is only used when JSON Serialization using Jackson is not supported in a VectorStore. * When Jackson is supported, @JsonProperty should be used to specify an alternate field name in the storage database. + * @return The storage name of the field. */ String storageName() default ""; /** * Whether the field is filterable. + * @return {@code true} if the field is filterable. */ boolean isFilterable() default false; /** * Whether the field is full text searchable. + * @return {@code true} if the field is full text searchable. */ boolean isFullTextSearchable() default false; -} \ No newline at end of file +} diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordKey.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordKey.java index cd462dfc..8f8c98a7 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordKey.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordKey.java @@ -14,6 +14,7 @@ public @interface VectorStoreRecordKey { /** * Storage name of the field. + * @return The storage name of the field. */ String storageName() default ""; } diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordVector.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordVector.java index 91d5571d..90128b41 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordVector.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/annotations/VectorStoreRecordVector.java @@ -19,22 +19,26 @@ /** * Number of dimensions in the vector. + * @return The number of dimensions in the vector. */ int dimensions(); /** * Storage name of the field. + * @return The storage name of the field. */ String storageName() default ""; /** * Type of index to be used for the vector. + * @return The type of index to be used for the vector. */ @Nullable IndexKind indexKind() default IndexKind.UNDEFINED; /** * Distance function to be used for to compute the distance between vectors. + * @return The distance function to be used for to compute the distance between vectors. */ @Nullable DistanceFunction distanceFunction() default DistanceFunction.UNDEFINED; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/DistanceFunction.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/DistanceFunction.java index 8b2577a7..1512db52 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/DistanceFunction.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/DistanceFunction.java @@ -1,6 +1,9 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.data.vectorstorage.definition; +/** + * Distance functions for vector storage. + */ public enum DistanceFunction { /** * Cosine (angular) similarity function. @@ -29,6 +32,10 @@ public enum DistanceFunction { this.value = value; } + /** + * Gets the function name. + * @return The function name. + */ public String getValue() { return value; } diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/IndexKind.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/IndexKind.java index cda1598b..4372d651 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/IndexKind.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/IndexKind.java @@ -1,6 +1,9 @@ // Copyright (c) Microsoft. All rights reserved. package com.microsoft.semantickernel.data.vectorstorage.definition; +/** + * Represents the kind of index to use for a vector store. + */ public enum IndexKind { /** * Hierarchical Navigable Small World, which performs an approximate nearest neighbour (ANN) search. @@ -31,6 +34,11 @@ public enum IndexKind { this.value = value; } + /** + * Gets the string value of the index kind. + * + * @return the string value of the index kind + */ public String getValue() { return value; } diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDataField.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDataField.java index 76a47187..9e5aea11 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDataField.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDataField.java @@ -4,10 +4,17 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; +/** + * Represents a data field in a record. + */ public class VectorStoreRecordDataField extends VectorStoreRecordField { private final boolean isFilterable; private final boolean isFullTextSearchable; + /** + * Create a builder for the VectorStoreRecordDataField class. + * @return a new instance of the builder + */ public static Builder builder() { return new Builder(); } @@ -19,6 +26,7 @@ public static Builder builder() { * @param storageName the storage name of the field * @param fieldType the field type * @param isFilterable a value indicating whether the field is filterable + * @param isFullTextSearchable a value indicating whether the field is full text searchable */ public VectorStoreRecordDataField( @Nonnull String name, @@ -49,6 +57,9 @@ public boolean isFullTextSearchable() { return isFullTextSearchable; } + /** + * Builder for the VectorStoreRecordDataField class. + */ public static class Builder extends VectorStoreRecordField.Builder { private boolean isFilterable; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDefinition.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDefinition.java index 6b72d529..54b2bf2b 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDefinition.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordDefinition.java @@ -30,10 +30,18 @@ public class VectorStoreRecordDefinition { private final List allFields; private final Map allFieldsMap; + /** + * Gets the key field in the record definition. + * @return VectorStoreRecordKeyField + */ public VectorStoreRecordKeyField getKeyField() { return keyField; } + /** + * Gets the data fields in the record definition. + * @return List of VectorStoreRecordDataField + */ public List getDataFields() { return dataFields; } @@ -212,6 +220,12 @@ public static VectorStoreRecordDefinition fromRecordClass(Class recordClass) return checkFields(keyFields, dataFields, vectorFields); } + /** + * Validate that the record class contains only supported field types. + * @param fields The declared fields in the record class. + * @param supportedTypes The supported field types. + * @throws IllegalArgumentException if unsupported field types are found. + */ public static void validateSupportedTypes(List fields, Set> supportedTypes) { Set> unsupportedTypes = new HashSet<>(); diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordField.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordField.java index 9d85f2c9..0ba377af 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordField.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordField.java @@ -19,6 +19,8 @@ public class VectorStoreRecordField { * Creates a new instance of the VectorStoreRecordField class. * * @param name the name of the field + * @param storageName the storage name of the field + * @param fieldType the field type */ public VectorStoreRecordField( @Nonnull String name, @@ -66,6 +68,11 @@ public Class getFieldType() { return fieldType; } + /** + * A builder for the VectorStoreRecordField class. + * @param the type of the field + * @param the type of the builder + */ public abstract static class Builder> implements SemanticKernelBuilder { diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordKeyField.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordKeyField.java index b255e561..9e2a70e7 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordKeyField.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordKeyField.java @@ -5,6 +5,11 @@ * Represents the key field in a record. */ public class VectorStoreRecordKeyField extends VectorStoreRecordField { + + /** + * Create a builder for the VectorStoreRecordKeyField class. + * @return a new instance of the builder + */ public static Builder builder() { return new Builder(); } @@ -20,6 +25,9 @@ public VectorStoreRecordKeyField(String name, String storageName, Class type) super(name, storageName, type); } + /** + * A builder for the VectorStoreRecordKeyField class. + */ public static class Builder extends VectorStoreRecordField.Builder { @Override diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordVectorField.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordVectorField.java index e5b94898..00b7627a 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordVectorField.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/definition/VectorStoreRecordVectorField.java @@ -12,6 +12,10 @@ public class VectorStoreRecordVectorField extends VectorStoreRecordField { private final IndexKind indexKind; private final DistanceFunction distanceFunction; + /** + * Create a builder for the VectorStoreRecordVectorField class. + * @return a new instance of the builder + */ public static Builder builder() { return new Builder(); } @@ -67,6 +71,9 @@ public DistanceFunction getDistanceFunction() { return distanceFunction; } + /** + * A builder for the VectorStoreRecordVectorField class. + */ public static class Builder extends VectorStoreRecordField.Builder { private int dimensions; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/GetRecordOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/GetRecordOptions.java index 444d4533..74d2b065 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/GetRecordOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/GetRecordOptions.java @@ -12,12 +12,21 @@ public class GetRecordOptions { private final boolean wildcardKeyMatching; + /** + * Creates a new instance of the GetRecordOptions class. + * @param includeVectors A value indicating whether to include vectors in a response. + */ public GetRecordOptions( boolean includeVectors) { this.includeVectors = includeVectors; this.wildcardKeyMatching = false; } + /** + * Creates a new instance of the GetRecordOptions class. + * @param includeVectors A value indicating whether to include vectors in a response. + * @param wildcardKeyMatching A value indicating whether to use wildcard key matching. + */ public GetRecordOptions( boolean includeVectors, boolean wildcardKeyMatching) { @@ -25,6 +34,10 @@ public GetRecordOptions( this.wildcardKeyMatching = wildcardKeyMatching; } + /** + * Gets whether to use wildcard key matching. + * @return {@code true} if wildcard key matching is used; otherwise, {@code false}. + */ public boolean isWildcardKeyMatching() { return wildcardKeyMatching; } @@ -38,6 +51,9 @@ public static Builder builder() { return new Builder(); } + /** + * A builder for GetRecordOptions. + */ public static class Builder implements SemanticKernelBuilder { private boolean includeVectors; diff --git a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/VectorSearchOptions.java b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/VectorSearchOptions.java index 28c0a6d7..35fe2f01 100644 --- a/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/VectorSearchOptions.java +++ b/semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/vectorstorage/options/VectorSearchOptions.java @@ -6,8 +6,14 @@ import javax.annotation.Nullable; +/** + * Options for a vector search. + */ public class VectorSearchOptions { + /** + * The default limit of the number of results to return. + */ public static final int DEFAULT_RESULT_LIMIT = 3; /** @@ -29,6 +35,14 @@ public static VectorSearchOptions createDefault(String vectorFieldName) { private final int offset; private final boolean includeVectors; + /** + * Creates a new instance of the VectorSearchOptions class. + * @param vectorSearchFilter The vector search filter. + * @param vectorFieldName The name of the vector field. + * @param limit The limit of the number of results to return. + * @param offset The offset of the results to return. + * @param includeVectors A value indicating whether to include vectors in the results. + */ public VectorSearchOptions(VectorSearchFilter vectorSearchFilter, String vectorFieldName, int limit, int offset, boolean includeVectors) { this.vectorSearchFilter = vectorSearchFilter; @@ -94,6 +108,9 @@ public static Builder builder() { return new Builder(); } + /** + * A builder for the VectorSearchOptions class. + */ public static class Builder implements SemanticKernelBuilder { private VectorSearchFilter vectorSearchFilter; private String vectorFieldName; @@ -101,32 +118,60 @@ public static class Builder implements SemanticKernelBuilder