Java: Add documentation examples

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/documentationexamples/CreatingFunctions.java

@@ -1,4 +1,3 @@
-// Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.samples.documentationexamples;
 
 import java.util.Scanner;
@@ -9,6 +8,9 @@
 import com.azure.core.credential.KeyCredential;
 import com.microsoft.semantickernel.Kernel;
 import com.microsoft.semantickernel.aiservices.openai.chatcompletion.OpenAIChatCompletion;
+import com.microsoft.semantickernel.contextvariables.ContextVariableType;
+import com.microsoft.semantickernel.contextvariables.ContextVariableTypes;
+import com.microsoft.semantickernel.orchestration.InvocationContext;
 import com.microsoft.semantickernel.orchestration.ToolCallBehavior;
 import com.microsoft.semantickernel.plugin.KernelPluginFactory;
 import com.microsoft.semantickernel.samples.plugins.MathPlugin;
@@ -23,51 +25,53 @@ public class CreatingFunctions {
 
     // Only required if AZURE_CLIENT_KEY is set
     private static final String CLIENT_ENDPOINT = System.getenv("CLIENT_ENDPOINT");
-    private static final String MODEL_ID = System.getenv().getOrDefault("MODEL_ID",
-        "gpt-35-turbo-2");
+    private static final String MODEL_ID = System.getenv().getOrDefault("MODEL_ID", "gpt-35-turbo-2");
 
     public static void main(String[] args) {
         System.out.println("======== Prompts ========");
         OpenAIAsyncClient client;
 
         if (AZURE_CLIENT_KEY != null) {
             client = new OpenAIClientBuilder()
-                .credential(new AzureKeyCredential(AZURE_CLIENT_KEY))
-                .endpoint(CLIENT_ENDPOINT)
-                .buildAsyncClient();
+                    .credential(new AzureKeyCredential(AZURE_CLIENT_KEY))
+                    .endpoint(CLIENT_ENDPOINT)
+                    .buildAsyncClient();
         } else {
             client = new OpenAIClientBuilder()
-                .credential(new KeyCredential(CLIENT_KEY))
-                .buildAsyncClient();
+                    .credential(new KeyCredential(CLIENT_KEY))
+                    .buildAsyncClient();
         }
 
+        // <RunNativeFunction>
         Kernel kernel = Kernel.builder()
-            .withAIService(ChatCompletionService.class, ChatCompletionService.builder()
-                .withModelId(MODEL_ID)
-                .withOpenAIAsyncClient(client)
-                .build())
-            .withPlugin(KernelPluginFactory.createFromObject(new MathPlugin(), "MathPlugin"))
-            .build();
+                .withAIService(ChatCompletionService.class, ChatCompletionService.builder()
+                        .withModelId(MODEL_ID)
+                        .withOpenAIAsyncClient(client)
+                        .build())
+                .withPlugin(KernelPluginFactory.createFromObject(new MathPlugin(), "MathPlugin"))
+                .build();
 
         // Test the math plugin
         var answer = kernel
-            .invokeAsync(kernel.getFunction("MathPlugin", "sqrt"))
-            .withArguments(KernelFunctionArguments
-                .builder()
-                .withVariable("number1", 12.0)
-                .build())
-            .block();
+                .invokeAsync(kernel.getFunction("MathPlugin", "sqrt"))
+                .withArguments(KernelFunctionArguments
+                        .builder()
+                        .withVariable("number1", 12.0)
+                        .build())
+                .block();
         System.out.println("The square root of 12 is " + answer.getResult() + ".");
+        // </RunNativeFunction>
 
         // Create chat history
         ChatCompletionService chat = OpenAIChatCompletion.builder()
-            .withModelId(MODEL_ID)
-            .withOpenAIAsyncClient(client)
-            .build();
+                .withModelId(MODEL_ID)
+                .withOpenAIAsyncClient(client)
+                .build();
 
         System.out.println("Chat content:");
         System.out.println("------------------------");
 
+        // <Conversation>
         ChatHistory history = new ChatHistory();
 
         // Start the conversation
@@ -77,26 +81,25 @@ public static void main(String[] args) {
         while (!(userInput = scanner.nextLine()).isEmpty()) {
             history.addUserMessage(userInput);
 
-            reply(chat, history);
-            messageOutput(history);
-        }
-    }
+            // Enable auto function calling
+            var invocationContext = InvocationContext.builder()
+                    .withToolCallBehavior(
+                            ToolCallBehavior.allowAllKernelFunctions(true))
+                    .build();
 
-    private static void reply(ChatCompletionService chatGPT, ChatHistory chatHistory) {
-        // Enable auto function calling
-        var toolCallBehavior = ToolCallBehavior.allowAllKernelFunctions(true);
+            // Get the response from the AI
+            var reply = chat.getChatMessageContentsAsync(history, kernel, invocationContext)
+                    .block();
 
-        var reply = chatGPT.getChatMessageContentsAsync(chatHistory, null, null)
-            .block();
+            String message = reply.get(reply.size() - 1).getContent();
+            System.out.println("Assistant" + " > " + message);
 
-        StringBuilder message = new StringBuilder();
-        reply.forEach(chatMessageContent -> message.append(chatMessageContent.getContent()));
-        chatHistory.addAssistantMessage(message.toString());
-    }
+            // Add the message from the agent to the chat history
+            history.addAssistantMessage(message.toString());
 
-    private static void messageOutput(ChatHistory chatHistory) {
-        var message = chatHistory.getLastMessage().get();
-        System.out.println(message.getAuthorRole() + ": " + message.getContent());
-        System.out.println("------------------------");
+            // Get user input again
+            System.out.print("User > ");
+        }
+        // </Conversation>
     }
 }

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/documentationexamples/Plugin.java

@@ -0,0 +1,126 @@
+// Copyright (c) Microsoft. All rights reserved.
+package com.microsoft.semantickernel.samples.documentationexamples;
+
+import com.azure.ai.openai.OpenAIAsyncClient;
+import com.azure.ai.openai.OpenAIClientBuilder;
+import com.azure.core.credential.AzureKeyCredential;
+import com.azure.core.credential.KeyCredential;
+import com.microsoft.semantickernel.Kernel;
+import com.microsoft.semantickernel.orchestration.InvocationContext;
+import com.microsoft.semantickernel.orchestration.ToolCallBehavior;
+import com.microsoft.semantickernel.plugin.KernelPlugin;
+import com.microsoft.semantickernel.plugin.KernelPluginFactory;
+import com.microsoft.semantickernel.semanticfunctions.annotations.DefineKernelFunction;
+import com.microsoft.semantickernel.semanticfunctions.annotations.KernelFunctionParameter;
+import com.microsoft.semantickernel.services.chatcompletion.ChatCompletionService;
+import com.microsoft.semantickernel.services.chatcompletion.ChatHistory;
+import java.io.InputStream;
+import java.util.Scanner;
+
+public class Plugin {
+    // CLIENT_KEY is for an OpenAI client
+    private static final String CLIENT_KEY = System.getenv("CLIENT_KEY");
+    private static final String AZURE_CLIENT_KEY = System.getenv("AZURE_CLIENT_KEY");
+
+    // Only required if AZURE_CLIENT_KEY is set
+    private static final String CLIENT_ENDPOINT = System.getenv("CLIENT_ENDPOINT");
+    private static final String MODEL_ID = System.getenv().getOrDefault("MODEL_ID", "gpt-35-turbo-2");
+
+    public static void main(String[] args) {
+        System.out.println("======== Plugin ========");
+
+        OpenAIAsyncClient client;
+
+        if (AZURE_CLIENT_KEY != null && CLIENT_ENDPOINT != null) {
+            // <build_client>
+            client = new OpenAIClientBuilder()
+                .credential(new AzureKeyCredential(AZURE_CLIENT_KEY))
+                .endpoint(CLIENT_ENDPOINT)
+                .buildAsyncClient();
+            // </build_client>
+        } else if (CLIENT_KEY != null) {
+            client = new OpenAIClientBuilder()
+                .credential(new KeyCredential(CLIENT_KEY))
+                .buildAsyncClient();
+        } else {
+            System.out.println("No client key found");
+            return;
+        }
+
+
+        // <KernelCreation>
+        ChatCompletionService chatCompletionService = ChatCompletionService.builder()
+            .withModelId(MODEL_ID)
+            .withOpenAIAsyncClient(client)
+            .build();
+
+        KernelPlugin plugin = KernelPluginFactory.createFromObject(
+            new LightPlugin(), "LightPlugin");
+
+        Kernel kernel = Kernel.builder()
+            .withAIService(ChatCompletionService.class, chatCompletionService)
+            .withPlugin(plugin)
+            .build();
+        // </KernelCreation>
+
+        // <Chat>
+        // Create chat history
+        var history = new ChatHistory();
+
+        // Start the conversation
+        System.out.print("User > ");
+        Scanner scanner = new Scanner(System.in);
+        String userInput;
+        while (!(userInput = scanner.nextLine()).isEmpty()) {
+            // Add user input to history
+            history.addUserMessage(userInput);
+
+            // Enable auto function calling
+            var invocationContext = InvocationContext.builder()
+                .withToolCallBehavior(
+                    ToolCallBehavior.allowAllKernelFunctions(true))
+                .build();
+
+            // Get the response from the AI
+            var result = chatCompletionService
+                .getChatMessageContentsAsync(
+                    history,
+                    kernel,
+                    invocationContext)
+                .block();
+
+            String message = result.get(result.size() - 1).getContent();
+            System.out.printf("Assistant > %s%n", message);
+
+            // Add the message from the agent to the chat history
+            history.addAssistantMessage(message);
+        }
+        // </Chat>
+    }
+
+    // <LightPlugin>
+    public static class LightPlugin {
+
+        public boolean isOn = false;
+
+        @DefineKernelFunction(name = "getState", description = "Gets the state of the light.'")
+        String getState() {
+            return isOn ? "on" : "off";
+        }
+
+        @DefineKernelFunction(name = "changeState", description = "Changes the state of the light.'")
+        public String changeState(
+            @KernelFunctionParameter(name = "newState",
+                    description = "The new state of the light, boolean true==on, false==off.",
+                    type = boolean.class) boolean newState) {
+
+            this.isOn = newState;
+            String state = getState();
+
+            // Print the state to the console
+            System.out.printf("[Light is now %s]%n", state);
+            return state;
+        }
+    }
+    // </LightPlugin>
+}