chore: Improve UX for Orchestration chat scenario

packages/orchestration/README.md

@@ -132,13 +132,15 @@ const response = await orchestrationClient.chatCompletion({
 const responseContent = response.getContent();
 const finishReason = response.getFinishReason();
 const tokenUsage = response.getTokenUsage();
+const allMessages = response.getAllMessages();
 ```
 
 You can use the following convenience methods for handling chat completion responses:
 
 - `getContent()` parses the response and returns the model's output as a string.
 - `getFinishReason()` retrieves the `finish_reason` explaining why chat completion request stopped.
 - `getTokenUsage()` provides token usage details, including `total_tokens`, `prompt_tokens`, and `completion_tokens`.
+- `getAllMessages()` parses the response and returns a list of all messages.
 
 #### Structured Outputs
 

packages/orchestration/src/orchestration-response.test.ts

@@ -38,6 +38,21 @@ describe('OrchestrationResponse', () => {
     });
   });
 
+  it('should return a list of all messages', () => {
+    const messageList = orchestrationResponse.getAllMessages();
+
+    expect(messageList.length).toBe(2);
+    expect(messageList[0]).toMatchObject({
+      role: 'user',
+      content: expect.any(String)
+    });
+
+    expect(messageList[1]).toEqual({
+      role: 'assistant',
+      content: expect.any(String)
+    });
+  });
+
   it('should return default choice index with convenience functions', () => {
     expect(orchestrationResponse.getFinishReason()).toBe('stop');
     expect(orchestrationResponse.getContent()).toBe(

packages/orchestration/src/orchestration-response.ts

@@ -1,7 +1,11 @@
 import type { HttpResponse } from '@sap-cloud-sdk/http-client';
 import type {
   CompletionPostResponse,
-  TokenUsage
+  TokenUsage,
+  ChatMessage,
+  SingleChatMessage,
+  MultiChatMessage,
+  ChatMessages
 } from './client/api/schema/index.js';
 
 /**
@@ -51,6 +55,56 @@ export class OrchestrationResponse {
     return choice?.message?.content;
   }
 
+  /**
+   * Messages that can be used for subsequent prompts as message history.
+   * @param choiceIndex - The index of the choice to parse.
+   * @returns A list of all messages.
+   */
+  getAllMessages(choiceIndex = 0): ChatMessages {
+    const messages: ChatMessage[] = (
+      this.data.module_results.templating ?? []
+    ).map(message =>
+      this.isMultiChatMessage(message)
+        ? this.handleMultiChatMessage(message as MultiChatMessage)
+        : this.handleSingleChatMessage(message as SingleChatMessage)
+    );
+
+    const content = this.getChoices().find(c => c.index === choiceIndex)
+      ?.message.content;
+    return content ? [...messages, { role: 'assistant', content }] : messages;
+  }
+
+  private handleSingleChatMessage(
+    singleChatMessage: SingleChatMessage
+  ): ChatMessage {
+    return {
+      role: singleChatMessage.role,
+      content: singleChatMessage.content
+    };
+  }
+
+  private handleMultiChatMessage(
+    multiChatMessage: MultiChatMessage
+  ): ChatMessage {
+    return {
+      role: multiChatMessage.role,
+      content: multiChatMessage.content
+        .map(content =>
+          content.type === 'text'
+            ? content.text
+            : JSON.stringify({
+                url: content.image_url.url,
+                detail: content.image_url.detail
+              })
+        )
+        .join('\n')
+    };
+  }
+
+  private isMultiChatMessage(params: ChatMessage): params is MultiChatMessage {
+    return Array.isArray(params.content);
+  }
+
   private getChoices() {
     return this.data.orchestration_result.choices;
   }

sample-code/src/orchestration.ts

@@ -14,7 +14,8 @@ import type {
   OrchestrationStreamChunkResponse,
   OrchestrationStreamResponse,
   OrchestrationResponse,
-  StreamOptions
+  StreamOptions,
+  TemplatingChatMessage
 } from '@sap-ai-sdk/orchestration';
 
 const logger = createLogger({
@@ -142,6 +143,31 @@ export async function orchestrationTemplating(): Promise<OrchestrationResponse>
   });
 }
 
+/**
+ * Chat request to OpenAI through the Orchestration service using message history.
+ * @returns The orchestration service response.
+ */
+export async function orchestrationMessagesHistory(): Promise<OrchestrationResponse> {
+  const orchestrationClient = (messages: TemplatingChatMessage) =>
+    new OrchestrationClient({
+      llm,
+      templating: {
+        template: messages
+      }
+    });
+
+  const firstResponse = await orchestrationClient([
+    { role: 'user', content: 'What is the capital of France?' }
+  ]).chatCompletion();
+
+  // User can then ask a follow-up question
+  const nextResponse = await orchestrationClient([
+    { role: 'user', content: 'Are you sure?' }
+  ]).chatCompletion({ messagesHistory: firstResponse.getAllMessages() });
+
+  return nextResponse;
+}
+
 /**
  * Use a template stored in the prompt registry.
  * @returns The orchestration service response.

sample-code/src/server.ts

@@ -21,6 +21,7 @@ import {
   orchestrationGroundingHelpSapCom,
   orchestrationMaskGroundingInput,
   orchestrationPromptRegistry,
+  orchestrationMessagesHistory,
   orchestrationResponseFormat
 } from './orchestration.js';
 import {
@@ -257,6 +258,7 @@ app.get('/orchestration/:sampleCase', async (req, res) => {
       simple: orchestrationChatCompletion,
       template: orchestrationTemplating,
       templateRef: orchestrationPromptRegistry,
+      messageHistory: orchestrationMessagesHistory,
       inputFiltering: orchestrationInputFiltering,
       outputFiltering: orchestrationOutputFiltering,
       requestConfig: orchestrationRequestConfig,

tests/type-tests/test/orchestration.test-d.ts

@@ -11,7 +11,8 @@ import type {
   ChatModel,
   GroundingModuleConfig,
   LlmModelParams,
-  AzureContentSafetyFilterConfig
+  AzureContentSafetyFilterConfig,
+  ChatMessages
 } from '@sap-ai-sdk/orchestration';
 
 /**
@@ -80,6 +81,19 @@ expectType<TokenUsage>(
   ).getTokenUsage()
 );
 
+expectType<ChatMessages>(
+  (
+    await new OrchestrationClient({
+      templating: {
+        template: [{ role: 'user', content: 'Hello!' }]
+      },
+      llm: {
+        model_name: 'gpt-35-turbo-16k'
+      }
+    }).chatCompletion()
+  ).getAllMessages()
+);
+
 expectType<Promise<OrchestrationResponse>>(
   new OrchestrationClient(
     {