feat: Add descriptive constant for Azure content filter configuration

packages/orchestration/README.md

@@ -269,7 +269,14 @@ This feature allows filtering both the [input](https://help.sap.com/docs/sap-ai-
 
 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.
+Each category can be assigned a specific severity level, which corresponds to an Azure threshold value.
+
+| Severity Level          | Azure Threshold Value |
+| ----------------------- | --------------------- |
+| `ALLOW_SAFE`            | 0                     |
+| `ALLOW_SAFE_LOW`        | 2                     |
+| `ALLOW_SAFE_LOW_MEDIUM` | 4                     |
+| `ALLOW_ALL`             | 6                     |
 
 Here is a complete example of using an Azure content filter for both input and output:
 
@@ -283,7 +290,10 @@ const templating = {
   template: [{ role: 'user', content: '{{?input}}' }]
 };
 
-const filter = buildAzureContentSafetyFilter({ Hate: 2, Violence: 4 });
+const filter = buildAzureContentSafetyFilter({
+  Hate: 'ALLOW_SAFE_LOW',
+  Violence: 'ALLOW_SAFE_LOW_MEDIUM'
+});
 const orchestrationClient = new OrchestrationClient({
   llm,
   templating,

packages/orchestration/src/index.ts

@@ -8,7 +8,8 @@ export type {
   StreamOptions,
   DocumentGroundingServiceConfig,
   DocumentGroundingServiceFilter,
-  LlmModelParams
+  LlmModelParams,
+  AzureContentFilter
 } from './orchestration-types.js';
 
 export { OrchestrationStreamResponse } from './orchestration-stream-response.js';

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

@@ -163,10 +163,20 @@ describe('orchestration service client', () => {
       },
       filtering: {
         input: {
-          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 2 })]
+          filters: [
+            buildAzureContentSafetyFilter({
+              Hate: 'ALLOW_SAFE_LOW_MEDIUM',
+              SelfHarm: 'ALLOW_SAFE_LOW'
+            })
+          ]
         },
         output: {
-          filters: [buildAzureContentSafetyFilter({ Sexual: 0, Violence: 4 })]
+          filters: [
+            buildAzureContentSafetyFilter({
+              Sexual: 'ALLOW_SAFE',
+              Violence: 'ALLOW_SAFE_LOW_MEDIUM'
+            })
+          ]
         }
       }
     };

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

@@ -170,7 +170,12 @@ describe('construct completion post request', () => {
       ...defaultConfig,
       filtering: {
         input: {
-          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 0 })]
+          filters: [
+            buildAzureContentSafetyFilter({
+              Hate: 'ALLOW_SAFE_LOW_MEDIUM',
+              SelfHarm: 'ALLOW_SAFE'
+            })
+          ]
         }
       }
     };
@@ -212,7 +217,12 @@ describe('construct completion post request', () => {
       ...defaultConfig,
       filtering: {
         output: {
-          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 0 })]
+          filters: [
+            buildAzureContentSafetyFilter({
+              Hate: 'ALLOW_SAFE_LOW_MEDIUM',
+              SelfHarm: 'ALLOW_SAFE'
+            })
+          ]
         }
       }
     };

packages/orchestration/src/orchestration-types.ts

@@ -166,3 +166,42 @@ export interface DocumentGroundingServiceConfig {
    */
   output_param: string;
 }
+
+/**
+ * Filter configuration for Azure content safety Filter.
+ */
+export interface AzureContentFilter {
+  /**
+   * The filter category for hate content.
+   */
+  Hate?: AzureFilterThreshold;
+  /**
+   * The filter category for self-harm content.
+   */
+  SelfHarm?: AzureFilterThreshold;
+  /**
+   * The filter category for sexual content.
+   */
+  Sexual?: AzureFilterThreshold;
+  /**
+   * The filter category for violence content.
+   */
+  Violence?: AzureFilterThreshold;
+}
+
+/**
+ * A descriptive constant for Azure content safety filter threshold.
+ * @internal
+ */
+export const supportedAzureFilterThresholds = {
+  ALLOW_SAFE: 0,
+  ALLOW_SAFE_LOW: 2,
+  ALLOW_SAFE_LOW_MEDIUM: 4,
+  ALLOW_ALL: 6
+} as const;
+
+/**
+ * The Azure threshold level supported for each azure content filter category.
+ * @internal
+ */
+export type AzureFilterThreshold = keyof typeof supportedAzureFilterThresholds;

packages/orchestration/src/util/filtering.test.ts

@@ -184,8 +184,8 @@ describe('Content filter util', () => {
   describe('Azure content filter', () => {
     it('builds filter config', async () => {
       const filterConfig = buildAzureContentSafetyFilter({
-        Hate: 4,
-        SelfHarm: 0
+        Hate: 'ALLOW_SAFE_LOW_MEDIUM',
+        SelfHarm: 'ALLOW_SAFE'
       });
       const expectedFilterConfig: FilterConfig = {
         type: 'azure_content_safety',

packages/orchestration/src/util/filtering.ts

@@ -1,9 +1,14 @@
+import { supportedAzureFilterThresholds } from '../orchestration-types.js';
 import type {
   AzureContentSafety,
   AzureContentSafetyFilterConfig,
   InputFilteringConfig,
   OutputFilteringConfig
 } from '../client/api/schema/index.js';
+import type {
+  AzureContentFilter,
+  AzureFilterThreshold
+} from '../orchestration-types.js';
 
 /**
  * Convenience function to create Azure content filters.
@@ -33,13 +38,22 @@ export function buildAzureContentFilter(
  * @returns Filter config object.
  */
 export function buildAzureContentSafetyFilter(
-  config?: AzureContentSafety
+  config?: AzureContentFilter
 ): AzureContentSafetyFilterConfig {
   if (config && !Object.keys(config).length) {
     throw new Error('Filtering configuration cannot be an empty object');
   }
   return {
     type: 'azure_content_safety',
-    ...(config && { config })
+    ...(config && {
+      config: {
+        ...Object.fromEntries(
+          Object.entries(config).map(([key, value]) => [
+            key,
+            supportedAzureFilterThresholds[value as AzureFilterThreshold]
+          ])
+        )
+      }
+    })
   };
 }

packages/orchestration/src/util/request-config.test.ts

@@ -74,7 +74,12 @@ describe('stream util tests', () => {
       ...defaultOrchestrationModuleConfig,
       filtering: {
         output: {
-          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 0 })]
+          filters: [
+            buildAzureContentSafetyFilter({
+              Hate: 'ALLOW_SAFE_LOW_MEDIUM',
+              SelfHarm: 'ALLOW_SAFE'
+            })
+          ]
         }
       }
     };
@@ -93,7 +98,12 @@ describe('stream util tests', () => {
       ...defaultModuleConfigs,
       filtering_module_config: {
         output: {
-          filters: [buildAzureContentSafetyFilter({ Hate: 4, SelfHarm: 0 })]
+          filters: [
+            buildAzureContentSafetyFilter({
+              Hate: 'ALLOW_SAFE_LOW_MEDIUM',
+              SelfHarm: 'ALLOW_SAFE'
+            })
+          ]
         }
       }
     };

sample-code/src/orchestration.ts

@@ -170,8 +170,8 @@ export async function orchestrationInputFiltering(): Promise<void> {
   // create a filter with minimal thresholds for hate and violence
   // lower numbers mean more strict filtering
   const azureContentFilter = buildAzureContentSafetyFilter({
-    Hate: 0,
-    Violence: 0
+    Hate: 'ALLOW_SAFE',
+    Violence: 'ALLOW_SAFE'
   });
   const orchestrationClient = new OrchestrationClient({
     llm,
@@ -207,8 +207,8 @@ export async function orchestrationOutputFiltering(): Promise<OrchestrationRespo
   // output filters are build in the same way as input filters
   // set the thresholds to the minimum to maximize the chance the LLM output will be filtered
   const azureContentFilter = buildAzureContentSafetyFilter({
-    Hate: 0,
-    Violence: 0
+    Hate: 'ALLOW_SAFE',
+    Violence: 'ALLOW_SAFE'
   });
   const orchestrationClient = new OrchestrationClient({
     llm,

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

@@ -1,6 +1,7 @@
 import { expectError, expectType, expectAssignable } from 'tsd';
 import {
   OrchestrationClient,
+  buildAzureContentSafetyFilter,
   buildDocumentGroundingConfig
 } from '@sap-ai-sdk/orchestration';
 import type {
@@ -9,7 +10,8 @@ import type {
   TokenUsage,
   ChatModel,
   GroundingModuleConfig,
-  LlmModelParams
+  LlmModelParams,
+  AzureContentSafetyFilterConfig
 } from '@sap-ai-sdk/orchestration';
 
 /**
@@ -244,6 +246,26 @@ expectType<Promise<OrchestrationResponse>>(
 expect<ChatModel>('custom-model');
 expect<ChatModel>('gemini-1.0-pro');
 
+/**
+ * FilteringUtil.
+ */
+
+expectType<AzureContentSafetyFilterConfig>(
+  buildAzureContentSafetyFilter({
+    Hate: 'ALLOW_ALL',
+    SelfHarm: 'ALLOW_SAFE_LOW',
+    Sexual: 'ALLOW_SAFE_LOW_MEDIUM',
+    Violence: 'ALLOW_SAFE'
+  })
+);
+
+expectError<AzureContentSafetyFilterConfig>(
+  buildAzureContentSafetyFilter({
+    Hate: 2,
+    SelfHarm: 4
+  })
+);
+
 /**
  * Grounding util.
  */