refactor: Content filter helper function

.changeset/afraid-cooks-shave.md

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

packages/orchestration/README.md

@@ -244,24 +244,35 @@
 
 This feature allows filtering both the [input](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/consume-orchestration#content-filtering-on-input) and [output](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/consume-orchestration#content-filtering-on-input) of a model based on content safety criteria.
 
-```ts
-import {
-  OrchestrationClient,
-  buildAzureContentFilter
-} from '@sap-ai-sdk/orchestration';
+#### Azure Content Filter
+
+Use `ContentFilters.azure()` 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 = ContentFilters.azure({ 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]
+    }
   }
 });
 
@@ -275,23 +286,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**:  
+- **Output Content Filtered**:  
   The method `getContent()` 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

@@ -47,7 +47,10 @@ export type {
 
 export { OrchestrationClient } from './orchestration-client.js';
 
-export { buildAzureContentFilter } from './orchestration-utils.js';
+export {
+  buildAzureContentFilter,
+  ContentFilters
+} from './orchestration-filtering.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 './orchestration-filtering.js';
 export * from './orchestration-types.js';
 export * from './orchestration-response.js';

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

@@ -10,7 +10,7 @@ import {
   constructCompletionPostRequest,
   OrchestrationClient
 } from './orchestration-client.js';
-import { buildAzureContentFilter } from './orchestration-utils.js';
+import { ContentFilters } from './orchestration-filtering.js';
 import { OrchestrationResponse } from './orchestration-response.js';
 import type { CompletionPostResponse } from './client/api/schema/index.js';
 import type {
@@ -120,8 +120,12 @@ describe('orchestration service client', () => {
         ]
       },
       filtering: {
-        input: buildAzureContentFilter({ Hate: 4, SelfHarm: 2 }),
-        output: buildAzureContentFilter({ Sexual: 0, Violence: 4 })
+        input: {
+          filters: [ContentFilters.azure({ Hate: 4, SelfHarm: 2 })]
+        },
+        output: {
+          filters: [ContentFilters.azure({ Sexual: 0, Violence: 4 })]
+        }
       }
     };
     const prompt = {

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

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

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

@@ -0,0 +1,194 @@
+import {
+  buildAzureContentFilter,
+  ContentFilters
+} from './orchestration-filtering.js';
+import { constructCompletionPostRequest } from './orchestration-client.js';
+import type { OrchestrationModuleConfig } from './orchestration-types.js';
+import type {
+  CompletionPostRequest,
+  FilterConfig,
+  FilteringModuleConfig
+} from './client/api/schema/index.js';
+
+describe('Content filters', () => {
+  // TOOD: Remove this test collection once `buildAzureContentFilter` is removed.
+  describe('buildAzureContentFilter', () => {
+    const config: OrchestrationModuleConfig = {
+      llm: {
+        model_name: 'gpt-35-turbo-16k',
+        model_params: { max_tokens: 50, temperature: 0.1 }
+      },
+      templating: {
+        template: [
+          { role: 'user', content: 'Create {number} paraphrases of {phrase}' }
+        ]
+      }
+    };
+
+    const prompt = { inputParams: { phrase: 'I hate you.', number: '3' } };
+
+    afterEach(() => {
+      config.filtering = undefined;
+    });
+
+    it('constructs filter configuration with only input', async () => {
+      const filtering: FilteringModuleConfig = {
+        input: buildAzureContentFilter({ Hate: 4, SelfHarm: 0 })
+      };
+      const expectedFilterConfig: FilteringModuleConfig = {
+        input: {
+          filters: [
+            {
+              type: 'azure_content_safety',
+              config: {
+                Hate: 4,
+                SelfHarm: 0
+              }
+            }
+          ]
+        }
+      };
+      config.filtering = filtering;
+      const completionPostRequest: CompletionPostRequest =
+        constructCompletionPostRequest(config, prompt);
+      expect(
+        completionPostRequest.orchestration_config.module_configurations
+          .filtering_module_config
+      ).toEqual(expectedFilterConfig);
+    });
+
+    it('constructs filter configuration with only output', async () => {
+      const filtering: FilteringModuleConfig = {
+        output: buildAzureContentFilter({ Sexual: 2, Violence: 6 })
+      };
+      const expectedFilterConfig: FilteringModuleConfig = {
+        output: {
+          filters: [
+            {
+              type: 'azure_content_safety',
+              config: {
+                Sexual: 2,
+                Violence: 6
+              }
+            }
+          ]
+        }
+      };
+      config.filtering = filtering;
+      const completionPostRequest: CompletionPostRequest =
+        constructCompletionPostRequest(config, prompt);
+      expect(
+        completionPostRequest.orchestration_config.module_configurations
+          .filtering_module_config
+      ).toEqual(expectedFilterConfig);
+    });
+
+    it('constructs filter configuration with both input and output', async () => {
+      const filtering: FilteringModuleConfig = {
+        input: buildAzureContentFilter({
+          Hate: 4,
+          SelfHarm: 0,
+          Sexual: 2,
+          Violence: 6
+        }),
+        output: buildAzureContentFilter({ Sexual: 2, Violence: 6 })
+      };
+      const expectedFilterConfig: FilteringModuleConfig = {
+        input: {
+          filters: [
+            {
+              type: 'azure_content_safety',
+              config: {
+                Hate: 4,
+                SelfHarm: 0,
+                Sexual: 2,
+                Violence: 6
+              }
+            }
+          ]
+        },
+        output: {
+          filters: [
+            {
+              type: 'azure_content_safety',
+              config: {
+                Sexual: 2,
+                Violence: 6
+              }
+            }
+          ]
+        }
+      };
+      config.filtering = filtering;
+      const completionPostRequest: CompletionPostRequest =
+        constructCompletionPostRequest(config, prompt);
+      expect(
+        completionPostRequest.orchestration_config.module_configurations
+          .filtering_module_config
+      ).toEqual(expectedFilterConfig);
+    });
+
+    it('omits filters if not set', async () => {
+      const filtering: FilteringModuleConfig = {
+        input: buildAzureContentFilter(),
+        output: buildAzureContentFilter()
+      };
+      config.filtering = filtering;
+      const completionPostRequest: CompletionPostRequest =
+        constructCompletionPostRequest(config, prompt);
+      const expectedFilterConfig: FilteringModuleConfig = {
+        input: {
+          filters: [
+            {
+              type: 'azure_content_safety'
+            }
+          ]
+        },
+        output: {
+          filters: [
+            {
+              type: 'azure_content_safety'
+            }
+          ]
+        }
+      };
+      expect(
+        completionPostRequest.orchestration_config.module_configurations
+          .filtering_module_config
+      ).toEqual(expectedFilterConfig);
+    });
+
+    it('omits filter configuration if not set', async () => {
+      const filtering: FilteringModuleConfig = {};
+      config.filtering = filtering;
+      const completionPostRequest: CompletionPostRequest =
+        constructCompletionPostRequest(config, prompt);
+      expect(
+        completionPostRequest.orchestration_config.module_configurations
+          .filtering_module_config
+      ).toBeUndefined();
+    });
+  });
+
+  describe('Azure content filter', () => {
+    it('builds filter config', async () => {
+      const filterConfig = ContentFilters.azure({ Hate: 4, SelfHarm: 0 });
+      const expectedFilterConfig: FilterConfig = {
+        type: 'azure_content_safety',
+        config: {
+          Hate: 4,
+          SelfHarm: 0
+        }
+      };
+      expect(filterConfig).toEqual(expectedFilterConfig);
+    });
+
+    it('builds filter config with no config', async () => {
+      const filterConfig = ContentFilters.azure();
+      const expectedFilterConfig: FilterConfig = {
+        type: 'azure_content_safety'
+      };
+      expect(filterConfig).toEqual(expectedFilterConfig);
+    });
+  });
+});

packages/orchestration/src/orchestration-filtering.ts

@@ -0,0 +1,39 @@
+import type {
+  AzureContentSafety,
+  FilterConfig,
+  InputFilteringConfig,
+  OutputFilteringConfig
+} from './client/api/schema/index.js';
+
+/**
+ * Convenience function to create Azure content filters.
+ * @param filter - Filtering configuration for Azure filter. If skipped, the default Azure content filter configuration is used.
+ * @returns An object with the Azure filtering configuration.
+ * @deprecated Use ContentFilters.azure() instead.
+ */
+export function buildAzureContentFilter(
+  filter?: AzureContentSafety
+): InputFilteringConfig | OutputFilteringConfig {
+  return {
+    filters: [ContentFilters.azure(filter)]
+  };
+}
+
+/**
+ * Convenience function to create Azure content filters.
+ * @param config - Filtering configuration for Azure filter. If skipped, the default Azure content filter configuration is used.
+ * @returns Filter config object.
+ */
+function azure(config?: AzureContentSafety): FilterConfig {
+  return {
+    type: 'azure_content_safety',
+    ...(config && { config })
+  };
+}
+
+/**
+ * Content filters for orchestration.
+ */
+export const ContentFilters = {
+  azure
+};