Add detailed Javadoc comments to Llama classes for improved documentation

Author: Jan-Kazlouski-elastic

libs/x-content/src/main/java/org/elasticsearch/xcontent/ConstructingObjectParser.java

@@ -220,6 +220,13 @@ public <T> void declareField(BiConsumer<Value, T> consumer, ContextParser<Contex
         }
     }
 
+    /**
+     * Declare a field that is an array of objects or null. Used to avoid calling the consumer when used with
+     * {@link #optionalConstructorArg()} or {@link #constructorArg()}.
+     * @param consumer Consumer that will be passed as is to the {@link #declareField(BiConsumer, ContextParser, ParseField, ValueType)}.
+     * @param objectParser Parser that will parse the objects in the array, checking for nulls.
+     * @param field Field to declare.
+     */
     @Override
     public <T> void declareObjectArrayOrNull(
         BiConsumer<Value, List<T>> consumer,

x-pack/plugin/inference/src/main/java/org/elasticsearch/xpack/inference/services/llama/action/LlamaActionCreator.java

@@ -32,10 +32,14 @@
 import static org.elasticsearch.core.Strings.format;
 import static org.elasticsearch.xpack.inference.common.Truncator.truncate;
 
+/**
+ * Creates actions for Llama inference requests, handling both embeddings and completions.
+ * This class implements the {@link LlamaActionVisitor} interface to provide specific action creation methods.
+ */
 public class LlamaActionCreator implements LlamaActionVisitor {
 
     private static final String FAILED_TO_SEND_REQUEST_ERROR_MESSAGE = "Failed to send Llama %s request from inference entity id [%s]";
-    public static final String COMPLETION_ERROR_PREFIX = "Llama completions";
+    private static final String COMPLETION_ERROR_PREFIX = "Llama completions";
     private static final String USER_ROLE = "user";
 
     private static final ResponseHandler EMBEDDINGS_HANDLER = new LlamaEmbeddingsResponseHandler(
@@ -50,6 +54,12 @@ public class LlamaActionCreator implements LlamaActionVisitor {
     private final Sender sender;
     private final ServiceComponents serviceComponents;
 
+    /**
+     * Constructs a new LlamaActionCreator with the specified sender and service components.
+     *
+     * @param sender the sender to use for executing actions
+     * @param serviceComponents the service components providing necessary services
+     */
     public LlamaActionCreator(Sender sender, ServiceComponents serviceComponents) {
         this.sender = Objects.requireNonNull(sender);
         this.serviceComponents = Objects.requireNonNull(serviceComponents);
@@ -87,6 +97,13 @@ public ExecutableAction create(LlamaChatCompletionModel model) {
         return new SingleInputSenderExecutableAction(sender, manager, errorMessage, COMPLETION_ERROR_PREFIX);
     }
 
+    /**
+     * Builds an error message for failed requests.
+     *
+     * @param requestType the type of request that failed
+     * @param inferenceId the inference entity ID associated with the request
+     * @return a formatted error message
+     */
     public static String buildErrorMessage(TaskType requestType, String inferenceId) {
         return format(FAILED_TO_SEND_REQUEST_ERROR_MESSAGE, requestType.toString(), inferenceId);
     }

x-pack/plugin/inference/src/main/java/org/elasticsearch/xpack/inference/services/llama/action/LlamaActionVisitor.java

@@ -11,8 +11,24 @@
 import org.elasticsearch.xpack.inference.services.llama.completion.LlamaChatCompletionModel;
 import org.elasticsearch.xpack.inference.services.llama.embeddings.LlamaEmbeddingsModel;
 
+/**
+ * Visitor interface for creating executable actions for Llama inference models.
+ * This interface defines methods to create actions for both embeddings and chat completion models.
+ */
 public interface LlamaActionVisitor {
+    /**
+     * Creates an executable action for the given Llama embeddings model.
+     *
+     * @param model the Llama embeddings model
+     * @return an executable action for the embeddings model
+     */
     ExecutableAction create(LlamaEmbeddingsModel model);
 
+    /**
+     * Creates an executable action for the given Llama chat completion model.
+     *
+     * @param model the Llama chat completion model
+     * @return an executable action for the chat completion model
+     */
     ExecutableAction create(LlamaChatCompletionModel model);
 }

x-pack/plugin/inference/src/main/java/org/elasticsearch/xpack/inference/services/llama/completion/LlamaChatCompletionModel.java

@@ -20,8 +20,21 @@
 
 import java.util.Map;
 
+/**
+ * Represents a Llama chat completion model for inference.
+ * This class extends the LlamaModel and provides specific configurations and settings for chat completion tasks.
+ */
 public class LlamaChatCompletionModel extends LlamaModel {
 
+    /**
+     * Constructor for creating a LlamaChatCompletionModel with specified parameters.
+     * @param inferenceEntityId the unique identifier for the inference entity
+     * @param taskType the type of task this model is designed for
+     * @param service the name of the inference service
+     * @param serviceSettings the settings for the inference service, specific to chat completion
+     * @param secrets the secret settings for the model, such as API keys or tokens
+     * @param context the context for parsing configuration settings
+     */
     public LlamaChatCompletionModel(
         String inferenceEntityId,
         TaskType taskType,
@@ -39,6 +52,14 @@ public LlamaChatCompletionModel(
         );
     }
 
+    /**
+     * Constructor for creating a LlamaChatCompletionModel with specified parameters.
+     * @param inferenceEntityId the unique identifier for the inference entity
+     * @param taskType the type of task this model is designed for
+     * @param service the name of the inference service
+     * @param serviceSettings the settings for the inference service, specific to chat completion
+     * @param secrets the secret settings for the model, such as API keys or tokens
+     */
     public LlamaChatCompletionModel(
         String inferenceEntityId,
         TaskType taskType,
@@ -53,6 +74,14 @@ public LlamaChatCompletionModel(
         setPropertiesFromServiceSettings(serviceSettings);
     }
 
+    /**
+     * Factory method to create a LlamaChatCompletionModel with overridden model settings based on the request.
+     * If the request does not specify a model, the original model is returned.
+     *
+     * @param model the original LlamaChatCompletionModel
+     * @param request the UnifiedCompletionRequest containing potential overrides
+     * @return a new LlamaChatCompletionModel with overridden settings or the original model if no overrides are specified
+     */
     public static LlamaChatCompletionModel of(LlamaChatCompletionModel model, UnifiedCompletionRequest request) {
         if (request.model() == null) {
             // If no model id is specified in the request, return the original model
@@ -81,11 +110,22 @@ private void setPropertiesFromServiceSettings(LlamaChatCompletionServiceSettings
         this.rateLimitSettings = serviceSettings.rateLimitSettings();
     }
 
+    /**
+     * Returns the service settings specific to Llama chat completion.
+     *
+     * @return the LlamaChatCompletionServiceSettings associated with this model
+     */
     @Override
     public LlamaChatCompletionServiceSettings getServiceSettings() {
         return (LlamaChatCompletionServiceSettings) super.getServiceSettings();
     }
 
+    /**
+     * Accepts a visitor that creates an executable action for this Llama chat completion model.
+     *
+     * @param creator the visitor that creates the executable action
+     * @return an ExecutableAction representing this model
+     */
     public ExecutableAction accept(LlamaActionVisitor creator) {
         return creator.create(this);
     }