Merge branch 'main' into spec-update/core/main

.github/workflows/spec-update.yaml

@@ -45,7 +45,7 @@ jobs:
       - uses: sap/ai-sdk-js/.github/actions/setup@main
         with:
           node-version: 20
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.GH_CLOUD_SDK_JS_ADMIN_WRITE_TOKEN }}
 
       - name: "Checkout or Create Branch"
         id: branch
@@ -134,7 +134,7 @@ jobs:
         id: create-pr
         if: ${{ env.CREATE_PR == 'true' && steps.spec_diff.outputs.spec_diff == 'true'}}
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GH_CLOUD_SDK_JS_ADMIN_WRITE_TOKEN }}
           BRANCH: ${{ steps.branch.outputs.branch }}
         run: |
           if gh pr list --head $BRANCH --json number -q '.[].number' | grep -q .; then

packages/ai-api/src/utils/deployment-resolver.ts

@@ -127,7 +127,7 @@ export async function resolveDeploymentId(
 
   if (!deployments.length) {
     throw new Error(
-      'No deployment matched the given criteria: ' + JSON.stringify(opts)
+      `No deployment matched the given criteria: ${JSON.stringify(opts)}. Make sure the deployment is successful, as it is a prerequisite before consuming orchestration or foundation models.`
     );
   }
   return deployments[0].id;

packages/orchestration/README.md

@@ -11,7 +11,9 @@ This package incorporates generative AI orchestration capabilities into your AI
 - [Orchestration Service](#orchestration-service)
 - [Relationship between Orchestration and Resource Groups](#relationship-between-orchestration-and-resource-groups)
 - [Usage](#usage)
+  - [LLM Config](#llm-config)
   - [Templating](#templating)
+  - [Prompt Registry](#prompt-registry)
   - [Content Filtering](#content-filtering)
   - [Data Masking](#data-masking)
   - [Grounding](#grounding)
@@ -65,28 +67,44 @@ Consequently, each orchestration deployment uniquely maps to a resource group wi
 ## Usage
 
 Leverage the orchestration service capabilities by using the orchestration client.
-Configure the LLM module by setting the `model_name` property.
-Define the optional `model_version` property to choose an available model version.
-By default, the version is set to `latest`.
-Specify the optional `model_params` property to apply specific parameters to the model
+You can perform a simple prompt by running:
 
 ```ts
 import { OrchestrationClient } from '@sap-ai-sdk/orchestration';
 
 const orchestrationClient = new OrchestrationClient({
   llm: {
-    model_name: 'gpt-4o',
-    model_params: { max_tokens: 50, temperature: 0.1 },
-    model_version: 'latest'
+    model_name: 'gpt-4o'
   },
-  ...
+  templating: {
+    template: [
+      { role: 'user', content: 'Hello World! Why is this phrase so famous?' }
+    ]
+  }
 });
+
+const response = await orchestrationClient.chatCompletion();
+console.log(response.getContent());
 ```
 
-The client allows you to combine various modules, such as templating and content filtering, while sending chat completion requests to an orchestration-compatible generative AI model.
+Here we use GPT-4o with a single user message as prompt and print out the response.
+
+The `OrchestrationClient` enables combining various modules, such as templating and content filtering, while sending chat completion requests to an orchestration-compatible generative AI model.
 
 In addition to the examples below, you can find more **sample code** [here](https://github.com/SAP/ai-sdk-js/blob/main/sample-code/src/orchestration.ts).
 
+### LLM Config
+
+Choose the LLM by setting the `model_name` property.
+Optionally, define `model_version` (default: `latest`) and `model_params` for custom settings.
+
+> [!Tip]
+>
+> #### Harmonized API
+>
+> The Orchestration Service provides a [harmonized API](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/harmonized-api) for all models.
+> Switching to a different model — even from another vendor — only requires changing the `model_name` property.
+
 ### Templating
 
 Use the orchestration client with templating to pass a prompt containing placeholders that will be replaced with input parameters during a chat completion request.
@@ -135,27 +153,29 @@ console.log(
 );
 ```
 
-> [!Tip]
->
-> #### Harmonized API
->
-> As the orchestration service API is harmonized, you can switch to a different model, even from another vendor, by changing only the `model_name` property.
-> Here’s an example where only one line of code is changed.
->
-> ```ts
-> const orchestrationClient = new OrchestrationClient({
->   llm: {
->     // only change the model name here
->     model_name: 'gemini-1.5-flash',
->     model_params: { max_tokens: 50, temperature: 0.1 }
->   },
->   templating: {
->     template: [
->       { role: 'user', content: 'What is the capital of {{?country}}?' }
->     ]
->   }
-> });
-> ```
+### Prompt Registry
+
+Alternatively, prepared templates from the [Prompt Registry](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/prompt-registry) of SAP AI Core can be used instead of passing a template in the request.
+
+```ts
+const orchestrationClient = new OrchestrationClient({
+  llm,
+  templating: {
+    template_ref: {
+      name: 'get-capital',
+      scenario: 'e2e-test',
+      version: '0.0.1'
+    }
+  }
+});
+
+return orchestrationClient.chatCompletion({
+  inputParams: { input: 'France' }
+});
+```
+
+A prompt template can be referenced either by ID, or by using a combination of name, scenario, and version.
+For details on storing a template in the Prompt Registry, refer to [this guide](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-prompt-template-imperative).
 
 #### Passing a Message History
 

packages/orchestration/src/client/api/schema/llama-guard-38-b-filter-config.ts

@@ -14,4 +14,4 @@ export type LlamaGuard38BFilterConfig = {
    */
   type: 'llama_guard_3_8b';
   config: LlamaGuard38B;
-} & Record<string, any>;
+};

packages/orchestration/src/spec/api.yaml

@@ -1,11 +1,11 @@
 openapi: 3.0.0
 
 info:
-  title: Orchestration
-  description: Orchestration is an inference service which provides common additional capabilities for business AI scenarios, such as content filtering and data masking. At the core of the service is the LLM module which allows for an easy, harmonized access to the language models of gen AI hub. The service is designed to be modular and extensible, allowing for the addition of new modules in the future. Each module can be configured independently and at runtime, allowing for a high degree of flexibility in the orchestration of AI services.
+  title: Internal Orchestration Service API
+  description: SAP AI Core - Orchestration Service API
   contact:
     name: SAP AI Core
-  version: 0.48.2
+  version: 0.0.1
 
 servers:
   - url: '/v1'
@@ -849,6 +849,7 @@ components:
       required:
         - type
         - config
+      additionalProperties: false
       properties:
         type:
           description: Name of the filter provider type

sample-code/src/index.ts

@@ -8,6 +8,7 @@ export {
 export {
   orchestrationChatCompletion,
   orchestrationTemplating,
+  orchestrationPromptRegistry,
   orchestrationInputFiltering,
   orchestrationOutputFiltering,
   orchestrationRequestConfig,

sample-code/src/orchestration.ts

@@ -140,6 +140,27 @@ export async function orchestrationTemplating(): Promise<OrchestrationResponse>
   });
 }
 
+/**
+ * Use a template stored in the prompt registry.
+ * @returns The orchestration service response.
+ */
+export async function orchestrationPromptRegistry(): Promise<OrchestrationResponse> {
+  const orchestrationClient = new OrchestrationClient({
+    llm,
+    templating: {
+      template_ref: {
+        name: 'get-capital',
+        scenario: 'e2e-test',
+        version: '0.0.1'
+      }
+    }
+  });
+
+  return orchestrationClient.chatCompletion({
+    inputParams: { input: 'France' }
+  });
+}
+
 const templating = { template: [{ role: 'user', content: '{{?input}}' }] };
 
 /**

sample-code/src/server.ts

@@ -18,7 +18,8 @@ import {
   orchestrationGroundingVector,
   orchestrationChatCompletionImage,
   chatCompletionStreamWithJsonModuleConfig as orchestrationChatCompletionStreamWithJsonModuleConfig,
-  orchestrationGroundingHelpSapCom
+  orchestrationGroundingHelpSapCom,
+  orchestrationPromptRegistry
 } from './orchestration.js';
 import {
   getDeployments,
@@ -253,6 +254,7 @@ app.get('/orchestration/:sampleCase', async (req, res) => {
     {
       simple: orchestrationChatCompletion,
       template: orchestrationTemplating,
+      templateRef: orchestrationPromptRegistry,
       inputFiltering: orchestrationInputFiltering,
       outputFiltering: orchestrationOutputFiltering,
       requestConfig: orchestrationRequestConfig,

tests/e2e-tests/src/orchestration.test.ts

@@ -1,6 +1,7 @@
 import {
   orchestrationChatCompletion,
   orchestrationTemplating,
+  orchestrationPromptRegistry,
   orchestrationInputFiltering,
   orchestrationOutputFiltering,
   orchestrationRequestConfig,
@@ -35,6 +36,12 @@ describe('orchestration', () => {
     assertContent(response);
   });
 
+  it('should complete a chat with a template reference', async () => {
+    const response = await orchestrationPromptRegistry();
+
+    assertContent(response);
+  });
+
   it('should trigger an input filter', async () => {
     await orchestrationInputFiltering();
   });