Merge branch 'main' into chore/refactor-core-classes

Author: MatKuhr

.github/workflows/prepare-release.yaml

@@ -59,6 +59,11 @@ jobs:
           git add .
           git commit -m "Update to version ${{ steps.determine-versions.outputs.RELEASE_VERSION }}"
 
+          # Create release notes
+          python .pipeline/scripts/release_notes_automation.py --version ${{ steps.determine-versions.outputs.RELEASE_VERSION }} --folder "docs/release-notes"
+          git add .
+          git commit -m "Add new release notes"
+
           # We need to get the commit id, and push the branch so the release tag will point at the right commit afterwards
           RELEASE_COMMIT_ID=$(git log -1 --pretty=format:"%H")
           echo "RELEASE_COMMIT_ID=$RELEASE_COMMIT_ID" >> $GITHUB_OUTPUT
@@ -135,11 +140,16 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global user.name "SAP Cloud SDK Bot"
 
-      - name: "Set New Version"
+      - name: "Set New Version and Reset Release Notes"
         run: |
           python .pipeline/scripts/set-release-versions.py --version ${{ needs.bump-version.outputs.new-version }}
           git add .
           git commit -m "Update to version ${{ needs.bump-version.outputs.new-version }}"
+          
+          # Reset release notes for next version
+          cp .pipeline/scripts/release_notes_template.md docs/release-notes/release_notes.md
+          git add docs/release-notes/release_notes.md
+          git commit -m "Reset release notes"
           git push
 
       - name: "Create Code PR"
@@ -148,7 +158,6 @@ jobs:
           
           PR_URL=$(gh pr create --title "Release ${{ needs.bump-version.outputs.release-version }}" --body "## TODOs
           - [ ] Review the changes in [the release commit]($COMMIT_URL)
-          - [ ] Update the Release notes
           - [ ] Review the [Draft Release](${{ needs.create-release.outputs.release-url }})
           - [ ] Review **and approve** this PR
           - [ ] Trigger the [Perform Release Workflow](${{ github.event.repository.html_url }}/actions/workflows/perform-release.yml)

.pipeline/scripts/release_notes_automation.py

@@ -0,0 +1,110 @@
+import argparse
+import os
+import re
+from datetime import datetime
+
+
+def read_file(file_name):
+    with open(file_name, 'r', encoding="utf8") as file:
+        return file.read()
+
+
+def write_file(file_name, data):
+    with open(file_name, 'w', encoding="utf8") as file:
+        file.write(data)
+
+unchanged_sections = [
+"""### 🚧 Known Issues
+
+-
+
+""",
+"""### 🔧 Compatibility Notes
+
+-
+
+""",
+"""### ✨ New Functionality
+
+-
+
+""",
+"""### 📈 Improvements
+
+-
+
+""",
+"""### 🐛 Fixed Issues
+
+- 
+"""]
+
+def remove_unchanged_sections(file, unchanged_sections):
+    for unchanged_section in unchanged_sections:
+        # if file contains unchanged_section, remove it
+        file = re.sub(unchanged_section, "", file)
+    return file
+
+def set_header(file, version):
+    date = datetime.today().strftime('%B %d, %Y')
+    # Replace the first line with: ## 5.2.0 - January 17, 2024
+    file = re.sub("^## .*", "## " + version + " - " + date, file)
+    return file
+
+def link_github_release(file, version):
+    old_github_release_link = "\[All Release Changes\]\(https://github.com/SAP/ai-sdk-java/releases/\)"
+    new_github_release_link = "[All Release Changes](https://github.com/SAP/ai-sdk-java/releases/tag/rel%2F"+version+")"
+    file = re.sub(old_github_release_link, new_github_release_link, file)
+    return file
+
+
+
+releases_pattern = re.compile(r"^## ")
+def count_releases(filename):
+    count = 0
+    with open(filename, 'r', encoding="utf-8") as file:
+        for line in file:
+            if releases_pattern.match(line):
+                count += 1
+    return count
+
+def find_target_file(version):
+    # release-notes-X-to-Y.mdx with every 15 versions the index increases by 15 and stays the same for 15 versions
+    minor_version = int(version.split(".")[1])
+    index = minor_version // 15 * 15
+    return "release-notes-" + str(index) + "-to-" + str(index + 14) + ".mdx"
+
+def write_release_notes(folder, target_file):
+    absolute_target_file = os.path.join(folder, target_file)
+
+    # if target_file is a file, prepend the new release notes at the top
+    if os.path.isfile(absolute_target_file):
+        existing_file = read_file(absolute_target_file)
+        write_file(absolute_target_file, file + "\n" + existing_file)
+    # if target_file is not a file, create it
+    else:
+        write_file(absolute_target_file, file)
+
+
+file_name = "docs/release-notes/release_notes.md"
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='SAP Cloud SDK for AI (for Java) - Release Notes formatting script.')
+
+    parser.add_argument('--version', metavar='VERSION', help='The version to be released.', required=True)
+    parser.add_argument('--folder', metavar='FOLDER', help='The ai-sdk-java/docs/release-notes folder.', required=True)
+    args = parser.parse_args()
+
+    file = read_file(file_name)
+    file = remove_unchanged_sections(file, unchanged_sections)
+    file = set_header(file, args.version)
+    file = link_github_release(file, args.version)
+
+    target_file = find_target_file(args.version)
+
+
+    folder_path = args.folder
+    write_release_notes(folder_path, target_file)
+
+    # delete (temporary) release-notes file so it does not appear in the released version
+    os.remove(file_name)

.pipeline/scripts/release_notes_template.md

@@ -0,0 +1,23 @@
+## 0.X.0-SNAPSHOT
+
+[All Release Changes](https://github.com/SAP/ai-sdk-java/releases/)
+
+### 🚧 Known Issues
+
+-
+
+### 🔧 Compatibility Notes
+
+-
+
+### ✨ New Functionality
+
+-
+
+### 📈 Improvements
+
+-
+
+### 🐛 Fixed Issues
+
+- 

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -200,12 +200,10 @@ Change your LLM configuration to add model parameters:
 ```java
 OrchestrationAiModel customGPT4O =
     OrchestrationAiModel.GPT_4O
-        .withParams(
-            Map.of(
-                "max_tokens", 50,
-                "temperature", 0.1,
-                "frequency_penalty", 0,
-                "presence_penalty", 0))
+        .withParam(MAX_TOKENS, 50)
+        .withParam(TEMPERATURE, 0.1)
+        .withParam(FREQUENCY_PENALTY, 0)
+        .withParam(PRESENCE_PENALTY, 0)
         .withVersion("2024-05-13");
 ```
 
@@ -225,4 +223,4 @@ var prompt = new OrchestrationPrompt(Map.of("your-input-parameter", "your-param-
 new OrchestrationClient().executeRequestFromJsonModuleConfig(prompt, configJson);
 ```
 
-While this is not recommended for long term use, it can be useful for creating demos and PoCs.
+While this is not recommended for long term use, it can be useful for creating demos and PoCs.

docs/release-notes/release_notes.md

@@ -0,0 +1,23 @@
+## 0.X.0-SNAPSHOT
+
+[All Release Changes](https://github.com/SAP/ai-sdk-java/releases/)
+
+### 🚧 Known Issues
+
+-
+
+### 🔧 Compatibility Notes
+
+-
+
+### ✨ New Functionality
+
+-
+
+### 📈 Improvements
+
+-
+
+### 🐛 Fixed Issues
+
+- 

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

@@ -0,0 +1,17 @@
+package com.sap.ai.sdk.orchestration;
+
+import javax.annotation.Nonnull;
+import lombok.Value;
+import lombok.experimental.Accessors;
+
+/** Represents a chat message as 'assistant' to the orchestration service. */
+@Value
+@Accessors(fluent = true)
+public class AssistantMessage implements Message {
+
+  /** The role of the assistant. */
+  @Nonnull String role = "assistant";
+
+  /** The content of the message. */
+  @Nonnull String content;
+}

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

@@ -31,7 +31,8 @@ static CompletionPostRequest toCompletionPostRequest(
         .orchestrationConfig(
             OrchestrationConfig.create().moduleConfigurations(toModuleConfigs(configCopy)))
         .inputParams(prompt.getTemplateParameters())
-        .messagesHistory(prompt.getMessagesHistory());
+        .messagesHistory(
+            prompt.getMessagesHistory().stream().map(Message::createChatMessage).toList());
   }
 
   @Nonnull
@@ -46,7 +47,8 @@ static TemplatingModuleConfig toTemplateModuleConfig(
      */
     val messages = template instanceof Template t ? t.getTemplate() : List.<ChatMessage>of();
     val messagesWithPrompt = new ArrayList<>(messages);
-    messagesWithPrompt.addAll(prompt.getMessages());
+    messagesWithPrompt.addAll(
+        prompt.getMessages().stream().map(Message::createChatMessage).toList());
     if (messagesWithPrompt.isEmpty()) {
       throw new IllegalStateException(
           "A prompt is required. Pass at least one message or configure a template with messages or a template reference.");

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

@@ -0,0 +1,67 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.sap.ai.sdk.orchestration.model.ChatMessage;
+import javax.annotation.Nonnull;
+
+/** Interface representing convenience wrappers of chat message to the orchestration service. */
+public sealed interface Message permits UserMessage, AssistantMessage, SystemMessage {
+
+  /**
+   * A convenience method to create a user message.
+   *
+   * @param msg the message content.
+   * @return the user message.
+   */
+  @Nonnull
+  static UserMessage user(@Nonnull final String msg) {
+    return new UserMessage(msg);
+  }
+
+  /**
+   * A convenience method to create an assistant message.
+   *
+   * @param msg the message content.
+   * @return the assistant message.
+   */
+  @Nonnull
+  static AssistantMessage assistant(@Nonnull final String msg) {
+    return new AssistantMessage(msg);
+  }
+
+  /**
+   * A convenience method to create a system message.
+   *
+   * @param msg the message content.
+   * @return the system message.
+   */
+  @Nonnull
+  static SystemMessage system(@Nonnull final String msg) {
+    return new SystemMessage(msg);
+  }
+
+  /**
+   * Converts the message to a serializable ChatMessage object.
+   *
+   * @return the corresponding {@code ChatMessage} object.
+   */
+  @Nonnull
+  default ChatMessage createChatMessage() {
+    return ChatMessage.create().role(role()).content(content());
+  }
+
+  /**
+   * Returns the role of the assistant.
+   *
+   * @return the role.
+   */
+  @Nonnull
+  String role();
+
+  /**
+   * Returns the content of the message.
+   *
+   * @return the content.
+   */
+  @Nonnull
+  String content();
+}