feat(generation-transformer): add generation transformer

[atierian]

Description of changes

Amplify GraphQL Generation Transformer

The Amplify GraphQL Generation Transformer is a tool that enables the quick and easy creation of AI-powered Generation routes within your AWS AppSync API. This transformer can be leveraged by using the @generation directive to configure AI models and system prompts for generating content.

Directive Definition

The @generation directive is defined as follows:

directive @generation(
    aiModel: String!,
    systemPrompt: String!,
    inferenceConfiguration: GenerationInferenceConfiguration
) on FIELD_DEFINITION

Features

1. AI Model Integration: Specify the AI model to be used for generation.
2. System Prompt Configuration: Define a system prompt to guide the AI's output.
3. Inference Configuration: Fine-tune generation parameters like max tokens, temperature, and top-p.
4. Integrates with @auth Directive: Supports existing auth modes like IAM, API key, and Amazon Cognito User Pools.
5. Resolver Creation: Generates resolvers with tool definitions based on the Query field's return type to interact with the specified AI model.
6. Bedrock HTTP Data Source Creation: Creates a AppSync HTTP Data Source for Bedrock to interact with the specified AI model.

Examples

Basic Usage

Scalar Type Generation

type Query {
  generateStory(topic: String!): String @generation(
    aiModel: "anthropic.claude-3-haiku-20240307-v1:0",
    systemPrompt: "You are a creative storyteller. Generate a short story based on the given topic."
  )
}

Complex Type Generation

type Recipe {
  name: String!
  ingredients: [String!]!
  instructions: [String!]!
  prepTime: Int!
  cookTime: Int!
  servings: Int!
  difficulty: String!
}

type Query {
  generateRecipe(cuisine: String!, dietaryRestrictions: [String]): Recipe
  @generation(
    aiModel: "anthropic.claude-3-haiku-20240307-v1:0",
    systemPrompt: "You are a professional chef specializing in creating recipes. Generate a detailed recipe based on the given cuisine and dietary restrictions."
  )
}

Advanced Configuration

type Query {
  generateCode(description: String!): String @generation(
    aiModel: "anthropic.claude-3-haiku-20240307-v1:0",
    systemPrompt: "You are an expert programmer. Generate code based on the given description.",
    inferenceConfiguration: {
      maxTokens: 500,
      temperature: 0.7,
      topP: 0.9
    }
  )
}

Limitations

• The @generation directive can only be used on Query fields.
• The AI model specified must:
  • be supported by Amazon Bedrock's /converse API
  • support tool usage
• Only the following GraphQL / AppSync scalar types are supported as required properties
  • Boolean
  • Int
  • Float
  • String
  • ID
  • AWSJSON

CDK / CloudFormation Parameters Changed

N/A

Issue #, if available

N/A

Description of how you validated changes

• Snapshot tests
• E2E tests
• Manual testing

Checklist

• PR description included
• yarn test passes
• Tests are changed or added
• Relevant documentation is changed or added (and PR referenced) Docs PRs are WIP
• New AWS SDK calls or CloudFormation actions have been added to relevant test and service IAM policies
• Any CDK or CloudFormation parameter changes are called out explicitly

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[atierian]

We're asserting that we get an answer here, not the correct answer because LLMs are not good (being generous) at math.

[atierian]

The test is currently disabled because we throw in the transformer when the return type contains required fields typed as certain AppSync scalars.

We're exploring options, including prompt improvements, better regex pattern in JSON Schema tool definitions, and special case handling for models (omitting createdAt, updatedAt, and id in tool definition, and populating them in the resolver).

For now, this is an accepted current limitation.

[atierian]

This allows existing VTL @auth generated resolver functions to be inserted into the pipeline resolver.

[atierian]

Probably should eventually be a constant defined in amplify-graphql-transformer-core, but it's only being used here for now. Will add one in a follow up if / when it becomes necessary.

[atierian]

Planned followup to improve the error message.

[atierian]

----- MARK REVIEW -----

[phani-srikar]

why do we need to store the directive definition when the actual directive arguments are already listed out separately below?

[atierian]

Good point, we don't! I'll remove this in a follow up. Thanks!

[phani-srikar]

I think Tim has a good point here and might be worth discussing the trade offs with team before we release. I couldn't find any AppSync imposed limit on number of datasources, but feel like re-use will save us from trouble in the future.

[phani-srikar]

Do you use this type elsewhere?

[atierian]

We don't, and your comment made me realize that we only actually need to export ToolConfig. The extra exports and Tools type definition are relics from previous structure. Will remove in a follow up. Thanks for the callout!

[phani-srikar]

We give so much information and it still returns a response with wrong format? :)

[atierian]

Yea 😞
We haven't found a generic solution yet, but we've seen some promising results with various techniques, and are cautiously optimistic that we can get there.