Added. More. Javadoc.

Author: MatKuhr

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

@@ -10,20 +10,38 @@
 import lombok.experimental.Accessors;
 import lombok.val;
 
+/**
+ * Represents a content filter based on Azure AI Content Safety. Filters content based on up to four
+ * categories: hate speech, self-harm, sexual content, and violence. Any category not set will not
+ * be filtered.
+ */
 @Data
 @Accessors(fluent = true)
 public final class AzureContentFilter implements ContentFilter {
+  /** The sensitivity level for hate speech, if any. */
   @Nullable private Sensitivity hate;
+
+  /** The sensitivity level for self-harm, if any. */
   @Nullable private Sensitivity selfHarm;
+
+  /** The sensitivity level for sexual content, if any. */
   @Nullable private Sensitivity sexual;
+
+  /** The sensitivity level for violence, if any. */
   @Nullable private Sensitivity violence;
 
+  /** The sensitivity level for the content filter categories. */
   @RequiredArgsConstructor
   public enum Sensitivity {
+    /** High filter sensitivity, filtering out more content. */
     HIGH(0),
+    /** Medium filter sensitivity, filtering out less content. */
     MEDIUM(2),
+    /** Low filter sensitivity, filtering out the least content. */
     LOW(4);
+
     // note: we leave out the value 6, as setting it is equivalent to not setting the filter at all
+    /** The integer value of the sensitivity level, will be applied as threshold. */
     private final int value;
   }
 

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

@@ -30,6 +30,11 @@
 import org.apache.hc.core5.http.message.BasicClassicHttpRequest;
 import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
 
+/**
+ * Client to execute requests to the orchestration service. Can be configured to hold a default
+ * {@link OrchestrationConfig} to be used for all requests. Configuration set on an {@link
+ * OrchestrationPrompt} will take precedence upon execution.
+ */
 @Slf4j
 @RequiredArgsConstructor
 public class OrchestrationClient implements OrchestrationConfig<OrchestrationClient> {
@@ -104,20 +109,53 @@ public OrchestrationResponse chatCompletion(@Nonnull final OrchestrationPrompt p
     return OrchestrationResponse.fromCompletionPostResponseDTO(result);
   }
 
+  /**
+   * Stream a completion for the given user message.
+   *
+   * @param prompt The user message.
+   * @return A stream of message chunks.
+   * @throws OrchestrationClientException If the request fails.
+   */
   @Nonnull
   public Stream<String> streamChatCompletion(@Nonnull final String prompt)
       throws OrchestrationClientException {
     throw new NotImplementedError();
   }
 
+  /**
+   * Stream a completion for the given prompt.
+   *
+   * @param prompt The prompt, including messages and other configuration.
+   * @return A stream of message chunks.
+   * @throws OrchestrationClientException If the request fails.
+   */
   @Nonnull
   public Stream<String> streamChatCompletionDelta(@Nonnull final OrchestrationPrompt prompt)
       throws OrchestrationClientException {
     throw new NotImplementedError();
   }
 
+  /**
+   * Serializes the given request, executes it and deserializes the response.
+   *
+   * <p>Override this method to customize the request execution. For example, to modify the request
+   * object before it is sent, use:
+   *
+   * <pre>{@code
+   * @Override
+   * protected CompletionPostResponse executeRequest(@Nonnull CompletionPostRequest request) {
+   *   request.setCustomField("myField", "myValue");
+   *   return super.executeRequest(request);
+   * }
+   * }</pre>
+   *
+   * @param request The request DTO to send to orchestration.
+   * @return The response DTO from orchestration.
+   * @throws OrchestrationClientException If the request fails.
+   */
   @Nonnull
-  protected CompletionPostResponse executeRequest(@Nonnull final CompletionPostRequest request) {
+  protected CompletionPostResponse executeRequest(@Nonnull final CompletionPostRequest request)
+      throws OrchestrationClientException {
     final BasicClassicHttpRequest postRequest = new HttpPost("/completion");
     try {
       val json = JACKSON.writeValueAsString(request);

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

@@ -27,14 +27,20 @@ public record OrchestrationResponse(
     @Nonnull TokenUsage tokenUsage,
     @Nonnull CompletionPostResponse originalResponseDto) {
 
+  /** The reason why an assistant message finished. */
   @RequiredArgsConstructor
   public enum FinishReason {
+    /** The assistant message finished normally. */
     STOP("stop"),
+    /** The generated message is cut off because the maximum number of output tokens was reached. */
     MAX_TOKENS("max_tokens"),
+    /** The generated message was filtered out by an output content filter. */
     CONTENT_FILTER("content_filter"),
+    /** The assistant message finished with a non-standardized reason. */
     UNKNOWN("unknown");
 
-    @Nonnull final String value;
+    /** String representation of the finish reason. */
+    @Nonnull private final String value;
 
     @Nonnull
     static FinishReason fromValue(@Nonnull final String value) {