Java: Docs (#3299)

### Motivation and Context  ### Description  ### Contribution Checklist  - [ ] The code builds clean without any errors or warnings - [ ] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [ ] All unit tests pass, and I have added new tests where possible - [ ] I didn't break anyone 😄
2026-10-12 02:19:06 +00:00 · 2023-10-27 14:10:10 +01:00
parent 70bfcbaeb0
commit 11eba8f697
32 changed files with 199 additions and 35 deletions
@@ -14,7 +14,7 @@ and frameworks.

 To run the LLM prompts and semantic functions in this kernel, make sure you have
 an [Open AI API Key](https://openai.com/api/)
-or [Azure Open AI service key](https://learn.microsoft.com/azure/cognitive-services/openai/quickstart?pivots=rest-api).
+or [Azure Open AI service key](https://learn.microsoft.com/azure/cognitive-services/openai/).

 ### Requirements

@@ -27,7 +27,7 @@ To build the Semantic Kernel, you will need:

 1. Clone this repository

-        git clone -b experimental-java https://github.com/microsoft/semantic-kernel/
+        git clone -b java-development https://github.com/microsoft/semantic-kernel/

 2. Build the Semantic Kernel

@@ -86,7 +86,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 `main` branch. The pull request will be reviewed by the
+Once your proposal is ready, submit a pull request to the `java-development` branch. 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.
@@ -34,12 +34,10 @@ They can then be run by:

 # Configuration

-By default, the samples will use the Open AI client, but you can also use the Azure Open AI client.
-
-## Open AI client type
-
-You can define the provider of Open AI (openai.com or Azure), this can be done by setting the `OPENAI_CLIENT_TYPE`
-property or environment variable to either `OPENAI` or `AZURE_OPEN_AI`, i.e.:
+You can define the provider of Open AI by setting the `OPENAI_CLIENT_TYPE`
+property or environment variable to either [`OPENAI`](https://openai.com/api/)
+or [`AZURE_OPEN_AI`](https://learn.microsoft.com/azure/cognitive-services/openai/).
+By default, the samples will use the Open AI client.

 ```shell
 OPENAI_CLIENT_TYPE=OPEN_AI ../../mvnw exec:java -Dsample=Example04_CombineLLMPromptsAndNativeCode
@@ -50,7 +48,7 @@ OR
 ```

 ## Client Settings
-The tests search for the client settings in the following order:
+The samples search for the client settings in the following order:
 1. Properties file whose location is defined by the `CONF_PROPERTIES` property or environment variable.
 1. System properties defined on the command line.
 1. Environment variables.
@@ -12,6 +12,15 @@ import com.microsoft.semantickernel.textcompletion.TextCompletion;

 import java.io.IOException;

+/**
+ * Code for Microsoft Developer Blog
+ * <a href="https://devblogs.microsoft.com/semantic-kernel/introducing-semantic-kernel-for-java/">
+ * Introducing Semantic Kernel for Java</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example99_BlogAnnouncement {

  static {
@@ -11,6 +11,13 @@ import com.microsoft.semantickernel.skilldefinition.annotations.SKFunctionInputA
 import com.microsoft.semantickernel.skilldefinition.annotations.SKFunctionParameters;
 import com.microsoft.semantickernel.textcompletion.TextCompletion;

+/**
+ * Example of a planner which uses native functions.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example_PlanWithNativeFunctions {

    public static void main(String[] args) throws ConfigurationException {
@@ -8,6 +8,12 @@ import com.microsoft.semantickernel.exceptions.ConfigurationException;
 import java.io.File;
 import java.util.List;

+/**
+ * Helper for creating
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class SamplesConfig {

    public static final List<File> DEFAULT_PROPERTIES_LOCATIONS = List.of(
@@ -22,13 +22,14 @@ import java.io.IOException;
 /**
 * Getting started
 * <p>
- * Create a conf.properties file based on the examples files at the root of this
- * module.
- * <p>
 * <a href=
 * "https://learn.microsoft.com/en-us/azure/cognitive-services/openai/quickstart">Get
 * started with Azure OpenAI</a>
 * <a href="https://openai.com/product">Get started with OpenAI</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example00_GettingStarted {

@@ -28,6 +28,10 @@ import java.io.IOException;
 * The repository includes some examples under the <a href=
 * "https://github.com/microsoft/semantic-kernel/tree/main/samples">samples</a>
 * folder.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example02_RunningPromptsFromFile {

@@ -19,6 +19,10 @@ import java.io.IOException;

 /**
 * Define a Semantic Function inline with Java code.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example03_SemanticFunctionInline {

@@ -27,6 +27,10 @@ import java.util.function.Function;
 * key-value store that you can use when running the kernel.
 * The context is local (i.e. in your computer's RAM) and not persisted anywhere
 * beyond the life of the JVM execution.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example04_ContextVariablesChat {
    public static void startChat(Kernel kernel)
@@ -11,9 +11,22 @@ import com.azure.ai.openai.OpenAIAsyncClient;
 import com.microsoft.semantickernel.Kernel;
 import com.microsoft.semantickernel.connectors.ai.openai.util.OpenAIClientProvider;
 import com.microsoft.semantickernel.exceptions.ConfigurationException;
+import com.microsoft.semantickernel.orchestration.SKContext;
+import com.microsoft.semantickernel.planner.actionplanner.Plan;
 import com.microsoft.semantickernel.planner.sequentialplanner.SequentialPlanner;
 import com.microsoft.semantickernel.samples.syntaxexamples.SampleSkillsUtil;

+/**
+ * Sequential Planner
+ * <p>
+ * See <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-sequential-planner/">
+ * Semantic Kernel Planners: Sequential Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example05_UsingThePlanner {

    public static SequentialPlanner getPlanner(Kernel kernel) {
@@ -2,6 +2,9 @@ package com.microsoft.semantickernel.samples.syntaxexamples;

 import com.microsoft.semantickernel.coreskills.TextSkill;

+/**
+ * Demonstrates a native function from the {@code com.microsoft.semantickernel.coreskills} package.
+ */
 public class Example01_NativeFunctions {

    public static void main(String[] args) {
@@ -7,6 +7,9 @@ import com.microsoft.semantickernel.orchestration.SKContext;
 import com.microsoft.semantickernel.skilldefinition.ReadOnlyFunctionCollection;
 import reactor.core.publisher.Mono;

+/**
+ * Demonstrates running a pipeline (a sequence of functions) over some input.
+ */
 public class Example02_Pipeline {
    public static void main(String[] args) {
        Kernel kernel = SKBuilders.kernel().build();
@@ -13,6 +13,10 @@ import reactor.core.publisher.Mono;

 import java.util.Locale;

+/**
+ * Demonstrates running a pipeline (a sequence of functions) on a
+ * {@code com.microsoft.semantickernel.orchestration.SKContext}
+ */
 public class Example03_Variables {

    public static class StaticTextSkill {
@@ -12,11 +12,18 @@ import com.microsoft.semantickernel.skilldefinition.annotations.SKFunctionInputA
 import com.microsoft.semantickernel.textcompletion.TextCompletion;
 import reactor.core.publisher.Mono;

+/**
+ * Demonstrates using skill in combination with LLM prompts.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example04_CombineLLMPromptsAndNativeCode {

  public static class SearchEngineSkill {

-    @DefineSKFunction(description = "Append the day variable", name = "search")
+    @DefineSKFunction(description = "Search for answer", name = "search")
    public Mono<String> search(
        @SKFunctionInputAttribute(description = "Text to search")
        String input) {
@@ -14,6 +14,13 @@ import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
 import java.time.format.FormatStyle;

+/**
+ * Demonstrates using prompt templates to define functions.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example05_InlineFunctionDefinition {
  public static void main(String[] args) throws ConfigurationException {
    OpenAIAsyncClient client = SamplesConfig.getClient();
@@ -10,11 +10,15 @@ import com.microsoft.semantickernel.exceptions.ConfigurationException;
 import com.microsoft.semantickernel.orchestration.SKContext;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;

+/**
+ * Show how to invoke a Native Function written in Java
+ * from a Semantic Function written in natural language
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example06_TemplateLanguage {
-    /// <summary>
-    /// Show how to invoke a Native Function written in C#
-    /// from a Semantic Function written in natural language
-    /// </summary>

    public static void main(String[] args) throws ConfigurationException {
        System.out.println("======== TemplateLanguage ========");
@@ -20,6 +20,13 @@ import java.time.Duration;

 import static com.microsoft.semantickernel.SamplesConfig.DEFAULT_PROPERTIES_LOCATIONS;

+/**
+ * Demonstrates customizing the configuration of the Open AI client.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for endpoint and credential configuration.
+ */
 public class Example08_RetryHandler {

    public static void main(String[] args) throws ConfigurationException {
@@ -14,6 +14,13 @@ import reactor.core.publisher.Mono;

 import java.time.Duration;

+/**
+ * Demonstrates how the Kernel uses functions loaded from skills.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example09_FunctionTypes {
    public static void main(String[] args) throws ConfigurationException {
        OpenAIAsyncClient client = SamplesConfig.getClient();
@@ -19,6 +19,15 @@ import org.slf4j.LoggerFactory;

 import java.util.Set;

+/**
+ * Demonstrates the <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-sequential-planner/">
+ * Sequential Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example12_SequentialPlanner {

    private static final Logger LOGGER = LoggerFactory.getLogger(Example12_SequentialPlanner.class);
@@ -13,6 +13,13 @@ import com.microsoft.semantickernel.skilldefinition.ReadOnlyFunctionCollection;
 import com.microsoft.semantickernel.textcompletion.TextCompletion;
 import reactor.core.publisher.Mono;

+/**
+ * Demonstrate the {@code com.microsoft.semantickernel.coreskills.ConversationSummarySkill}
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example13_ConversationSummarySkill {
    private static final String ChatTranscript =
            """
@@ -14,16 +14,23 @@ import java.util.Map;
 import java.util.stream.Collectors;


-/* The files contain two examples about SK Semantic Memory.
+/**
+ * Demonstrate two examples about SK Semantic Memory:
 *
 * 1. Memory using Azure Cognitive Search.
 * 2. Memory using a custom embedding generator and vector engine.
 *
 * Semantic Memory allows to store your data like traditional DBs,
 * adding the ability to query it using natural language.
+ * <p>
+ * You must <a href=
+ * "https://learn.microsoft.com/en-us/azure/search/search-create-service-portal">
+ * create an Azure Cognitive Search service in the portal</a> to run this example.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
-
-// ReSharper disable once InconsistentNaming
 public class Example14_SemanticMemory {
    private static final String MEMORY_COLLECTION_NAME = "SKGitHub";

@@ -18,6 +18,13 @@ import java.util.List;
 import java.util.stream.Collectors;
 import reactor.core.publisher.Mono;

+/**
+ * Demonstrates saving and retrieving memories.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example15_MemorySkill {
    private static final String MEMORY_COLLECTION_NAME = "aboutMe";

@@ -11,8 +11,11 @@ import com.microsoft.semantickernel.connectors.ai.openai.chatcompletion.OpenAICh
 import com.microsoft.semantickernel.exceptions.ConfigurationException;

 /**
- * The following example shows how to use Semantic Kernel with OpenAI ChatGPT
- * API
+ * Demonstrates the use of Semantic Kernel with OpenAI ChatGPT API
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example17_ChatGPT {

@@ -18,7 +18,7 @@ import java.util.StringJoiner;
 import java.util.stream.Collectors;

 /**
- * This sample provides a custom implementation of {@code MemoryStore} that is read only.
+ * Demonstrates a custom implementation of {@code MemoryStore} that is read only.
 * In this sample, the data is stored in a JSON String and deserialized into an
 * {@code MemoryRecord[]}. For this specific sample, the implementation
 * of {@code MemoryStore}  has a single collection, and thus does not need to be named.
@@ -8,6 +8,15 @@ import com.microsoft.semantickernel.coreskills.TextSkill;
 import com.microsoft.semantickernel.exceptions.ConfigurationException;
 import com.microsoft.semantickernel.planner.actionplanner.ActionPlanner;

+/**
+ * Demonstrates the <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-actionplanner/">
+ * Action Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example28_ActionPlanner {
    public static void main(String[] args) throws ConfigurationException {
        OpenAIAsyncClient client = SamplesConfig.getClient();
@@ -1,15 +1,17 @@
 package com.microsoft.semantickernel.samples.syntaxexamples;

 import com.microsoft.semantickernel.GPT3Tokenizer;
+
+/**
+ * Demonstrates how to count tokens using GPT tokenizer. The number of tokens affects
+ * API calls cost and each model has a maximum amount of tokens it can process and generate.
+ * This example is specific to OpenAI models, which use the tokenization described here:
+ * <a href="https://platform.openai.com/tokenizer">OpenAI tokenizer</a>
+ * If you use Semantic Kernel with other models, the tokenization logic is most probably different,
+ * and you should not use the GPT tokenizer.
+ */
 public class Example29_Tokenizer {
-    /**
-     * This sample shows how to count tokens using GPT tokenizer. The number of tokens affects
-     * API calls cost and each model has a maximum amount of tokens it can process and generate.
-     * This example is specific to OpenAI models, which use the tokenization described here:
-     * <a href="https://platform.openai.com/tokenizer">OpenAI tokenizer</a>
-     * If you use Semantic Kernel with other models, the tokenization logic is most probably different,
-     * and you should not use the GPT tokenizer.
-     */
+
    public static void main(String[] args) {
        // Example 1
        String sentence = "Some text on one line";
@@ -15,7 +15,11 @@ import java.util.function.BiFunction;
 import static com.microsoft.semantickernel.chatcompletion.ChatHistory.AuthorRoles.Assistant;

 /**
- * The following example shows how to use Semantic Kernel with Text Completion as streaming
+ * Demonstrates how to use Semantic Kernel with Text Completion as streaming
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example33_StreamingChat {
    public static void main(String[] args) throws ConfigurationException {
@@ -17,7 +17,13 @@ import java.util.Locale;
 import reactor.core.publisher.Mono;

 /**
- * This example shows how to use Stepwise Planner to create a plan for a given goal.
+ * Demonstrates the <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-stepwise-planner/">
+ * Stepwise Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
 */
 public class Example51_StepwisePlanner {

@@ -3,6 +3,13 @@ package com.microsoft.semantickernel.samples.syntaxexamples;
 import java.util.Arrays;
 import java.util.List;

+/**
+ * Run all the syntax examples.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class RunAll {
    public interface MainMethod {
        void run(String[] args) throws Exception;
@@ -26,7 +33,8 @@ public class RunAll {
                Example25_ReadOnlyMemoryStore::main,
                Example28_ActionPlanner::main,
                Example29_Tokenizer::main,
-                Example33_StreamingChat::main
+                Example33_StreamingChat::main,
+                Example51_StepwisePlanner::main
        );

        mains.forEach(mainMethod -> {
@@ -6,6 +6,9 @@ import com.microsoft.semantickernel.orchestration.SKFunction;

 import java.io.IOException;

+/**
+ * Import a skill from resources.
+ */
 public class Java_Example01_ResourceLoading {

    public static void main(String[] args) throws IOException {
@@ -13,6 +13,17 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;

+/**
+ * Using Sequential Planner to take the input as a question and answer it finding any information needed.
+ * <p>
+ * See <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-sequential-planner/">
+ * Semantic Kernel Planners: Sequential Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class SequentialPlanner_AnswerQuestion {

    public static class InformationFinder {