Switch to builder approach

Author: MatKuhr

core/src/main/java/com/sap/ai/sdk/core/AiCoreService.java

@@ -88,47 +88,33 @@ public HttpDestination getBaseDestination()
   }
 
   /**
-   * Get a new endpoint object, targeting a specific deployment ID.
+   * Get a destination to perform inference calls against a deployment under the default resource
+   * group on AI Core.
    *
-   * @param deploymentId The deployment id to be used for the new endpoint.
-   * @return the new instance.
-   */
-  @Nonnull
-  public HttpDestination getDestinationForDeploymentById(
-      @Nonnull final String resourceGroup, @Nonnull final String deploymentId) {
-    return toInferenceDestination(resourceGroup, deploymentId);
-  }
-
-  /**
-   * Get a destination to perform inference calls for a specific model. If there are multiple
-   * deployments of the same model, the first one is returned.
-   *
-   * @param model The model to be used for inference calls.
-   * @return A new instance of the AI Core Deployment.
-   * @throws DeploymentResolutionException if no running deployment is found for the model.
+   * @return The destination pointing to the specific deployment ID.
+   * @throws DestinationAccessException If there was an issue creating the base destination, e.g. in
+   *     case of invalid credentials.
+   * @throws DestinationNotFoundException If there was an issue creating the base destination, e.g.
+   *     in case of missing credentials.
+   * @see #getInferenceDestination(String) for specifying a custom resource group.
    */
   @Nonnull
-  public HttpDestination getDestinationForDeploymentByModel(
-      @Nonnull final String resourceGroup, @Nonnull final AiModel model)
-      throws DeploymentResolutionException {
-    val deploymentId = deploymentResolver.getDeploymentIdByModel(resourceGroup, model);
-    return toInferenceDestination(resourceGroup, deploymentId);
+  public InferenceDestinationBuilder getInferenceDestination()
+      throws DestinationAccessException, DestinationNotFoundException {
+    return new InferenceDestinationBuilder(DEFAULT_RESOURCE_GROUP);
   }
 
   /**
-   * Set a specific deployment by scenario id. If there are multiple deployments of the same model,
-   * the first one is returned.
+   * Get a destination to perform inference calls against a deployment for the given resource group
+   * on AI Core.
    *
-   * @param scenarioId The scenario id to be used for AI Core service calls.
-   * @return A new instance of the AI Core Deployment.
-   * @throws DeploymentResolutionException if no running deployment is found for the scenario.
+   * @param resourceGroup The resource group to be used for the new endpoint.
+   * @return The destination pointing to the specific deployment ID.
+   * @see #getInferenceDestination() for using the default resource group.
    */
   @Nonnull
-  public HttpDestination getDestinationForDeploymentByScenario(
-      @Nonnull final String resourceGroup, @Nonnull final String scenarioId)
-      throws DeploymentResolutionException {
-    val deploymentId = deploymentResolver.getDeploymentIdByScenario(resourceGroup, scenarioId);
-    return toInferenceDestination(resourceGroup, deploymentId);
+  public InferenceDestinationBuilder getInferenceDestination(@Nonnull final String resourceGroup) {
+    return new InferenceDestinationBuilder(resourceGroup);
   }
 
   /**
@@ -159,17 +145,6 @@ public ApiClient getApiClient() {
     return new ApiClient(rt).setBasePath(destination.asHttp().getUri().toString());
   }
 
-  HttpDestination toInferenceDestination(
-      @Nonnull final String resourceGroup, @Nonnull final String deploymentId) {
-    val destination = getBaseDestination();
-    val path = buildDeploymentPath(deploymentId);
-
-    return DefaultHttpDestination.fromDestination(destination)
-        .uri(destination.getUri().resolve(path))
-        .property(RESOURCE_GROUP_HEADER_PROPERTY, resourceGroup)
-        .build();
-  }
-
   /**
    * Helper method to build the <b>relative</b> URL path for the inference endpoint of a deployment.
    * The result of this together with the base path defined on the destination will be used for
@@ -195,4 +170,73 @@ protected String buildDeploymentPath(@Nonnull final String deploymentId) {
   public void reloadCachedDeployments(@Nonnull final String resourceGroup) {
     deploymentResolver.reloadDeployments(resourceGroup);
   }
+
+  /** Builder for creating inference destinations. */
+  @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+  public class InferenceDestinationBuilder {
+    @Nonnull private final String resourceGroup;
+
+    /**
+     * Use a fixed deployment ID to identify the deployment.
+     *
+     * @param deploymentId The ID of the deployment to target.
+     * @return A new destination targeting the specified deployment.
+     * @throws DestinationAccessException If there was an issue creating the base destination, e.g.
+     *     in case of invalid credentials.
+     * @throws DestinationNotFoundException If there was an issue creating the base destination,
+     *     e.g. in case of missing credentials.
+     * @see #forModel(AiModel)
+     * @see #forScenario(String)
+     */
+    @Nonnull
+    public HttpDestination usingDeploymentId(@Nonnull final String deploymentId)
+        throws DestinationAccessException, DestinationNotFoundException {
+      return build(deploymentId);
+    }
+
+    /**
+     * Lookup a deployment based on the given {@link AiModel}. If there are multiple deployments for
+     * the given model, the first one is returned.
+     *
+     * @param model The model to be used for inference calls.
+     * @return A new destination targeting a deployment for the given model.
+     * @throws DeploymentResolutionException If no running deployment is found for the model.
+     * @see #forScenario(String)
+     * @see #usingDeploymentId(String)
+     */
+    @Nonnull
+    public HttpDestination forModel(@Nonnull final AiModel model)
+        throws DeploymentResolutionException {
+      val id = deploymentResolver.getDeploymentIdByModel(resourceGroup, model);
+      return build(id);
+    }
+
+    /**
+     * Lookup a deployment based on the given scenario. If there are multiple deployments within the
+     * same scenario, the first one is returned.
+     *
+     * @param scenarioId The scenario to discover deployments for.
+     * @return A new destination targeting a deployment within the given scenario.
+     * @throws DeploymentResolutionException If no running deployment is found within the scenario.
+     * @see #forModel(AiModel)
+     * @see #usingDeploymentId(String)
+     */
+    @Nonnull
+    public HttpDestination forScenario(@Nonnull final String scenarioId)
+        throws DeploymentResolutionException {
+      val id = deploymentResolver.getDeploymentIdByScenario(resourceGroup, scenarioId);
+      return build(id);
+    }
+
+    @Nonnull
+    HttpDestination build(@Nonnull final String deploymentId) {
+      val destination = getBaseDestination();
+      val path = buildDeploymentPath(deploymentId);
+
+      return DefaultHttpDestination.fromDestination(destination)
+          .uri(destination.getUri().resolve(path))
+          .property(RESOURCE_GROUP_HEADER_PROPERTY, resourceGroup)
+          .build();
+    }
+  }
 }

core/src/test/java/com/sap/ai/sdk/core/AiCoreServiceTest.java

@@ -2,6 +2,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import com.sap.cloud.sdk.cloudplatform.connectivity.DefaultHttpDestination;
 import com.sap.cloud.sdk.cloudplatform.connectivity.Header;
@@ -61,8 +62,12 @@ void testCustomBaseDestination() {
   }
 
   @Test
-  void testToInferenceDestination() {
-    val destination = service.toInferenceDestination("foo", "123");
+  void testGetInferenceDestination() {
+    var builder = service.getInferenceDestination();
+    assertThatThrownBy(() -> builder.forScenario("doesn't exist"))
+        .isExactlyInstanceOf(DeploymentResolutionException.class);
+
+    val destination = service.getInferenceDestination("foo").usingDeploymentId("123");
 
     assertThat(destination.getUri())
         .hasHost("api.ai.com")

foundation-models/openai/pom.xml

@@ -87,6 +87,10 @@
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+    </dependency>
     <!-- scope "provided" -->
     <dependency>
       <groupId>org.projectlombok</groupId>

foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiClient.java

@@ -6,8 +6,8 @@
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import com.google.common.annotations.Beta;
 import com.sap.ai.sdk.core.AiCoreService;
-import com.sap.ai.sdk.core.AiModel;
 import com.sap.ai.sdk.core.DeploymentResolutionException;
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiChatCompletionDelta;
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiChatCompletionOutput;
@@ -64,15 +64,19 @@ public final class OpenAiClient {
   @Nonnull
   public static OpenAiClient forModel(@Nonnull final OpenAiModel foundationModel)
       throws DeploymentResolutionException {
-    final var destination =
-        new AiCoreService()
-            .getDestinationForDeploymentByModel(
-                AiCoreService.DEFAULT_RESOURCE_GROUP, foundationModel);
+    final var destination = new AiCoreService().getInferenceDestination().forModel(foundationModel);
+
     final var client = new OpenAiClient(destination);
     return client.withApiVersion(DEFAULT_API_VERSION);
   }
 
-  // package private, but prepared in case we want to expose it later
+  /**
+   * Create a new OpenAI client targeting the specified API version.
+   *
+   * @param apiVersion the API version to target.
+   * @return a new client.
+   */
+  @Beta
   @Nonnull
   OpenAiClient withApiVersion(@Nonnull final String apiVersion) {
     final var newDestination =
@@ -85,18 +89,21 @@ OpenAiClient withApiVersion(@Nonnull final String apiVersion) {
 
   /**
    * Create a new OpenAI client with a custom destination, allowing for a custom resource group or
-   * otherwise custom destination.
+   * otherwise custom destination. The destination needs to be configured with a URL pointing to an
+   * OpenAI model deployment. Typically, such a destination should be obtained using {@link
+   * AiCoreService#getInferenceDestination(String)}.
    *
    * <p>Example:
    *
    * <pre>{@code
-   * OpenAiClient.withCustomDestination(new AiCoreService().getDestinationForDeploymentByModel("custom-rg", GPT_4O));
-   *
+   * var destination = new AiCoreService().getInferenceDestination("custom-rg").forModel(GPT_4O);
+   * OpenAiClient.withCustomDestination(destination).withApiVersion("2024-10-21");
    * }</pre>
    *
    * @param destination The specific {@link HttpDestination} to use.
-   * @see AiCoreService#getDestinationForDeploymentByModel(String, AiModel)
+   * @see AiCoreService#getInferenceDestination(String)
    */
+  @Beta
   @Nonnull
   public static OpenAiClient withCustomDestination(@Nonnull final Destination destination) {
     return new OpenAiClient(destination);

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

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import com.google.common.annotations.Beta;
 import com.sap.ai.sdk.core.AiCoreService;
+import com.sap.ai.sdk.core.DeploymentResolutionException;
 import com.sap.ai.sdk.orchestration.model.CompletionPostRequest;
 import com.sap.ai.sdk.orchestration.model.CompletionPostResponse;
 import com.sap.ai.sdk.orchestration.model.FilterConfig;
@@ -25,7 +26,6 @@
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationNotFoundException;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.HttpClientInstantiationException;
 import java.io.IOException;
-import java.util.NoSuchElementException;
 import java.util.function.Supplier;
 import javax.annotation.Nonnull;
 import lombok.extern.slf4j.Slf4j;
@@ -64,25 +64,25 @@ public class OrchestrationClient {
   /** Default constructor. */
   public OrchestrationClient() {
     destinationSupplier =
-        () ->
-            new AiCoreService()
-                .getDestinationForDeploymentByScenario(
-                    AiCoreService.DEFAULT_RESOURCE_GROUP, DEFAULT_SCENARIO);
+        () -> new AiCoreService().getInferenceDestination().forScenario(DEFAULT_SCENARIO);
   }
 
   /**
    * Constructor with a custom destination, allowing for a custom resource group or otherwise custom
-   * destination.
+   * destination. The destination needs to be configured with a URL pointing to an orchestration
+   * service deployment. Typically, such a destination should be obtained using {@link
+   * AiCoreService#getInferenceDestination(String)}.
    *
    * <p>Example:
    *
    * <pre>{@code
-   * new OrchestrationClient(new AiCoreService().getDestinationForDeploymentByScenario("custom-rg", "orchestration"));
+   * new OrchestrationClient(new AiCoreService().getInferenceDestination("custom-rg").forScenario("orchestration"));
    * }</pre>
    *
    * @param destination The specific {@link HttpDestination} to use.
-   * @see AiCoreService#getDestinationForDeploymentByScenario(String, String)
+   * @see AiCoreService#getInferenceDestination(String)
    */
+  @Beta
   public OrchestrationClient(@Nonnull final HttpDestination destination) {
     this.destinationSupplier = () -> destination;
   }
@@ -210,7 +210,7 @@ CompletionPostResponse executeRequest(@Nonnull final String request) {
       val client = ApacheHttpClient5Accessor.getHttpClient(destination);
       return client.execute(
           postRequest, new OrchestrationResponseHandler<>(CompletionPostResponse.class));
-    } catch (NoSuchElementException
+    } catch (DeploymentResolutionException
         | DestinationAccessException
         | DestinationNotFoundException
         | HttpClientInstantiationException