feat: Add grounding convenience function (#378)

* grounding convenience * review + tests+ changeset * lint * restructure types * fix: Changes from lint * add type test * fix: Changes from lint * docs * fix: Changes from lint * Apply suggestions from code review * review * review * fix: Changes from lint * update type DocumentGroundingServiceFilter * fix: Changes from lint * docs review * fix: Changes from lint * Apply suggestions from code review * adjust sample for grounding * fix: Changes from lint --------- Co-authored-by: cloud-sdk-js <cloud-sdk-js@github.com> Co-authored-by: Zhongpin Wang <zhongpin.wang@sap.com>
SAP · Jan 13, 2025 · a039890 · a039890
1 parent b65e38b
commit a039890
Show file tree

Hide file tree

Showing 9 changed files with 329 additions and 181 deletions.
diff --git a/.changeset/shiny-brooms-punch.md b/.changeset/shiny-brooms-punch.md
@@ -0,0 +1,5 @@
+---
+'@sap-ai-sdk/orchestration': minor
+---
+
+[Improvement] Add `buildDocumentGroundingConfig()` convenience function to create document grounding configuration in the Orchestration client.
diff --git a/packages/orchestration/README.md b/packages/orchestration/README.md
@@ -330,6 +330,7 @@ return response.getContent();
 ### Grounding
 
 Grounding enables integrating external, contextually relevant, domain-specific, or real-time data into AI processes.
+The grounding configuration can be provided as a raw JSON object or by using the `buildDocumentGroundingConfig()` function, which requires only the minimal mandatory values.
 
 ```ts
 const orchestrationClient = new OrchestrationClient({
@@ -346,21 +347,16 @@ const orchestrationClient = new OrchestrationClient({
     ],
     defaults: {}
   },
-  grounding: {
-    type: 'document_grounding_service',
-    config: {
-      filters: [
+  grounding: buildDocumentGroundingConfig(
+    input_params: ['groundingRequest'],
+    output_param: 'groundingOutput',
+    filters: [
         {
           id: 'filter1',
-          data_repositories: ['*'],
-          search_config: {},
-          data_repository_type: 'vector'
+          data_repositories: ['repository-id']
         }
       ],
-      input_params: ['groundingRequest'],
-      output_param: 'groundingOutput'
-    }
-  }
+    )
 });
 
 const response = await orchestrationClient.chatCompletion({

diff --git a/packages/orchestration/src/index.ts b/packages/orchestration/src/index.ts
@@ -42,12 +42,17 @@ export type {
   OrchestrationModuleConfig,
   LlmModuleConfig,
   Prompt,
+  DocumentGroundingServiceConfig,
+  DocumentGroundingServiceFilter,
   LlmModelParams
 } from './orchestration-types.js';
 
 export { OrchestrationClient } from './orchestration-client.js';
 
-export { buildAzureContentFilter } from './orchestration-utils.js';
+export {
+  buildAzureContentFilter,
+  buildDocumentGroundingConfig
+} from './orchestration-utils.js';
 
 export { OrchestrationResponse } from './orchestration-response.js';
 

diff --git a/packages/orchestration/src/orchestration-completion-post-request.test.ts b/packages/orchestration/src/orchestration-completion-post-request.test.ts
@@ -1,6 +1,6 @@
 import { constructCompletionPostRequest } from './orchestration-client.js';
 import { buildAzureContentFilter } from './orchestration-utils.js';
-import type { CompletionPostRequest } from './client/api/schema';
+import type { CompletionPostRequest } from './client/api/schema/index.js';
 import type { OrchestrationModuleConfig } from './orchestration-types.js';
 
 describe('construct completion post request', () => {

diff --git a/packages/orchestration/src/orchestration-types.ts b/packages/orchestration/src/orchestration-types.ts
@@ -1,6 +1,8 @@
 import type { ChatModel } from './model-types.js';
 import type {
   ChatMessages,
+  DataRepositoryType,
+  DocumentGroundingFilter,
   FilteringModuleConfig,
   GroundingModuleConfig,
   MaskingModuleConfig,
@@ -69,3 +71,36 @@ export interface OrchestrationModuleConfig {
    */
   grounding?: GroundingModuleConfig;
 }
+
+/**
+ * Represents a filter configuration for the Document Grounding Service.
+ */
+export type DocumentGroundingServiceFilter = Omit<
+  DocumentGroundingFilter,
+  'data_repository_type'
+> & {
+  /**
+   * Defines the type of data repository.
+   * If not set, the default value is 'vector'.
+   */
+  data_repository_type?: DataRepositoryType;
+};
+
+/**
+ * Represents the configuration for the Document Grounding Service.
+ */
+export interface DocumentGroundingServiceConfig {
+  /**
+   * Defines the filters to apply during the grounding process.
+   */
+  filters?: DocumentGroundingServiceFilter[];
+  /**
+   * Contains the input parameters used for grounding input questions.
+   */
+  input_params: string[];
+  /**
+   * Parameter name used for grounding output.
+   * @example "groundingOutput"
+   */
+  output_param: string;
+}