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 <[email protected]>
Co-authored-by: Zhongpin Wang <[email protected]>

Author: 3 people

.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.

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({

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';
 

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', () => {

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;
+}