Merge branch 'main' of https://github.com/microsoft/semantic-kernel-java into jdbc

Author: Milder Hernandez Cagua

BUILD.md

@@ -36,11 +36,11 @@ To build the Semantic Kernel for Java, you will need:
 
 1. Clone this repository
 
-        git clone -b java-v1 https://github.com/microsoft/semantic-kernel/
+        git clone https://github.com/microsoft/semantic-kernel-java
 
 2. Build the project with the Maven Wrapper
 
-        cd semantic-kernel/java
+        cd semantic-kernel
         ./mvnw install
 
 3. (Optional) To run a FULL build including static analysis and end-to-end tests that might require a valid OpenAI key,
@@ -104,8 +104,7 @@ Also ensure that:
 - All new code is covered by unit tests
 - All new code is covered by integration tests
 
-Once your proposal is ready, submit a pull request to the `java-v1` branch. The pull request will be reviewed by the
-project maintainers.
+Once your proposal is ready, submit a pull request. The pull request will be reviewed by the project maintainers.
 
 Make sure your pull request has an objective title and a clear description explaining the problem and solution.
 

CHANGELOG.md

@@ -1,3 +1,15 @@
+# 1.2.1
+
+- Fix bug in `FunctionInvocation` not using per-invocation type conversion when calling `withResultType`.
+- Fix bug in Global Hooks not being invoked under certain circumstances.
+- Add fluent returns to `ChatHistory` `addXMessage` methods.
+- Add user agent opt-out for OpenAI requests by setting the property `semantic-kernel.useragent-disable` to `true`.
+- Add several convenience `invokePromptAsync` methods to `Kernel`.
+
+#### Non-API Changes
+
+- Add custom type Conversion example, CustomTypes_Example
+
 # 1.2.0
 
 - Add ability to use image_url as content for a OpenAi chat completion

README.md

@@ -5,12 +5,12 @@
 
 # Semantic Kernel for Java
 
-Welcome to the Semantic Kernel for Java. For detailed documentation, visit [Microsoft Learn](https://learn.microsoft.com/en-us/semantic-kernel/overview/?tabs=Java).
+Welcome to the Semantic Kernel for Java. For detailed documentation, visit [Microsoft Learn](https://learn.microsoft.com/en-us/semantic-kernel/overview/?tabs=Java&pivots=programming-language-java).
 
 [Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) is an SDK that integrates Large Language Models (LLMs) like [OpenAI](https://platform.openai.com/docs/introduction), [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service), and [Hugging Face](https://huggingface.co/)
-with conventional programming languages like C#, Python, and Java. Semantic Kernel achieves this by allowing you to define [plugins](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins) that can be chained together in just a [few lines of code](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chaining-functions?tabs=Java#using-the-runasync-method-to-simplify-your-code).
+with conventional programming languages like C#, Python, and Java. Semantic Kernel achieves this by allowing you to define [plugins](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins??tabs=Java&pivots=programming-language-java) that can be chained together in just a [few lines of code](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chaining-functions?tabs=Java&pivots=programming-language-java#using-the-runasync-method-to-simplify-your-code).
 
-What makes Semantic Kernel _special_, however, is its ability to _automatically_ orchestrate plugins with AI. With Semantic Kernel [planners](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner), you can ask an LLM to generate a plan that achieves a user's unique goal. Afterwards, Semantic Kernel will execute the plan for the user.
+What makes Semantic Kernel _special_, however, is its ability to _automatically_ orchestrate plugins with AI. With Semantic Kernel [planners](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner?tabs=Java&pivots=programming-language-java), you can ask an LLM to generate a plan that achieves a user's unique goal. Afterwards, Semantic Kernel will execute the plan for the user.
 
 For C#, Python and other language support, see [microsoft/semantic-kernel](https://github.com/microsoft/semantic-kernel).
 
@@ -23,20 +23,20 @@ For C#, Python and other language support, see [microsoft/semantic-kernel](https
 The quickest way to get started with the basics is to get an API key from either OpenAI or Azure OpenAI and to run one of the Java console applications/scripts below.
 
 1. Clone the repository: `git clone https://github.com/microsoft/semantic-kernel-java.git`
-2. Follow the instructions [Start learning how to use Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/get-started/quick-start-guide?tabs=Java).
+2. Follow the instructions [Start learning how to use Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/get-started/quick-start-guide?tabs=Java&pivots=programming-language-java).
 
 ## Documentation: Learning how to use Semantic Kernel
 
 The fastest way to learn how to use Semantic Kernel is with our walkthroughs
 on our Learn site.
 
-1. 📖 [Overview of the kernel](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/?tabs=Java)
-1. 🔌 [Understanding AI plugins](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins?tabs=Java)
-1. 👄 [Creating semantic functions](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/semantic-functions?tabs=Java)
-1. 💽 [Creating native functions](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/native-functions?tabs=Java)
-1. ⛓️ [Chaining functions together](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chaining-functions?tabs=Java)
-1. 🤖 [Auto create plans with planner](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner?tabs=Java)
-1. 💡 [Create and run a ChatGPT plugin](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chatgpt-plugins?tabs=Java)
+1. 📖 [Overview of the kernel](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/?tabs=Java&pivots=programming-language-java)
+1. 🔌 [Understanding AI plugins](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins?tabs=Java&pivots=programming-language-java)
+1. 👄 [Creating semantic functions](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/semantic-functions?tabs=Java&pivots=programming-language-java)
+1. 💽 [Creating native functions](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/native-functions?tabs=Java&pivots=programming-language-java)
+1. ⛓️ [Chaining functions together](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chaining-functions?tabs=Java&pivots=programming-language-java)
+1. 🤖 [Auto create plans with planner](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner?tabs=Java&pivots=programming-language-java)
+1. 💡 [Create and run a ChatGPT plugin](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chatgpt-plugins?tabs=Java&pivots=programming-language-java)
 
 ## Join the community
 
@@ -50,8 +50,8 @@ in a different direction, but also to consider the impact on the larger ecosyste
 
 To learn more and get started:
 
-- Read the [documentation](https://learn.microsoft.com/en-us/semantic-kernel/overview/?tabs=Java)
-- Learn how to [contribute](https://learn.microsoft.com/en-us/semantic-kernel/get-started/contributing) to the project
+- Read the [documentation](https://learn.microsoft.com/en-us/semantic-kernel/overview/?tabs=Java&pivots=programming-language-java)
+- Learn how to [contribute](https://learn.microsoft.com/en-us/semantic-kernel/get-started/contributing?tabs=Java&pivots=programming-language-java) to the project
 - Join the [Discord community](https://aka.ms/SKDiscord)
 - Attend [regular office hours and SK community events](COMMUNITY.md)
 - Follow the team on our [blog](https://aka.ms/sk/blog)

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/OpenAiService.java

@@ -1,23 +1,22 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.aiservices.openai;
 
-import com.azure.ai.openai.OpenAIAsyncClient;
 import com.microsoft.semantickernel.services.AIService;
 import javax.annotation.Nullable;
 
 /**
  * Provides OpenAI service.
  */
-public abstract class OpenAiService implements AIService {
+public abstract class OpenAiService<Client> implements AIService {
 
-    private final OpenAIAsyncClient client;
+    private final Client client;
     @Nullable
     private final String serviceId;
     private final String modelId;
     private final String deploymentName;
 
     protected OpenAiService(
-        OpenAIAsyncClient client,
+        Client client,
         @Nullable String serviceId,
         String modelId,
         String deploymentName) {
@@ -39,7 +38,7 @@ public String getServiceId() {
         return serviceId;
     }
 
-    protected OpenAIAsyncClient getClient() {
+    protected Client getClient() {
         return client;
     }
 

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiAudioToTextService.java

@@ -18,7 +18,7 @@
 /**
  * Provides OpenAi implementation of audio to text service.
  */
-public class OpenAiAudioToTextService extends OpenAiService implements AudioToTextService {
+public class OpenAiAudioToTextService extends OpenAiService<OpenAIAsyncClient> implements AudioToTextService {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(OpenAiAudioToTextService.class);
 

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/audio/OpenAiTextToAudioService.java

@@ -17,7 +17,7 @@
 /**
  * Provides OpenAi implementation of text to audio service.
  */
-public class OpenAiTextToAudioService extends OpenAiService implements TextToAudioService {
+public class OpenAiTextToAudioService extends OpenAiService<OpenAIAsyncClient> implements TextToAudioService {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(OpenAiTextToAudioService.class);
 

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/chatcompletion/OpenAIChatCompletion.java

@@ -79,7 +79,7 @@
 /**
  * OpenAI chat completion service.
  */
-public class OpenAIChatCompletion extends OpenAiService implements ChatCompletionService {
+public class OpenAIChatCompletion extends OpenAiService<OpenAIAsyncClient> implements ChatCompletionService {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(OpenAIChatCompletion.class);
 
@@ -311,6 +311,7 @@ private Mono<ChatMessages> internalChatMessageContentsAsync(
 
         ChatCompletionsOptions options = executeHook(
             invocationContext,
+            kernel,
             new PreChatCompletionEvent(
                 getCompletionsOptions(
                     this,
@@ -349,7 +350,7 @@ private Mono<ChatMessages> internalChatMessageContentsAsync(
                     .collect(Collectors.toList());
 
                 // execute post chat completion hook
-                executeHook(invocationContext, new PostChatCompletionEvent(completions));
+                executeHook(invocationContext, kernel, new PostChatCompletionEvent(completions));
 
                 // Just return the result:
                 // If we don't want to attempt to invoke any functions
@@ -517,11 +518,12 @@ private Mono<FunctionResult<String>> invokeFunctionTool(
                 pluginName,
                 openAIFunctionToolCall.getFunctionName());
 
-            PreToolCallEvent hookResult = executeHook(invocationContext, new PreToolCallEvent(
-                openAIFunctionToolCall.getFunctionName(),
-                openAIFunctionToolCall.getArguments(),
-                function,
-                contextVariableTypes));
+            PreToolCallEvent hookResult = executeHook(invocationContext, kernel,
+                new PreToolCallEvent(
+                    openAIFunctionToolCall.getFunctionName(),
+                    openAIFunctionToolCall.getArguments(),
+                    function,
+                    contextVariableTypes));
 
             function = hookResult.getFunction();
             KernelFunctionArguments arguments = hookResult.getArguments();
@@ -537,12 +539,21 @@ private Mono<FunctionResult<String>> invokeFunctionTool(
 
     private static <T extends KernelHookEvent> T executeHook(
         @Nullable InvocationContext invocationContext,
+        @Nullable Kernel kernel,
         T event) {
-        KernelHooks kernelHooks = invocationContext != null
-            && invocationContext.getKernelHooks() != null
-                ? invocationContext.getKernelHooks()
-                : new KernelHooks();
-
+        KernelHooks kernelHooks = null;
+        if (kernel == null) {
+            if (invocationContext != null) {
+                kernelHooks = invocationContext.getKernelHooks();
+            }
+        } else {
+            kernelHooks = KernelHooks.merge(
+                kernel.getGlobalKernelHooks(),
+                invocationContext != null ? invocationContext.getKernelHooks() : null);
+        }
+        if (kernelHooks == null) {
+            return event;
+        }
         return kernelHooks.executeHooks(event);
     }
 
@@ -1044,7 +1055,7 @@ static ChatRequestMessage getChatRequestMessage(
     /**
      * Builder for creating a new instance of {@link OpenAIChatCompletion}.
      */
-    public static class Builder extends OpenAiServiceBuilder<OpenAIChatCompletion, Builder> {
+    public static class Builder extends OpenAiServiceBuilder<OpenAIAsyncClient, OpenAIChatCompletion, Builder> {
 
         @Override
         public OpenAIChatCompletion build() {

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/implementation/OpenAIRequestSettings.java

@@ -20,16 +20,26 @@ public final class OpenAIRequestSettings {
 
     private static final String SEMANTIC_KERNEL_VERSION_PROPERTY_NAME = "semantic-kernel.version";
     private static final String SEMANTIC_KERNEL_VERSION_PROPERTIES_FILE = "semantic-kernel-version.properties";
-    private static final String useragent;
 
+    private static final String useragent;
     private static final String header;
 
+    public static final String SEMANTIC_KERNEL_DISABLE_USERAGENT_PROPERTY = "semantic-kernel.useragent-disable";
+
+    private static final boolean disabled;
+
     static {
+        disabled = isDisabled();
         String version = loadVersion();
         useragent = "semantic-kernel-java/" + version;
         header = "java/" + version;
     }
 
+    private static boolean isDisabled() {
+        return Boolean.parseBoolean(
+            System.getProperty(SEMANTIC_KERNEL_DISABLE_USERAGENT_PROPERTY, "false"));
+    }
+
     private static String loadVersion() {
 
         String version = "unknown";
@@ -58,9 +68,14 @@ private static String loadVersion() {
      * @return The request options
      */
     public static RequestOptions getRequestOptions() {
-        return new RequestOptions()
+        RequestOptions requestOptions = new RequestOptions();
+
+        if (disabled) {
+            return requestOptions;
+        }
+
+        return requestOptions
             .setHeader(HttpHeaderName.fromString("Semantic-Kernel-Version"), header)
-            .setContext(
-                new Context(UserAgentPolicy.APPEND_USER_AGENT_CONTEXT_KEY, useragent));
+            .setContext(new Context(UserAgentPolicy.APPEND_USER_AGENT_CONTEXT_KEY, useragent));
     }
 }

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/textcompletion/OpenAITextGenerationService.java

@@ -30,7 +30,7 @@
 /**
  * An OpenAI implementation of a {@link TextGenerationService}.
  */
-public class OpenAITextGenerationService extends OpenAiService implements TextGenerationService {
+public class OpenAITextGenerationService extends OpenAiService<OpenAIAsyncClient> implements TextGenerationService {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(OpenAITextGenerationService.class);
 

aiservices/openai/src/main/java/com/microsoft/semantickernel/aiservices/openai/textembedding/OpenAITextEmbeddingGenerationService.java

@@ -23,7 +23,7 @@
  * An OpenAI implementation of a {@link TextEmbeddingGenerationService}.
  *
  */
-public class OpenAITextEmbeddingGenerationService extends OpenAiService
+public class OpenAITextEmbeddingGenerationService extends OpenAiService<OpenAIAsyncClient>
     implements TextEmbeddingGenerationService {
     private static final Logger LOGGER = LoggerFactory
         .getLogger(OpenAITextEmbeddingGenerationService.class);
@@ -87,7 +87,7 @@ protected Mono<List<Embedding>> internalGenerateTextEmbeddingsAsync(List<String>
      * A builder for creating a {@link OpenAITextEmbeddingGenerationService}.
      */
     public static class Builder extends
-        OpenAiServiceBuilder<OpenAITextEmbeddingGenerationService, OpenAITextEmbeddingGenerationService.Builder> {
+        OpenAiServiceBuilder<OpenAIAsyncClient, OpenAITextEmbeddingGenerationService, OpenAITextEmbeddingGenerationService.Builder> {
         private int dimensions = DEFAULT_DIMENSIONS;
 
         /**