Java: Docs

java/README.md

@@ -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
 
@@ -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 `experimental-java` 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.

java/samples/sample-code/README.md

@@ -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=OPENAI ../../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.

java/samples/sample-code/pom.xml

@@ -98,7 +98,7 @@
                     </execution>
                 </executions>
                 <configuration>
-                    <mainClass>com.microsoft.semantickernel.syntaxexamples.${sample}</mainClass>
+                    <mainClass>com.microsoft.semantickernel.samples.syntaxexamples.${sample}</mainClass>
                 </configuration>
             </plugin>
         </plugins>

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

@@ -12,6 +12,15 @@
 
 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 {

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

@@ -11,6 +11,13 @@
 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 {

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

@@ -8,6 +8,12 @@
 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(

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

@@ -22,13 +22,14 @@
 /**
  * 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 {
 

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

@@ -28,6 +28,10 @@
  * 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_RunnningPromptsFromFile {
 

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

@@ -19,6 +19,10 @@
 
 /**
  * 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 {
 

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

@@ -27,6 +27,10 @@
  * 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)

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

@@ -11,9 +11,22 @@
 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) {

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example01_NativeFunctions.java

@@ -2,6 +2,9 @@
 
 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) {

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example02_Pipeline.java

@@ -7,6 +7,9 @@
 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();

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example03_Variables.java

@@ -13,6 +13,10 @@
 
 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 {

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example04_CombineLLMPromptsAndNativeCode.java

@@ -12,11 +12,18 @@
 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) {

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example05_InlineFunctionDefinition.java

@@ -14,6 +14,13 @@
 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();

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example06_TemplateLanguage.java

@@ -10,11 +10,15 @@
 import com.microsoft.semantickernel.orchestration.SKContext;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
 
+/**
+ * Show how to invoke a Native Function written in C#
+ * 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 ========");

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example08_RetryHandler.java

@@ -20,6 +20,13 @@
 
 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 {

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example09_FunctionTypes.java

@@ -14,6 +14,13 @@
 
 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();

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example12_SequentialPlanner.java

@@ -19,6 +19,15 @@
 
 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);

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example13_ConversationSummarySkill.java

@@ -13,6 +13,13 @@
 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 =
             """

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example14_SemanticMemory.java

@@ -14,16 +14,23 @@
 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";
 

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example15_MemorySkill.java

@@ -18,6 +18,13 @@
 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";
 

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example17_ChatGPT.java

@@ -11,8 +11,11 @@
 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 {
 

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example25_ReadOnlyMemoryStore.java

@@ -18,7 +18,7 @@
 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.

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example28_ActionPlanner.java

@@ -8,6 +8,15 @@
 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();