feat(guardrails): add Contextual grounding (#660)

* feat(guardrails): add contextual grounding

Author: krokoko

.projen/deps.json

@@ -30,7 +30,7 @@ import {
 const GITHUB_USER = 'awslabs';
 const PUBLICATION_NAMESPACE = 'cdklabs';
 const PROJECT_NAME = 'generative-ai-cdk-constructs';
-const CDK_VERSION: string = '2.149.0';
+const CDK_VERSION: string = '2.154.1';
 
 function camelCaseIt(input: string): string {
   // Hypens and dashes to spaces and then CamelCase...

.projenrc.ts

@@ -1,3 +1,7 @@
+# CDK Generative AI Constructs V0.1.258 (2024-08-26)
+
+Based on CDK library version 2.154.1
+
 # CDK Generative AI Constructs V0.1.213 (2024-07-18)
 
 Based on CDK library version 2.149.0

CHANGELOG.md

@@ -16,7 +16,7 @@ Default output format [None]: json
 ```
 
 - [Node](https://nodejs.org/en) >= v20.9.0
-- [AWS CDK](https://github.com/aws/aws-cdk/releases/tag/v2.141.0) >= 2.141.0
+- [AWS CDK](https://github.com/aws/aws-cdk/releases/tag/v2.154.1) >= 2.154.1
 - [Python](https://www.python.org/downloads/) >=3.9
 - [Projen](https://github.com/projen/projen) >= 0.78.8
 - [Yarn](https://classic.yarnpkg.com/lang/en/docs/cli/install/) >= 1.22.19

DEVELOPER_GUIDE.md

@@ -565,6 +565,25 @@ stable
 
 ***
 
+### recursiveLoop?
+
+> `readonly` `optional` **recursiveLoop**: `RecursiveLoop`
+
+Sets the Recursive Loop Protection for Lambda Function.
+It lets Lambda detect and terminate unintended recusrive loops.
+
+#### Default
+
+```ts
+RecursiveLoop.Terminate
+```
+
+#### Stability
+
+stable
+
+***
+
 ### reservedConcurrentExecutions?
 
 > `readonly` `optional` **reservedConcurrentExecutions**: `number`

apidocs/interfaces/DockerLambdaCustomProps.md

@@ -12,6 +12,7 @@
 
 - [CanadaSpecific](enumerations/CanadaSpecific.md)
 - [ChunkingStrategy](enumerations/ChunkingStrategy.md)
+- [ContextualGroundingFilterConfigType](enumerations/ContextualGroundingFilterConfigType.md)
 - [FiltersConfigStrength](enumerations/FiltersConfigStrength.md)
 - [FiltersConfigType](enumerations/FiltersConfigType.md)
 - [Finance](enumerations/Finance.md)
@@ -52,6 +53,7 @@
 - [ApiSchemaConfig](interfaces/ApiSchemaConfig.md)
 - [BedrockFoundationModelProps](interfaces/BedrockFoundationModelProps.md)
 - [ContentPolicyConfigProps](interfaces/ContentPolicyConfigProps.md)
+- [ContextualGroundingPolicyConfigProps](interfaces/ContextualGroundingPolicyConfigProps.md)
 - [GuardrailConfiguration](interfaces/GuardrailConfiguration.md)
 - [GuardrailProps](interfaces/GuardrailProps.md)
 - [InferenceConfiguration](interfaces/InferenceConfiguration.md)

apidocs/namespaces/bedrock/README.md

@@ -106,6 +106,20 @@ The tree node.
 
 ## Methods
 
+### addContextualGroundingPolicyConfig()
+
+> **addContextualGroundingPolicyConfig**(`props`): `void`
+
+#### Parameters
+
+• **props**: [`ContextualGroundingPolicyConfigProps`](../interfaces/ContextualGroundingPolicyConfigProps.md)[]
+
+#### Returns
+
+`void`
+
+***
+
 ### addSensitiveInformationPolicyConfig()
 
 > **addSensitiveInformationPolicyConfig**(`props`, `guardrailRegexesConfig`): `void`

apidocs/namespaces/bedrock/classes/Guardrail.md

@@ -0,0 +1,27 @@
+[**@cdklabs/generative-ai-cdk-constructs**](../../../README.md) • **Docs**
+
+***
+
+[@cdklabs/generative-ai-cdk-constructs](../../../README.md) / [bedrock](../README.md) / ContextualGroundingFilterConfigType
+
+# Enumeration: ContextualGroundingFilterConfigType
+
+## Enumeration Members
+
+### GROUNDING
+
+> **GROUNDING**: `"GROUNDING"`
+
+Grounding score represents the confidence that the model response is factually correct and grounded in the source.
+If the model response has a lower score than the defined threshold, the response will be blocked and the configured
+blocked message will be returned to the user. A higher threshold level blocks more responses.
+
+***
+
+### RELEVANCE
+
+> **RELEVANCE**: `"RELEVANCE"`
+
+Relevance score represents the confidence that the model response is relevant to the user's query.
+If the model response has a lower score than the defined threshold, the response will be blocked and
+the configured blocked message will be returned to the user. A higher threshold level blocks more responses

apidocs/namespaces/bedrock/enumerations/ContextualGroundingFilterConfigType.md

@@ -0,0 +1,28 @@
+[**@cdklabs/generative-ai-cdk-constructs**](../../../README.md) • **Docs**
+
+***
+
+[@cdklabs/generative-ai-cdk-constructs](../../../README.md) / [bedrock](../README.md) / ContextualGroundingPolicyConfigProps
+
+# Interface: ContextualGroundingPolicyConfigProps
+
+## Properties
+
+### filtersConfigType
+
+> `readonly` **filtersConfigType**: [`ContextualGroundingFilterConfigType`](../enumerations/ContextualGroundingFilterConfigType.md)
+
+The filter details for the guardrails contextual grounding filter.
+GROUNDING: Validate if the model responses are grounded and factually correct based on the information provided in the reference source,
+and block responses that are below the defined threshold of grounding.
+RELEVANCE: Validate if the model responses are relevant to the user's query and block responses
+that are below the defined threshold of relevance.
+
+***
+
+### threshold
+
+> `readonly` **threshold**: `number`
+
+The threshold details for the guardrails contextual grounding filter.
+0 blocks nothing, 0.99 blocks almost everything

apidocs/namespaces/bedrock/interfaces/ContextualGroundingPolicyConfigProps.md

@@ -26,6 +26,14 @@ The message to return when the guardrail blocks a model response.
 
 ***
 
+### contextualGroundingfiltersConfig?
+
+> `readonly` `optional` **contextualGroundingfiltersConfig**: [`ContextualGroundingPolicyConfigProps`](ContextualGroundingPolicyConfigProps.md)[]
+
+Contextual grounding policy config for a guardrail.
+
+***
+
 ### description?
 
 > `readonly` `optional` **description**: `string`

apidocs/namespaces/bedrock/interfaces/GuardrailProps.md

@@ -597,6 +597,19 @@ const guardrails = new bedrock.Guardrail(this,'bedrockGuardrails',{
         action: "BLOCK", 
     });
 
+    // Optional - Add contextual grounding
+
+    guardrails.addContextualGroundingPolicyConfig([
+      {
+        threshold: 0.5,
+        filtersConfigType: bedrock.ContextualGroundingFilterConfigType.GROUNDING,
+      },
+      {
+        threshold: 0.9,
+        filtersConfigType: bedrock.ContextualGroundingFilterConfigType.RELEVANCE,
+      },
+    ]);
+
     // Optional - Add Denied topics . You can use default Topic or create your custom Topic with createTopic function. The default Topics can also be overwritten.
 
     const topic = new Topic(this,'topic');
@@ -641,6 +654,21 @@ Python
         action= "BLOCK"
     )
 
+    # Optional - Add contextual grounding
+
+    guardrails.add_contextual_grounding_policy_config(
+      props= [ 
+        bedrock.ContextualGroundingPolicyConfigProps(
+            threshold= 0.5,
+            filters_config_type= bedrock.ContextualGroundingFilterConfigType.GROUNDING
+        ),
+        bedrock.ContextualGroundingPolicyConfigProps(
+            threshold= 0.5,
+            filters_config_type= bedrock.ContextualGroundingFilterConfigType.RELEVANCE
+        ),
+      ],
+    )
+
     #Optional - Add Denied topics . You can use default Topic or create your custom Topic with createTopic function. The default Topics can also be overwritten.
 
     topic = bedrock.Topic(self,'topic')

package.json

@@ -31,12 +31,37 @@ export enum FiltersConfigStrength {
   HIGH = 'HIGH',
 }
 
+export enum ContextualGroundingFilterConfigType {
+  /**Grounding score represents the confidence that the model response is factually correct and grounded in the source.
+   * If the model response has a lower score than the defined threshold, the response will be blocked and the configured
+   * blocked message will be returned to the user. A higher threshold level blocks more responses. */
+  GROUNDING = 'GROUNDING',
+  /**Relevance score represents the confidence that the model response is relevant to the user's query.
+   * If the model response has a lower score than the defined threshold, the response will be blocked and
+   * the configured blocked message will be returned to the user. A higher threshold level blocks more responses */
+  RELEVANCE = 'RELEVANCE'
+}
+
 export interface ContentPolicyConfigProps{
   readonly filtersConfigType: FiltersConfigType;
   readonly inputStrength?: FiltersConfigStrength;
   readonly outputStrength?: FiltersConfigStrength;
 }
 
+export interface ContextualGroundingPolicyConfigProps {
+  /**The filter details for the guardrails contextual grounding filter.
+   * GROUNDING: Validate if the model responses are grounded and factually correct based on the information provided in the reference source,
+   * and block responses that are below the defined threshold of grounding.
+   * RELEVANCE: Validate if the model responses are relevant to the user's query and block responses
+   * that are below the defined threshold of relevance.
+  */
+  readonly filtersConfigType: ContextualGroundingFilterConfigType;
+  /** The threshold details for the guardrails contextual grounding filter.
+   * 0 blocks nothing, 0.99 blocks almost everything
+  */
+  readonly threshold: number;
+}
+
 export class ContentPolicyConfig extends Construct {
   readonly contentPolicyConfigList: bedrock.CfnGuardrail.ContentFilterConfigProperty[];
 

src/cdk-lib/bedrock/README.md

@@ -17,7 +17,7 @@ import { CfnTag, aws_bedrock as bedrock } from 'aws-cdk-lib';
 import * as kms from 'aws-cdk-lib/aws-kms';
 import { Construct } from 'constructs';
 
-import { ContentPolicyConfig, ContentPolicyConfigProps } from './content-policy';
+import { ContentPolicyConfig, ContentPolicyConfigProps, ContextualGroundingPolicyConfigProps } from './content-policy';
 import { GuardrailVersion } from './guardrail-version';
 import { SensitiveInformationPolicyConfig, SensitiveInformationPolicyConfigProps } from './pii-list';
 import { Topic } from './topic-list';
@@ -46,6 +46,11 @@ export interface GuardrailProps {
     */
   readonly filtersConfig?: ContentPolicyConfigProps[];
 
+  /**
+    * Contextual grounding policy config for a guardrail.
+    */
+  readonly contextualGroundingfiltersConfig?: ContextualGroundingPolicyConfigProps[];
+
   /**
     * PII fields which needs to be masked.
     */
@@ -132,6 +137,16 @@ export class Guardrail extends Construct {
       },
     });
 
+    if (props.contextualGroundingfiltersConfig) {
+      this.guardrailInstance.contextualGroundingPolicyConfig={
+        filtersConfig:
+          props.contextualGroundingfiltersConfig.map((prop) => ({
+            type: prop.filtersConfigType,
+            threshold: prop.threshold,
+          })),
+      };
+    }
+
     this.guardrailVersion = this.guardrailInstance.attrVersion;
     this.guardrailId = this.guardrailInstance.attrGuardrailId;
 
@@ -153,6 +168,20 @@ export class Guardrail extends Construct {
     }
   }
 
+  public addContextualGroundingPolicyConfig( props: ContextualGroundingPolicyConfigProps[]) {
+    if (props) {
+      this.guardrailInstance.contextualGroundingPolicyConfig={
+        filtersConfig:
+          props.map((prop) => ({
+            type: prop.filtersConfigType,
+            threshold: prop.threshold,
+          })),
+      };
+    } else {
+      throw new Error('No ContextualGroundingPolicyConfig is set in GuardrailProps.');
+    }
+  }
+
 
   public async uploadWordPolicyFromFile(filePath: string) {
     try {

src/cdk-lib/bedrock/content-policy.ts

@@ -14,7 +14,7 @@
 import { expect as cdkExpect, haveResource } from '@aws-cdk/assert';
 import * as cdk from 'aws-cdk-lib';
 import { AwsSolutionsChecks } from 'cdk-nag';
-import { FiltersConfigStrength, FiltersConfigType } from '../../../src/cdk-lib/bedrock/content-policy';
+import { FiltersConfigStrength, FiltersConfigType, ContextualGroundingFilterConfigType } from '../../../src/cdk-lib/bedrock/content-policy';
 import { Guardrail, GuardrailProps } from '../../../src/cdk-lib/bedrock/guardrails';
 import { General, PiiEntitiesConfigAction } from '../../../src/cdk-lib/bedrock/pii-list';
 import { Topic } from '../../../src/cdk-lib/bedrock/topic-list';
@@ -73,6 +73,17 @@ describe('Guardrail', () => {
       action: 'BLOCK',
     });
 
+    guardrail.addContextualGroundingPolicyConfig([
+      {
+        threshold: 0.5,
+        filtersConfigType: ContextualGroundingFilterConfigType.GROUNDING,
+      },
+      {
+        threshold: 0.9,
+        filtersConfigType: ContextualGroundingFilterConfigType.RELEVANCE,
+      },
+    ]);
+
     const topic = new Topic(stack, 'my-topic');
     topic.financialAdviceTopic();
 
@@ -117,6 +128,18 @@ describe('Guardrail', () => {
             },
           ],
         },
+        ContextualGroundingPolicyConfig: {
+          FiltersConfig: [
+            {
+              Threshold: 0.5,
+              Type: 'GROUNDING',
+            },
+            {
+              Threshold: 0.9,
+              Type: 'RELEVANCE',
+            },
+          ],
+        },
         TopicPolicyConfig: {
           TopicsConfig: [
             {