Add javadoc and logging

Author: MatKuhr

orchestration/src/main/java/com/sap/ai/sdk/orchestration/AssistantMessage.java

@@ -1,8 +1,15 @@
 package com.sap.ai.sdk.orchestration;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
-public record AssistantMessage(@Nonnull String content) implements Message {
+/**
+ * Response messages from an LLM.
+ *
+ * @param content the content, if any.
+ * @see Message
+ */
+public record AssistantMessage(@Nullable String content) implements Message {
   @Nonnull
   @Override
   public String type() {

orchestration/src/main/java/com/sap/ai/sdk/orchestration/ContentFilter.java

@@ -1,3 +1,8 @@
 package com.sap.ai.sdk.orchestration;
 
+/**
+ * A content filter configuration for orchestration requests.
+ *
+ * @see AzureContentFilter
+ */
 public sealed interface ContentFilter permits AzureContentFilter {}

orchestration/src/main/java/com/sap/ai/sdk/orchestration/DefaultOrchestrationConfig.java

@@ -11,6 +11,12 @@
 import lombok.Setter;
 import lombok.ToString;
 
+/**
+ * Default implementation of the {@link OrchestrationConfig} interface. This class supports
+ * delegation from other classes by accepting a wrapper instance.
+ *
+ * @param <T> The type of the wrapper object that delegates to this object, if any.
+ */
 @Data
 @Setter(AccessLevel.PRIVATE)
 @RequiredArgsConstructor(access = AccessLevel.PRIVATE)

orchestration/src/main/java/com/sap/ai/sdk/orchestration/DpiMaskingConfig.java

@@ -13,21 +13,37 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import lombok.AccessLevel;
+import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import lombok.Value;
 import lombok.val;
 
+/**
+ * Implementation of {@link MaskingConfig} for SAP Data Privacy Integration (DPI) service. Supports
+ * both anonymization and pseudonymization of personally identifiable information.
+ */
 @Value
+@Getter(AccessLevel.PACKAGE)
 @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
 public class DpiMaskingConfig implements MaskingConfig {
   @Nonnull MaskingProviderConfig.MethodEnum maskingMethod;
   @Nonnull List<DPIEntities> entities;
 
+  /**
+   * Build a configuration applying anonymization.
+   *
+   * @return A builder configured for anonymization
+   */
   @Nonnull
   public static Builder anonymization() {
     return new DpiMaskingConfig.Builder(ANONYMIZATION);
   }
 
+  /**
+   * Build a configuration applying pseudonymization.
+   *
+   * @return A builder configured for pseudonymization
+   */
   @Nonnull
   public static Builder pseudonymization() {
     return new DpiMaskingConfig.Builder(PSEUDONYMIZATION);
@@ -42,10 +58,22 @@ MaskingProviderConfig toMaskingProviderDTO() {
         .entities(entitiesDTO);
   }
 
+  /**
+   * Builder for creating DPI masking configurations. Allows specifying which entity types should be
+   * masked in the input text.
+   */
   @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
   public static class Builder {
     private final MaskingProviderConfig.MethodEnum maskingMethod;
 
+    /**
+     * Specifies which entities should be masked in the input text.
+     *
+     * @param entity An entity type to mask (required)
+     * @param entities Additional entity types to mask (optional)
+     * @return A configured {@link DpiMaskingConfig} instance
+     * @see DPIEntities
+     */
     @Nonnull
     public DpiMaskingConfig withEntities(
         @Nonnull final DPIEntities entity, @Nullable final DPIEntities... entities) {

orchestration/src/main/java/com/sap/ai/sdk/orchestration/LlmConfig.java

@@ -8,17 +8,47 @@
 import javax.annotation.Nullable;
 import lombok.val;
 
+/**
+ * Language model configuration for the orchestration service.
+ *
+ * <p>Please note that, depending on which model you are using, some parameters may be required.
+ * Furthermore, do not set the "stream" parameter here but use {@link
+ * OrchestrationClient#streamChatCompletion(String)} instead.
+ *
+ * @param name The name of the language model.
+ * @param version Optional, the version of the language model.
+ * @param parameters Optional, additional parameters of the language model.
+ * @see AiModel
+ * @see OrchestrationConfig#withLlmConfig(AiModel)
+ */
 public record LlmConfig(
     @Nonnull String name, @Nullable String version, @Nullable Map<String, ?> parameters)
     implements AiModel {
+  /**
+   * Reference a language model by name.
+   *
+   * @param name The name of the language model.
+   */
   public LlmConfig(@Nonnull final String name) {
     this(name, null, null);
   }
 
+  /**
+   * Reference a language model by name and version.
+   *
+   * @param name The name of the language model.
+   * @param version The version of the language model.
+   */
   public LlmConfig(@Nonnull final String name, @Nonnull final String version) {
     this(name, version, null);
   }
 
+  /**
+   * Reference a language model by name and parameters.
+   *
+   * @param name The name of the language model.
+   * @param parameters Additional parameters of the language model.
+   */
   public LlmConfig(@Nonnull final String name, @Nonnull final Map<String, ?> parameters) {
     this(name, null, parameters);
   }

orchestration/src/main/java/com/sap/ai/sdk/orchestration/MaskingConfig.java

@@ -1,3 +1,8 @@
 package com.sap.ai.sdk.orchestration;
 
+/**
+ * A masking configuration for orchestration requests.
+ *
+ * @see DpiMaskingConfig
+ */
 public sealed interface MaskingConfig permits DpiMaskingConfig {}

orchestration/src/main/java/com/sap/ai/sdk/orchestration/Message.java

@@ -1,12 +1,32 @@
 package com.sap.ai.sdk.orchestration;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
+/**
+ * Represents messages that can be sent to and received from the orchestration service as part of a
+ * template, message history or LLM response.
+ *
+ * @see UserMessage
+ * @see SystemMessage
+ * @see AssistantMessage
+ */
 public interface Message {
 
+  /**
+   * Type (or sometimes role) of the message.
+   *
+   * @return the type of the message
+   */
   @Nonnull
   String type();
 
-  @Nonnull
+  /**
+   * Content of the message.
+   *
+   * @return the content of the message. Can be {@code null}, unless specified otherwise by the
+   *     implementing type.
+   */
+  @Nullable
   String content();
 }

orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClient.java

@@ -22,13 +22,15 @@
 import javax.annotation.Nonnull;
 import lombok.RequiredArgsConstructor;
 import lombok.experimental.Delegate;
+import lombok.extern.slf4j.Slf4j;
 import lombok.val;
 import org.apache.hc.client5.http.classic.methods.HttpPost;
 import org.apache.hc.core5.http.ContentType;
 import org.apache.hc.core5.http.io.entity.StringEntity;
 import org.apache.hc.core5.http.message.BasicClassicHttpRequest;
 import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
 
+@Slf4j
 @RequiredArgsConstructor
 public class OrchestrationClient implements OrchestrationConfig<OrchestrationClient> {
   static final ObjectMapper JACKSON;
@@ -52,6 +54,7 @@ public class OrchestrationClient implements OrchestrationConfig<OrchestrationCli
 
   private interface IDelegate extends OrchestrationConfig<OrchestrationClient> {}
 
+  /** Default constructor. */
   public OrchestrationClient() {
     service = new AiCoreService();
   }
@@ -69,6 +72,9 @@ public String chatCompletion(@Nonnull final String userPrompt)
     val response = chatCompletion(new OrchestrationPrompt(userPrompt));
 
     if (response.finishReason() == CONTENT_FILTER) {
+      log.error(
+          "Output content filter triggered. Full response details: {}",
+          response.originalResponseDto());
       throw new OrchestrationClientException("Output content filter triggered");
     }
     return response.assistantMessage().getContent();
@@ -84,8 +90,16 @@ public String chatCompletion(@Nonnull final String userPrompt)
   @Nonnull
   public OrchestrationResponse chatCompletion(@Nonnull final OrchestrationPrompt prompt)
       throws OrchestrationClientException {
+    log.debug(
+        """
+            Performing request to orchestration service.
+            Prompt: {}
+            Defaults: {}
+            """,
+        prompt,
+        clientConfig);
     val dto = prompt.toCompletionPostRequestDTO(clientConfig);
-
+    log.debug("Assembled data transfer object for request: {}", dto);
     val result = executeRequest(dto);
     return OrchestrationResponse.fromCompletionPostResponseDTO(result);
   }
@@ -107,6 +121,7 @@ protected CompletionPostResponse executeRequest(@Nonnull final CompletionPostReq
     final BasicClassicHttpRequest postRequest = new HttpPost("/completion");
     try {
       val json = JACKSON.writeValueAsString(request);
+      log.debug("Serialized request into JSON payload: {}", json);
       postRequest.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON));
     } catch (final JsonProcessingException e) {
       throw new OrchestrationClientException("Failed to serialize request parameters", e);
@@ -120,6 +135,7 @@ protected CompletionPostResponse executeRequest(@Nonnull final CompletionPostReq
   CompletionPostResponse executeRequest(@Nonnull final BasicClassicHttpRequest request) {
     try {
       val destination = service.forDeploymentByScenario("orchestration").destination();
+      log.debug("Using destination {} to connect to orchestration service", destination);
       val client = ApacheHttpClient5Accessor.getHttpClient(destination);
       return client.execute(
           request, new OrchestrationResponseHandler<>(CompletionPostResponse.class));

orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClientException.java

@@ -2,12 +2,25 @@
 
 import javax.annotation.Nonnull;
 
+/** Exception thrown by the {@link OrchestrationClient} in case of an error. */
 public class OrchestrationClientException extends RuntimeException {
-  public OrchestrationClientException(@Nonnull final String msg, @Nonnull final Throwable cause) {
-    super(msg, cause);
-  }
 
+  /**
+   * Constructor.
+   *
+   * @param msg the error message
+   */
   public OrchestrationClientException(@Nonnull final String msg) {
     super(msg);
   }
+
+  /**
+   * Constructor.
+   *
+   * @param msg the error message
+   * @param cause the cause of the error
+   */
+  public OrchestrationClientException(@Nonnull final String msg, @Nonnull final Throwable cause) {
+    super(msg, cause);
+  }
 }