feat: OpenAI realtime api

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

@@ -0,0 +1,33 @@
+package com.sap.ai.sdk.core;
+
+import javax.annotation.Nonnull;
+
+/** Represents possible configuration params of realtime client */
+public interface RealtimeParam {
+  /** Represents configurable options */
+  enum SpeechOutputParamName {
+    /** Voice name to use to produce sound */
+    VOICE,
+    /**
+     * How model will recognize that it is its turn to respond (e.g. explicitly asked, automatically
+     * detected)
+     */
+    TURN_DETECTION,
+  }
+
+  /**
+   * Returns param name
+   *
+   * @return name
+   */
+  @Nonnull
+  SpeechOutputParamName getParamName();
+
+  /**
+   * Returns string value representation of the param
+   *
+   * @return string value
+   */
+  @Nonnull
+  String getValueAsString();
+}

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

@@ -0,0 +1,51 @@
+package com.sap.ai.sdk.core;
+
+import java.util.Objects;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/** Allows to configure turn detection (how model responds). */
+public final class RealtimeParamTurnDetection implements RealtimeParam {
+
+  /** Model tries to recognize if/when it should respond automatically */
+  public static final RealtimeParamTurnDetection BY_MODEL_AUTO =
+      new RealtimeParamTurnDetection("BY_MODEL_AUTO");
+
+  /**
+   * Each call to the provided realtime client is considered a turn (eager explicit turn detection).
+   * Less convenient than the automatic option but may give lower latency in some cases (model does
+   * not need to perform additional turn detection analysis).
+   */
+  public static final RealtimeParamTurnDetection EACH_CALL_IS_A_TURN =
+      new RealtimeParamTurnDetection("EACH_CALL_IS_A_TURN");
+
+  private final String turnDetectionKind;
+
+  private RealtimeParamTurnDetection(final String turnDetectionKind) {
+    this.turnDetectionKind = turnDetectionKind;
+  }
+
+  @Override
+  public @Nonnull SpeechOutputParamName getParamName() {
+    return SpeechOutputParamName.TURN_DETECTION;
+  }
+
+  @Override
+  public @Nonnull String getValueAsString() {
+    return turnDetectionKind;
+  }
+
+  @Override
+  public boolean equals(@Nullable final Object o) {
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    final RealtimeParamTurnDetection that = (RealtimeParamTurnDetection) o;
+    return Objects.equals(turnDetectionKind, that.turnDetectionKind);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(turnDetectionKind);
+  }
+}

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

@@ -0,0 +1,57 @@
+package com.sap.ai.sdk.core;
+
+import java.util.Objects;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/** Allows to configure model output voice */
+public final class RealtimeParamVoice implements RealtimeParam {
+
+  /** Standard voice 1 */
+  public static final RealtimeParamVoice DEFAULT_1 = new RealtimeParamVoice("DEFAULT_1");
+
+  /** Standard voice 2 */
+  public static final RealtimeParamVoice DEFAULT_2 = new RealtimeParamVoice("DEFAULT_2");
+
+  private final String voice;
+
+  private RealtimeParamVoice(@Nonnull final String voice) {
+    this.voice = voice;
+  }
+
+  /**
+   * Allows to configure raw voice name as named by model provider. Unsafe because SDK cannot verify
+   * in advance if the provided voice name is correct and supported by the chosen model and use case
+   *
+   * @param voiceName as named by model provider
+   * @return typed voice client configuration param
+   */
+  @Nonnull
+  public static RealtimeParamVoice unsafeWithExplicitVoice(@Nonnull final String voiceName) {
+    return new RealtimeParamVoice(voiceName);
+  }
+
+  @Override
+  public @Nonnull SpeechOutputParamName getParamName() {
+    return SpeechOutputParamName.VOICE;
+  }
+
+  @Override
+  public @Nonnull String getValueAsString() {
+    return voice;
+  }
+
+  @Override
+  public boolean equals(@Nullable final Object o) {
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    final RealtimeParamVoice that = (RealtimeParamVoice) o;
+    return Objects.equals(voice, that.voice);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(voice);
+  }
+}

foundation-models/openai/pom.xml

@@ -124,7 +124,6 @@
     <dependency>
       <groupId>com.openai</groupId>
       <artifactId>openai-java-core</artifactId>
-      <optional>true</optional>
     </dependency>
     <!-- scope "provided" -->
     <dependency>

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

@@ -0,0 +1,18 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+/**
+ * Functional interface representing audio input channel (audio data consumer)
+ *
+ * <p>Should be closed by application (try-with-resources) when not needed anymore
+ */
+public interface AudioInputChannel extends AutoCloseable {
+
+  /**
+   * This method is sequentially invoked by audio data provider to supply implementer (consumer)
+   * with the audio data. Exact audio format (encoding, sampling rate, etc.) depends on the usage
+   * context
+   *
+   * @param rawBytesChunk binary data in the depending on the use case format
+   */
+  void inputAudio(byte[] rawBytesChunk);
+}

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

@@ -0,0 +1,17 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+/** Functional interface representing audio output channel (audio data consumer) */
+public interface AudioOutputChannel {
+
+  /**
+   * This method is sequentially invoked by audio data provider to supply implementer (consumer)
+   * with the audio data. Exact audio format (encoding, sampling rate, etc.) depends on the usage
+   * context
+   *
+   * @param rawBytesChunk binary data in the depending on the use case format
+   * @param isLast true if this call logically concludes previous and this passed bytes data into a
+   *     single logical entity (e.g. gets called at the end when all byte parts of a single message
+   *     get passed)
+   */
+  void outputAudio(byte[] rawBytesChunk, boolean isLast);
+}

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

@@ -26,6 +26,7 @@
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiChatMessage.OpenAiChatUserMessage;
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiEmbeddingOutput;
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiEmbeddingParameters;
+import com.sap.ai.sdk.foundationmodels.openai.realtime.OpenAiRealtimeClient;
 import com.sap.cloud.sdk.cloudplatform.connectivity.ApacheHttpClient5Accessor;
 import com.sap.cloud.sdk.cloudplatform.connectivity.DefaultHttpDestination;
 import com.sap.cloud.sdk.cloudplatform.connectivity.Destination;
@@ -76,6 +77,18 @@ public static OpenAiClient forModel(@Nonnull final OpenAiModel foundationModel)
     return client.withApiVersion(DEFAULT_API_VERSION);
   }
 
+  /**
+   * Creates and configures OpenAI Realtime API client
+   *
+   * @return created client
+   */
+  @Beta
+  @Nonnull
+  public static OpenAiRealtimeClient realtimeClient() {
+    final var withResolvedDestination = OpenAiClient.forModel(OpenAiModel.GPT_REALTIME);
+    return new OpenAiRealtimeClient(withResolvedDestination.destination);
+  }
+
   /**
    * Create a new OpenAI client targeting the specified API version.
    *

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

@@ -121,7 +121,7 @@ public record OpenAiModel(@Nonnull String name, @Nullable String version) implem
   /** Azure OpenAI GPT-5-nano model */
   public static final OpenAiModel GPT_5_NANO = new OpenAiModel("gpt-5-nano", null);
 
-  /** Azure OpenAI GPT-5-nano model */
+  /** Azure OpenAI GPT-realtime model */
   public static final OpenAiModel GPT_REALTIME = new OpenAiModel("gpt-realtime", null);
 
   /** Azure OpenAI GPT-5.2 model */

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

@@ -0,0 +1,17 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Allows to input (send) text to the open channel, must be closed when not needed anymore (e.g.
+ * try-with-resources)
+ */
+public interface TextInputChannel extends AutoCloseable {
+
+  /**
+   * Sends input text
+   *
+   * @param text text to send
+   */
+  void sendText(@Nonnull final String text);
+}

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

@@ -0,0 +1,18 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import javax.annotation.Nonnull;
+
+/** Functional interface representing text output channel (text data consumer) */
+public interface TextOutputChannel {
+
+  /**
+   * This method is sequentially invoked by text data provider to supply implementer (consumer) with
+   * the text data.
+   *
+   * @param textChunk chunk of the text (possibly partial content)
+   * @param isLast true if this call logically concludes previous and this passed text data into a
+   *     single logical entity (e.g. gets called at the end when all parts of a single message get
+   *     passed)
+   */
+  void outputText(@Nonnull final CharSequence textChunk, final boolean isLast);
+}

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

@@ -0,0 +1,60 @@
+package com.sap.ai.sdk.foundationmodels.openai.realtime;
+
+import java.net.http.WebSocket;
+import java.nio.ByteBuffer;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+import javax.annotation.Nonnull;
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
+class BufferedWebSocketListener implements WebSocket.Listener {
+
+  private final Consumer<WebSocket> onOpen;
+  private final BiConsumer<WebSocket, CharSequence> onText;
+  private final StringBuilder buffer;
+
+  BufferedWebSocketListener(
+      @Nonnull final Consumer<WebSocket> onOpen,
+      @Nonnull final BiConsumer<WebSocket, CharSequence> onText) {
+    this.onOpen = onOpen;
+    this.onText = onText;
+    this.buffer = new StringBuilder(128 * 1024);
+  }
+
+  @Override
+  public void onOpen(@Nonnull final WebSocket webSocket) {
+    this.onOpen.accept(webSocket);
+    webSocket.request(1);
+  }
+
+  @Override
+  @Nonnull
+  public CompletionStage<?> onText(
+      final @Nonnull WebSocket webSocket, final @Nonnull CharSequence data, final boolean isLast) {
+    buffer.append(data);
+    webSocket.request(1);
+    if (isLast) {
+      final var completeMessage = buffer.toString();
+      buffer.setLength(0);
+      this.onText.accept(webSocket, completeMessage);
+    }
+
+    return CompletableFuture.completedStage(null);
+  }
+
+  @Override
+  public void onError(@Nonnull final WebSocket webSocket, @Nonnull final Throwable error) {
+    log.error("Websocket error occurred during realtime communication", error);
+  }
+
+  @Override
+  @Nonnull
+  public CompletionStage<?> onBinary(
+      @Nonnull final WebSocket webSocket, @Nonnull final ByteBuffer data, final boolean isLast) {
+    log.warn("Received unexpected binary bytes for WebSocket connection");
+    return CompletableFuture.completedStage(null);
+  }
+}