Add information about event version to conversation components (#2089)

Author: sobolk

.changeset/sixty-cycles-happen.md

@@ -0,0 +1,6 @@
+---
+'@aws-amplify/ai-constructs': minor
+'@aws-amplify/backend-ai': minor
+---
+
+Add information about event version to conversation components

packages/ai-constructs/API.md

@@ -17,7 +17,8 @@ import { ResourceProvider } from '@aws-amplify/plugin-types';
 declare namespace __export__conversation {
     export {
         ConversationHandlerFunction,
-        ConversationHandlerFunctionProps
+        ConversationHandlerFunctionProps,
+        ConversationTurnEventVersion
     }
 }
 export { __export__conversation }
@@ -43,6 +44,8 @@ export { __export__conversation__runtime }
 class ConversationHandlerFunction extends Construct implements ResourceProvider<FunctionResources> {
     constructor(scope: Construct, id: string, props: ConversationHandlerFunctionProps);
     // (undocumented)
+    static readonly eventVersion: ConversationTurnEventVersion;
+    // (undocumented)
     resources: FunctionResources;
 }
 
@@ -114,6 +117,9 @@ type ConversationTurnEvent = {
     };
 };
 
+// @public (undocumented)
+type ConversationTurnEventVersion = `1.${number}`;
+
 // @public
 const createExecutableTool: <TJSONSchema extends JSONSchema = JSONSchema, TToolInput = FromJSONSchema<TJSONSchema>>(name: string, description: string, inputSchema: ToolInputSchema<TJSONSchema>, handler: (input: TToolInput) => Promise<bedrock.ToolResultContentBlock>) => ExecutableTool<TJSONSchema, TToolInput>;
 

packages/ai-constructs/src/conversation/conversation_handler_construct.ts

@@ -40,6 +40,11 @@ export type ConversationHandlerFunctionProps = {
   outputStorageStrategy?: BackendOutputStorageStrategy<AIConversationOutput>;
 };
 
+// Event is a protocol between AppSync and Lambda handler. Therefore, X.Y subset of semver is enough.
+// Typing this as 1.X so that major version changes are caught by compiler if consumer of this construct inspects
+// event version.
+export type ConversationTurnEventVersion = `1.${number}`;
+
 /**
  * Conversation Handler Function CDK construct.
  * This construct deploys resources that integrate conversation routes
@@ -54,6 +59,7 @@ export class ConversationHandlerFunction
   extends Construct
   implements ResourceProvider<FunctionResources>
 {
+  static readonly eventVersion: ConversationTurnEventVersion = '1.0';
   resources: FunctionResources;
 
   /**

packages/ai-constructs/src/conversation/index.ts

@@ -1,6 +1,11 @@
 import {
   ConversationHandlerFunction,
   ConversationHandlerFunctionProps,
+  ConversationTurnEventVersion,
 } from './conversation_handler_construct.js';
 
-export { ConversationHandlerFunction, ConversationHandlerFunctionProps };
+export {
+  ConversationHandlerFunction,
+  ConversationHandlerFunctionProps,
+  ConversationTurnEventVersion,
+};

packages/backend-ai/API.md

@@ -5,12 +5,14 @@
 ```ts
 
 import { ConstructFactory } from '@aws-amplify/plugin-types';
+import { ConversationTurnEventVersion } from '@aws-amplify/ai-constructs/conversation';
 import { FunctionResources } from '@aws-amplify/plugin-types';
 import { ResourceProvider } from '@aws-amplify/plugin-types';
 import * as runtime from '@aws-amplify/ai-constructs/conversation/runtime';
 
 declare namespace __export__conversation {
     export {
+        ConversationHandlerFunctionFactory,
         DefineConversationHandlerFunctionProps,
         defineConversationHandlerFunction
     }
@@ -28,14 +30,19 @@ declare namespace __export__conversation__runtime {
 }
 export { __export__conversation__runtime }
 
+// @public (undocumented)
+type ConversationHandlerFunctionFactory = ConstructFactory<ResourceProvider<FunctionResources>> & {
+    readonly eventVersion: ConversationTurnEventVersion;
+};
+
 // @public (undocumented)
 type ConversationTurnEvent = runtime.ConversationTurnEvent;
 
 // @public (undocumented)
 const createExecutableTool: <TJSONSchema extends runtime.JSONSchema = runtime.JSONSchema, TToolInput = runtime.FromJSONSchema<TJSONSchema>>(name: string, description: string, inputSchema: runtime.ToolInputSchema<TJSONSchema>, handler: (input: TToolInput) => Promise<ToolResultContentBlock>) => ExecutableTool<TJSONSchema, TToolInput>;
 
 // @public
-const defineConversationHandlerFunction: (props: DefineConversationHandlerFunctionProps) => ConstructFactory<ResourceProvider<FunctionResources>>;
+const defineConversationHandlerFunction: (props: DefineConversationHandlerFunctionProps) => ConversationHandlerFunctionFactory;
 
 // @public (undocumented)
 type DefineConversationHandlerFunctionProps = {

packages/backend-ai/src/conversation/factory.test.ts

@@ -15,6 +15,7 @@ import { defaultEntryHandler } from './test-assets/with-default-entry/resource.j
 import { customEntryHandler } from './test-assets/with-custom-entry/resource.js';
 import { Template } from 'aws-cdk-lib/assertions';
 import { defineConversationHandlerFunction } from './factory.js';
+import { ConversationHandlerFunction } from '@aws-amplify/ai-constructs/conversation';
 
 const createStackAndSetContext = (): Stack => {
   const app = new App();
@@ -57,6 +58,14 @@ void describe('ConversationHandlerFactory', () => {
     assert.strictEqual(instance1, instance2);
   });
 
+  void it('has event version corresponding to construct', () => {
+    const factory = defaultEntryHandler;
+    assert.strictEqual(
+      factory.eventVersion,
+      ConversationHandlerFunction.eventVersion
+    );
+  });
+
   void it('resolves default entry when not specified', () => {
     const factory = defaultEntryHandler;
     const lambda = factory.getInstance(getInstanceProps);

packages/backend-ai/src/conversation/factory.ts

@@ -11,6 +11,7 @@ import {
 import {
   ConversationHandlerFunction,
   ConversationHandlerFunctionProps,
+  ConversationTurnEventVersion,
 } from '@aws-amplify/ai-constructs/conversation';
 import path from 'path';
 import { CallerDirectoryExtractor } from '@aws-amplify/platform-core';
@@ -51,9 +52,17 @@ class ConversationHandlerFunctionGenerator
   };
 }
 
-class ConversationHandlerFunctionFactory
-  implements ConstructFactory<ConversationHandlerFunction>
+export type ConversationHandlerFunctionFactory = ConstructFactory<
+  ResourceProvider<FunctionResources>
+> & {
+  readonly eventVersion: ConversationTurnEventVersion;
+};
+
+class DefaultConversationHandlerFunctionFactory
+  implements ConversationHandlerFunctionFactory
 {
+  readonly eventVersion: ConversationTurnEventVersion =
+    ConversationHandlerFunction.eventVersion;
   private generator: ConstructContainerEntryGenerator;
 
   constructor(
@@ -121,6 +130,6 @@ export type DefineConversationHandlerFunctionProps = {
  */
 export const defineConversationHandlerFunction = (
   props: DefineConversationHandlerFunctionProps
-): ConstructFactory<ResourceProvider<FunctionResources>> =>
+): ConversationHandlerFunctionFactory =>
   // eslint-disable-next-line amplify-backend-rules/prefer-amplify-errors
-  new ConversationHandlerFunctionFactory(props, new Error().stack);
+  new DefaultConversationHandlerFunctionFactory(props, new Error().stack);

packages/backend-ai/src/conversation/index.ts

@@ -1,9 +1,11 @@
 import {
+  ConversationHandlerFunctionFactory,
   DefineConversationHandlerFunctionProps,
   defineConversationHandlerFunction,
 } from './factory.js';
 
 export {
+  ConversationHandlerFunctionFactory,
   DefineConversationHandlerFunctionProps,
   defineConversationHandlerFunction,
 };