Finishing up all major items

- client method for high level objects
- Only support 'float' encoding format
- Add javadoc
- create convenience embedding response class
- Add unit/integration tests
- Add json payloads for req and res
- Add e2e

Author: rpanackal

orchestration/pom.xml

@@ -203,6 +203,7 @@
                     <useOneOfInterfaces>true</useOneOfInterfaces>
                     <removeEnumValuePrefix>true</removeEnumValuePrefix>
                     <useOneOfCreators>true</useOneOfCreators>
+                    <useFloatArrays>true</useFloatArrays>
                   </additionalProperties>
                 </configuration>
               </execution>

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

@@ -218,12 +218,31 @@ public Stream<OrchestrationChatCompletionDelta> streamChatCompletionDeltas(
   }
 
   /**
-   * Generate embeddings for the given request.
+   * Generate embeddings for a {@code OrchestrationEmbeddingRequest} request.
    *
    * @param request the request containing the input text and other parameters.
    * @return the response containing the embeddings.
    * @throws OrchestrationClientException if the request fails
-   * @since 1.9.0
+   * @since 1.11.0
+   */
+  @Nonnull
+  public OrchestrationEmbeddingResponse embed(@Nonnull final OrchestrationEmbeddingRequest request)
+      throws OrchestrationClientException {
+    final var response = embed(request.createEmbeddingsPostRequest());
+    return new OrchestrationEmbeddingResponse(response);
+  }
+
+  /**
+   * Generates embeddings using the low-level API request.
+   *
+   * <p>This method provides direct access to the underlying API for advanced use cases. For most
+   * scenarios, prefer {@link #embed(OrchestrationEmbeddingRequest)}.
+   *
+   * @param request the low-level API request
+   * @return the low level response object
+   * @throws OrchestrationClientException if the request fails
+   * @since 1.11.0
+   * @see #embed(OrchestrationEmbeddingRequest)
    */
   @Nonnull
   public EmbeddingsPostResponse embed(@Nonnull final EmbeddingsPostRequest request)

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

@@ -4,6 +4,7 @@
 import com.sap.ai.sdk.core.AiModel;
 import com.sap.ai.sdk.orchestration.model.EmbeddingsModelDetails;
 import com.sap.ai.sdk.orchestration.model.EmbeddingsModelParams;
+import com.sap.ai.sdk.orchestration.model.EmbeddingsModelParams.EncodingFormatEnum;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import lombok.AccessLevel;
@@ -12,46 +13,61 @@
 import lombok.With;
 import lombok.experimental.Accessors;
 
-// ideally this is a record but exposes all args constructor which we want to avoid. Is it worth a
-// value class?
-// Currently, model list follow SAP Notes as the source of truth. But deprecated models are not
-// listed there.
-// Can we reuse existing enum from generated class?
+/**
+ * Configuration for embedding models in the Orchestration service.
+ *
+ * @since 1.11.0
+ */
 @Beta
 @With
 @Value
 @Accessors(fluent = true)
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class OrchestrationEmbeddingModel implements AiModel {
+  /** The name of the embedding model. */
   @Nonnull String name;
+
+  /** The version of the model, defaults to latest if not specified. */
   @Nullable String version;
+
+  /** The number of dimensions for the output embeddings. */
   @Nullable Integer dimensions;
-  @Nullable Boolean normalize;
-  @Nullable EmbeddingsModelParams.EncodingFormatEnum encodingFormat;
 
-  public OrchestrationEmbeddingModel(@Nonnull final String name) {
-    this(name, null, null, null, null);
-  }
+  /** Whether to normalize the embedding vectors. */
+  @Nullable Boolean normalize;
 
+  /** Azure OpenAI Text Embedding 3 Small model */
   public static final OrchestrationEmbeddingModel TEXT_EMBEDDING_3_SMALL =
       new OrchestrationEmbeddingModel("text-embedding-3-small");
 
+  /** Azure OpenAI Text Embedding 3 Large model */
   public static final OrchestrationEmbeddingModel TEXT_EMBEDDING_3_LARGE =
       new OrchestrationEmbeddingModel("text-embedding-3-large");
 
+  /** Amazon Titan Embed Text model */
   public static final OrchestrationEmbeddingModel AMAZON_TITAN_EMBED_TEXT =
       new OrchestrationEmbeddingModel("amazon.titan-embed-text");
 
+  /** NVIDIA LLaMA 3.2 7B NV EmbedQA model */
   public static final OrchestrationEmbeddingModel NVIDIA_LLAMA_32_NV_EMBEDQA_1B =
       new OrchestrationEmbeddingModel("nvidia--llama-3.2-nv-embedqa-1b");
 
-  EmbeddingsModelDetails createEmbeddingsModelDetails() {
+  /**
+   * Creates a new embedding model configuration with the specified name.
+   *
+   * @param name the model name
+   */
+  public OrchestrationEmbeddingModel(@Nonnull final String name) {
+    this(name, null, null, null);
+  }
 
+  @Nonnull
+  EmbeddingsModelDetails createEmbeddingsModelDetails() {
     final var params =
         EmbeddingsModelParams.create()
             .dimensions(dimensions)
             .normalize(normalize)
-            .encodingFormat(encodingFormat);
+            .encodingFormat(EncodingFormatEnum.FLOAT);
     return EmbeddingsModelDetails.create().name(name).version(version).params(params);
   }
 }

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

@@ -1,8 +1,8 @@
 package com.sap.ai.sdk.orchestration;
 
-import static com.sap.ai.sdk.orchestration.model.EmbeddingsInput.TypeEnum.DOCUMENT;
-import static com.sap.ai.sdk.orchestration.model.EmbeddingsInput.TypeEnum.QUERY;
-import static com.sap.ai.sdk.orchestration.model.EmbeddingsInput.TypeEnum.TEXT;
+import static com.sap.ai.sdk.orchestration.OrchestrationEmbeddingRequest.TokenType.DOCUMENT;
+import static com.sap.ai.sdk.orchestration.OrchestrationEmbeddingRequest.TokenType.QUERY;
+import static com.sap.ai.sdk.orchestration.OrchestrationEmbeddingRequest.TokenType.TEXT;
 import static lombok.AccessLevel.PRIVATE;
 
 import com.google.common.annotations.Beta;
@@ -18,33 +18,86 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
 import lombok.Value;
 import lombok.With;
 import lombok.experimental.Tolerate;
 
-// Do we need staged input builder here?
-// Do we need an enum for tokenType?
+/**
+ * Represents a request for generating embeddings through the SAP AI Core Orchestration service.
+ *
+ * @since 1.11.0
+ */
 @Beta
 @Value
 @AllArgsConstructor(access = PRIVATE)
 public class OrchestrationEmbeddingRequest {
 
+  /** The embedding model to use for generating vector representations. */
   @Nonnull OrchestrationEmbeddingModel model;
+
+  /** The list of text inputs to be converted into embeddings. */
   @Nonnull List<String> tokens;
 
+  /** Optional masking providers for data privacy and security. */
   @With(value = PRIVATE)
   @Nullable
   List<MaskingProvider> masking;
 
+  /** Optional token type classification to optimize embedding generation. */
   @With(value = PRIVATE)
   @Nullable
-  EmbeddingsInput.TypeEnum tokenType;
+  TokenType tokenType;
+
+  /**
+   * Create an embedding request using fluent API starting with model selection.
+   *
+   * <pre>{@code
+   * OrchestrationEmbeddingRequest.forModel(myModel).forInputs("text to embed");
+   * }</pre>
+   *
+   * @param model the embedding model to use
+   * @return a step for specifying inputs
+   */
+  @Nonnull
+  public static InputStep forModel(@Nonnull final OrchestrationEmbeddingModel model) {
+    return tokens -> new OrchestrationEmbeddingRequest(model, List.copyOf(tokens), null, null);
+  }
 
-  public static OrchestrationEmbeddingRequest create(
-      OrchestrationEmbeddingModel model, List<String> tokens) {
-    return new OrchestrationEmbeddingRequest(model, tokens, null, null);
+  /** Builder step for specifying text inputs to embed. */
+  @FunctionalInterface
+  public interface InputStep {
+
+    /**
+     * Specifies text inputs to be embedded.
+     *
+     * @param tokens the text strings to embed
+     * @return a new embedding request instance
+     */
+    @Nonnull
+    OrchestrationEmbeddingRequest forInputs(@Nonnull final List<String> tokens);
+
+    /**
+     * Specifies multiple text inputs using variable arguments.
+     *
+     * @param tokens one or more strings to embed
+     * @return a new embedding request instance
+     */
+    @Nonnull
+    default OrchestrationEmbeddingRequest forInputs(@Nonnull final String... tokens) {
+      return forInputs(List.of(tokens));
+    }
   }
 
+  /**
+   * Adds data masking providers to enable detection and masking of sensitive information.
+   *
+   * @param maskingProvider the primary masking provider
+   * @param maskingProviders additional masking providers
+   * @return a new request instance with the specified masking providers
+   * @see MaskingProvider
+   */
   @Tolerate
   @Nonnull
   public OrchestrationEmbeddingRequest withMasking(
@@ -53,36 +106,71 @@ public OrchestrationEmbeddingRequest withMasking(
     return withMasking(Lists.asList(maskingProvider, maskingProviders));
   }
 
+  /**
+   * Configures this request to optimize embeddings for document content.
+   *
+   * @return a new request instance configured for document embedding
+   */
   @Nonnull
   public OrchestrationEmbeddingRequest asDocument() {
     return withTokenType(DOCUMENT);
   }
 
+  /**
+   * Configures this request to optimize embeddings for general text content.
+   *
+   * @return a new request instance configured for text embedding
+   */
   @Nonnull
   public OrchestrationEmbeddingRequest asText() {
     return withTokenType(TEXT);
   }
 
+  /**
+   * Configures this request to optimize embeddings for query content.
+   *
+   * @return a new request instance configured for query embedding
+   */
   @Nonnull
   public OrchestrationEmbeddingRequest asQuery() {
     return withTokenType(QUERY);
   }
 
+  @Nonnull
   EmbeddingsPostRequest createEmbeddingsPostRequest() {
 
-    final var input =
-        EmbeddingsInput.create().text(EmbeddingsInputText.create(tokens)).type(tokenType);
+    final var input = EmbeddingsInput.create().text(EmbeddingsInputText.create(tokens));
     final var embeddingsModelConfig =
-        EmbeddingsModelConfig.create().model(this.model.createEmbeddingsModelDetails());
+        EmbeddingsModelConfig.create().model(model.createEmbeddingsModelDetails());
     final var modules =
         EmbeddingsOrchestrationConfig.create()
             .modules(EmbeddingsModuleConfigs.create().embeddings(embeddingsModelConfig));
 
+    if (tokenType != null) {
+      input.setType(EmbeddingsInput.TypeEnum.fromValue(tokenType.getValue()));
+    }
     if (masking != null) {
-      final var dpiConfigs = this.masking.stream().map(MaskingProvider::createConfig).toList();
+      final var dpiConfigs = masking.stream().map(MaskingProvider::createConfig).toList();
       modules.getModules().setMasking(MaskingModuleConfigProviders.create().providers(dpiConfigs));
     }
-
     return EmbeddingsPostRequest.create().config(modules).input(input);
   }
+
+  /**
+   * Token type classification for optimizing embedding generation.
+   *
+   * <p>Token types may influence how the embedding model processes and represents the input text.
+   */
+  @Getter
+  @RequiredArgsConstructor
+  public enum TokenType {
+    /** For document content. */
+    DOCUMENT("document"),
+    /** For general text (default). */
+    TEXT("text"),
+    /** For search queries. */
+    QUERY("query");
+
+    private final String value;
+  }
 }

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

@@ -0,0 +1,46 @@
+package com.sap.ai.sdk.orchestration;
+
+import static lombok.AccessLevel.PACKAGE;
+
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.orchestration.model.Embedding;
+import com.sap.ai.sdk.orchestration.model.EmbeddingsPostResponse;
+import java.util.ArrayList;
+import java.util.List;
+import javax.annotation.Nonnull;
+import lombok.AllArgsConstructor;
+import lombok.Value;
+
+/**
+ * Response wrapper for orchestration embedding operations.
+ *
+ * <p>Wraps {@link EmbeddingsPostResponse} and provides convenient access to embedding vectors.
+ */
+@Beta
+@Value
+@AllArgsConstructor(access = PACKAGE)
+public class OrchestrationEmbeddingResponse {
+
+  /** The original embedding response from the orchestration API. */
+  @Nonnull EmbeddingsPostResponse originalResponse;
+
+  /**
+   * Extracts embedding vectors as float arrays.
+   *
+   * @return list of embedding vectors, never {@code null}
+   */
+  @Nonnull
+  public List<float[]> getEmbeddingVectors() {
+    final var embeddings = new ArrayList<float[]>();
+    for (final var container : originalResponse.getFinalResult().getData()) {
+      final var bigDecimals = (Embedding.InnerBigDecimals) container.getEmbedding();
+      final var values = bigDecimals.values();
+      final float[] arr = new float[values.size()];
+      for (int i = 0; i < values.size(); i++) {
+        arr[i] = values.get(i).floatValue();
+      }
+      embeddings.add(arr);
+    }
+    return embeddings;
+  }
+}