refactor: Content filter helper function

.changeset/afraid-cooks-shave.md

@@ -0,0 +1,6 @@
+---
+'@sap-ai-sdk/orchestration': minor
+---
+
+[Compatibility Note] Deprecate `buildAzureContentFilter()` function since it restricts filtering to have only one filter.
+Use `buildAzureContentSafetyFilter()` function instead.

packages/orchestration/README.md

@@ -245,24 +245,35 @@
 
 This feature allows filtering both the [input](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/input-filtering) and [output](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering) of a model based on content safety criteria.
 
-```ts
-import {
-  OrchestrationClient,
-  buildAzureContentFilter
-} from '@sap-ai-sdk/orchestration';
+#### Azure Content Filter
+
+Use `buildAzureContentSafetyFilter()` function to build an Azure content filter.
+The Azure content filter supports four categories: `Hate`, `Violence`, `Sexual`, and `SelfHarm`.
+Each category can be configured with severity levels of 0, 2, 4, or 6.
+
+Here is a complete example of using an Azure content filter for both input and output:
 
-const filter = buildAzureContentFilter({ Hate: 2, Violence: 4 });
+```ts
+import { OrchestrationClient, ContentFilters } from '@sap-ai-sdk/orchestration';
+const llm = {
+  model_name: 'gpt-4o',
+  model_params: { max_tokens: 50, temperature: 0.1 }
+};
+const templating = {
+  template: [{ role: 'user', content: '{{?input}}' }]
+};
+
+const filter = buildAzureContentSafetyFilter({ Hate: 2, Violence: 4 });
 const orchestrationClient = new OrchestrationClient({
-  llm: {
-    model_name: 'gpt-4o',
-    model_params: { max_tokens: 50, temperature: 0.1 }
-  },
-  templating: {
-    template: [{ role: 'user', content: '{{?input}}' }]
-  },
+  llm,
+  templating,
   filtering: {
-    input: filter,
-    output: filter
+    input: {
+      filters: [filter]
+    },
+    output: {
+      filters: [filter]
+    }
   }
 });
 
@@ -276,23 +287,19 @@
 }
 ```
 
+#### Error Handling
+
 Both `chatCompletion()` and `getContent()` methods can throw errors.
 
-- **axios errors**:  
+- **Axios Errors**:  
   When the chat completion request fails with a `400` status code, the caught error will be an `Axios` error.
   The property `error.response.data.message` may provide additional details about the failure's cause.
 
-- **output content filtered**:  
-  The method `getContent()` can throw an error if the output filter filters the model output.
+- **Output Content Filtered**:  
+  The `getContent()` method can throw an error if the output filter filters the model output.
   This can occur even if the chat completion request responds with a `200` HTTP status code.
   The `error.message` property indicates if the output was filtered.
 
-Therefore, handle errors appropriately to ensure meaningful feedback for both types of errors.
-
-`buildAzureContentFilter()` is a convenience function that creates an Azure content filter configuration based on the provided inputs.
-The Azure content filter supports four categories: `Hate`, `Violence`, `Sexual`, and `SelfHarm`.
-Each category can be configured with severity levels of 0, 2, 4, or 6.
-
 ### Data Masking
 
 You can anonymize or pseudonomize the prompt using the data masking capabilities of the orchestration service.

packages/orchestration/src/index.ts

@@ -21,8 +21,9 @@ export { OrchestrationClient } from './orchestration-client.js';
 
 export {
   buildAzureContentFilter,
+  buildAzureContentSafetyFilter,
   buildDocumentGroundingConfig
-} from './orchestration-utils.js';
+} from './util/index.js';
 
 export { OrchestrationResponse } from './orchestration-response.js';
 

packages/orchestration/src/internal.ts

@@ -1,4 +1,4 @@
 export * from './orchestration-client.js';
-export * from './orchestration-utils.js';
+export * from './util/index.js';
 export * from './orchestration-types.js';
 export * from './orchestration-response.js';

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

@@ -9,12 +9,12 @@ import {
   parseMockResponse
 } from '../../../test-util/mock-http.js';
 import { OrchestrationClient } from './orchestration-client.js';
+import { OrchestrationResponse } from './orchestration-response.js';
 import {
-  buildAzureContentFilter,
+  constructCompletionPostRequestFromJsonModuleConfig,
   constructCompletionPostRequest,
-  constructCompletionPostRequestFromJsonModuleConfig
-} from './orchestration-utils.js';
-import { OrchestrationResponse } from './orchestration-response.js';
+  buildAzureContentSafetyFilter
+} from './util/index.js';
 import type { CompletionPostResponse } from './client/api/schema/index.js';
 import type {
   OrchestrationModuleConfig,
@@ -162,8 +162,12 @@ describe('orchestration service client', () => {
         ]
       },
       filtering: {
-        input: buildAzureContentFilter({ Hate: 4, SelfHarm: 2 }),
-        output: buildAzureContentFilter({ Sexual: 0, Violence: 4 })
+        input: {
+          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 2 })]
+        },
+        output: {
+          filters: [buildAzureContentSafetyFilter({ Sexual: 0, Violence: 4 })]
+        }
       }
     };
     const prompt = {

packages/orchestration/src/orchestration-client.ts

@@ -7,7 +7,7 @@ import { OrchestrationResponse } from './orchestration-response.js';
 import {
   constructCompletionPostRequest,
   constructCompletionPostRequestFromJsonModuleConfig
-} from './orchestration-utils.js';
+} from './util/index.js';
 import type {
   HttpResponse,
   CustomRequestConfig

packages/orchestration/src/orchestration-completion-post-request-from-json.test.ts

@@ -1,4 +1,4 @@
-import { constructCompletionPostRequestFromJsonModuleConfig } from './orchestration-utils.js';
+import { constructCompletionPostRequestFromJsonModuleConfig } from './util/request-config.js';
 
 describe('construct completion post request from JSON', () => {
   it('should construct completion post request from JSON', () => {

packages/orchestration/src/orchestration-completion-post-request.test.ts

@@ -1,7 +1,7 @@
 import {
   constructCompletionPostRequest,
-  buildAzureContentFilter
-} from './orchestration-utils.js';
+  buildAzureContentSafetyFilter
+} from './util/index.js';
 import type { CompletionPostRequest } from './client/api/schema/index.js';
 import type {
   OrchestrationModuleConfig,
@@ -169,7 +169,9 @@ describe('construct completion post request', () => {
     const config: OrchestrationModuleConfig = {
       ...defaultConfig,
       filtering: {
-        input: buildAzureContentFilter({ Hate: 4, SelfHarm: 0 })
+        input: {
+          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 0 })]
+        }
       }
     };
     const expectedCompletionPostRequest: CompletionPostRequest = {
@@ -209,7 +211,9 @@ describe('construct completion post request', () => {
     const config: OrchestrationModuleConfig = {
       ...defaultConfig,
       filtering: {
-        output: buildAzureContentFilter({ Hate: 4, SelfHarm: 0 })
+        output: {
+          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 0 })]
+        }
       }
     };
 

packages/orchestration/src/orchestration-types.ts

@@ -63,6 +63,22 @@ export interface OrchestrationModuleConfig {
   llm: LlmModuleConfig;
   /**
    * Filtering module configuration.
+   * @example
+   * Configuring an input and output filter:
+   * ```ts
+   * filtering: {
+   *   input: {
+   *     filters: [
+   *       buildAzureContentSafetyFilter({ Hate: 0, Violence: 0 })
+   *     ]
+   *   },
+   *   output: {
+   *     filters: [
+   *       buildAzureContentSafetyFilter({ Hate: 0, Violence: 0 })
+   *     ]
+   *   }
+   * }
+   * ```
    */
   filtering?: FilteringModuleConfig;
   /**