aws-lex-conversation 6.1.0 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bbaa290608e0035207d3fbf6b53c862f36c95e0a07012a562e18ff21c6b3f3f
-  data.tar.gz: a79cff690a0d2419de8f859688f43881cf9d67e40756972afde597196ba7ac64
+  metadata.gz: 61c4edf66e617becb5f2c7aa3611e32c7eeef58ab2cb9533f1816abcaf675ab8
+  data.tar.gz: 485e85d4c07d25527752e2451e99c02af1eae808dfd9e048efa147a8042d76aa
 SHA512:
-  metadata.gz: 22e3b48931497c44e65d71834379ccd37e9f5c08ffc8713b4bfd7dfefdbc2e02f4d46aea8cd7e2a180b5537a80c9dbeee53eb3817f82755b37d4b1698d730a58
-  data.tar.gz: 71a0fe45f60e828b51cefd0ab52901ca06691377428eb19ff0c82623cfa85a603454b318f483fed138694889a3dd77dbf15b4c9a525f8338a8c379bf26345074
+  metadata.gz: 03f8814a82e0f6cea94033ef13d4f59ade4bb74a1cee26fe554151bff1b0785f32f0c3aef17e2a2293a1c71dd4442679ee516a9d16bd1bc94069e0e00dccfb3f
+  data.tar.gz: 360cb550a21e90e6063722c676071ed59d083e6a03eb44281f2517b79b8e2a70ccfeb435ad0df4b37b1c46a8e6e9e4258505622b6396f3168a140eb9e2998524

data/.rubocop.yml

@@ -45,6 +45,8 @@ Style/Lambda:
   EnforcedStyle: literal
 Style/GuardClause:
   Enabled: false
+Style/OpenStructUse:
+  Enabled: false
 Style/RedundantFetchBlock:
   Enabled: false
 Style/SlicingWithRange:

data/CHANGELOG.md

@@ -1,11 +1,45 @@
+# 6.4.0 - Feb 10, 2022
+
+* Add support for the new protocol properties of `proposedNextState` and `transcriptions`. This enables support for [transcription confidence scores](https://docs.aws.amazon.com/lexv2/latest/dg/using-transcript-confidence-scores.html).
+* Expose the following methods on `Aws::Lex::Conversation` instances:
+  - `proposed_next_state?`: Returns `true` if a `proposedNextState` value is present or `false` otherwise.
+  - `proposed_next_state`: Returns an `Aws::Lex::Conversation::Type::ProposedNextState` instance. May return `nil`.
+  - `transcriptions`: Returns an array of `Aws::Lex::Conversation::Type::Transcription` instances. Defaults to a empty array if the `transcriptions` property is not present.
+* Make the `content_type` attribute in the constructor for `Aws::Lex::Conversation::Type::Message` default to `PlainText` when not present.
+
+# 6.3.0 - Nov 22, 2021
+
+* Add support for the recently added `slotElicitationStyle` property when generating an `ElicitSlot` repsonse ([documentation](https://docs.aws.amazon.com/lexv2/latest/dg/using-spelling.html)).
+
+You can generate an `ElicitSlot` response now with an optional `slot_elicitation_style` property to allow for spelling support:
+
+```ruby
+conversation.elicit_slot(
+  slot_to_elicit: 'LastName',
+  slot_elicitation_style: 'SpellByWord' # one of Default, SpellByLetter, or SpellByWord
+)
+```
+
+# 6.2.0 - Sept 28, 2021
+
+* Add a `Aws::Lex::Conversation#restore_from!` method that accepts a checkpoint parameter. This method modifies the underlying conversation state to match the data from the saved checkpoint.
+* Make the `dialog_action_type` parameter on `Aws::Lex::Conversation#checkpoint!` default to `Delegate` if not specified as a developer convenience.
+* Allow developers to pass an optional `intent` override parameter on `Aws::Lex::Conversation#checkpoint!` for convenience.
+* Update the README with advanced examples for the conversation stash and checkpoints.
+
+# 6.1.1 - Sept 22, 2021
+
+* renamed `maximum_elicitations` to `max_retries` and made it backwards compatible to make the param name clear, by default this value is zero, allowing each slot to elicit only once
+
 # 6.1.0 - Sept 7, 2021
+
 Added helper methods for clearing active contexts
+
 ```ruby
 conversation.clear_context!(name: 'test') # clears this specific active context
 conversation.clear_all_contexts! # clears all current active contexts
 ```
 
-
 # 6.0.0 - Sept 7, 2021
 
 * **breaking change** - Modify `Aws::Lex::Conversation::Type::Base#computed_property` to accept a block instead of a callable argument. This is an internal class and should not require any application-level changes.
@@ -63,6 +97,7 @@ it 'creates an event' do
   expect(event).to include_session_values(username: 'jane.doe')
 end
 ```
+
 * Add a few convenience methods to `Aws::Lex::Conversation` instances for dealing with active contexts:
   - `#active_context(name:)`:
 

data/README.md

@@ -1,19 +1,15 @@
-# Aws::Lex::Conversation
+# `Aws::Lex::Conversation`
 
-Have you played around with [AWS Lex](https://aws.amazon.com/lex/) and quickly realized you were duplicating code to read and generate the [Lex Lambda input event and response format](https://docs.aws.amazon.com/lex/latest/dg/lambda-input-response-format.html)?
+Building a chatbot with [AWS Lex](https://aws.amazon.com/lex/) is really fun! Unfortunately implementing your bot's behaviour with the [Lex/Lambda event protocol](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html) is less fun.
 
-`Aws::Lex::Conversation` provides a mechanism to define the flow of a Lex conversation with a user easily!
+But don't worry - we've done the hard work for you!
 
-## Installation
-
-### Lex V1
-
-Version 3.x is the last major version of this gem that will support Lex V1.
+`Aws::Lex::Conversation` makes it simple to build dynamic, conversational chatbots with AWS Lex and AWS Lambda!
 
-Add this line to your application's Gemfile:
+## Installation
 
 ```ruby
-gem 'aws-lex-conversation', '~> 3.0'
+gem 'aws-lex-conversation'
 ```
 
 And then execute:
@@ -22,96 +18,162 @@ And then execute:
 bundle install
 ```
 
-### Lex V2
+**Please Note:** This library currently supports [AWS Lex Version 2](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html). If you're looking for Lex V1 support, lock `aws-lex-conversation` to `~> 3.0` in your `Gemfile`.
+
+## Core Concepts
+
+### The Conversation Instance
 
-Version 4.x and higher support Lex V2.
+Instances of `Aws::Lex::Conversation` wrap the Lex input/output event format and make it easy to manage conversation dialog.
 
-Add this line to your application's Gemfile:
+Imagine you have a `ButlerBot` configured with a `ServeBreakfast` intent and `BreakfastFood` slot.
+
+The backing lambda handler for your bot might look something like:
 
 ```ruby
-gem 'aws-lex-conversation', '>= 4.0'
+require "aws-lex-conversation"
+
+def lambda_handler(event:, context:)
+  # The conversation instance validates and wraps the Lex input event
+  conversation = Aws::Lex::Conversation.new(event: event, context: context)
+
+  # Return a Close dialog action to our Lex bot and end the conversation
+  conversation.close(
+    fulfillment_state: "Fulfilled",
+    messages: [
+      # We can construct response messages using wrapper classes.
+      Aws::Lex::Conversation::Type::Message.new(
+        content: "Hi - I'm a 🤖!"
+      ),
+      # Or we can pass a Hash that directly maps to the Lex response format
+      {
+        content: "Your intent is: #{conversation.intent_name}",
+        contentType: "PlainText"
+      },
+      {
+        content: "Here's your #{conversation.slots[:BreakfastFood].value}!",
+        contentType: "PlainText"
+      }
+    ]
+  )
+end
 ```
 
-And then execute:
+This lambda handler would generate the following dialog:
 
-```bash
-bundle install
+![ButlerBot Dialog](https://raw.github.com/amaabca/aws-lex-conversation/master/data/butler_bot.png)
+
+All data from the Lex input event is exposed via the `lex` attribute. By convention, the `lex` attribute directly translates input event attributes from `camelCase` to `snake_case`.
+
+We also provide some helpers to help manage the conversation. For example:
+
+```ruby
+# returns true if the lambda function was invoked as a DialogCodeHook
+conversation.lex.invocation_source.dialog_code_hook?
+
+# returns true if the InputMode is Speech
+conversation.lex.input_mode.speech?
+
+# you can easily set or retrieve a session values
+conversation.session[:name] = "Jane"
+conversation.session[:name] # => "Jane"
+
+# dealing with slot data is simple
+conversation.slots[:BreakfastFood].filled? # returns true if a slot value is present
+conversation.slots[:Hometown].blank?       # returns true if a slot value is nil/empty
+conversation.slots[:FirstName].value       # => "John"
 ```
 
-## Usage
+### The Handler Chain
+
+Conversational dialog gets complex quickly! Conversation instances include a handler chain that can help manage this complexity.
 
-At a high level, you must create a new instance of `Aws::Lex::Conversation`.
+Each handler in the chain defines the prerequisites necessary for the handler to generate a response.
 
-Generally the conversation instance will be initialized inside your Lambda handler method as follows:
+You can configure the handler chain as follows:
 
 ```ruby
-def my_lambda_handler(event:, context:)
+def lambda_handler(event:, context:)
   conversation = Aws::Lex::Conversation.new(event: event, context: context)
 
-  # define a chain of your own Handler classes
   conversation.handlers = [
+    # You need to define custom handler classes yourself
+    { handler: ServeBreakfast },
+    { handler: FallbackIntent },
+    # We offer a few "built in" handlers
     {
       handler: Aws::Lex::Conversation::Handler::Delegate,
       options: {
-        respond_on: ->(conversation) { conversation.current_intent.name == 'MyIntent' }
+        # If we get this far, always return a Delegate action
+        respond_on: ->(_) { true }
       }
     }
   ]
 
-  # return a response object to indicate Lex's next action
+  # The respond method will execute each handler sequentially and return a Lex response
   conversation.respond
 end
 ```
 
-Any custom behaviour in your flow is achieved by defining a Handler class. Handler classes must provide the following:
+### Writing Your Own Handler
+
+Generally, custom behaviour in your flow is achieved by defining your own handler class. Handler classes must:
 
 1. Inherit from `Aws::Lex::Conversation::Handler::Base`.
 2. Define a `will_respond?(conversation)` method that returns a boolean value.
 3. Define a `response(conversation)` method to return final response to Lex. This method is called if `will_respond?` returns `true`.
 
-The handlers defined on an `Aws::Lex::Conversation` instance will be called one-by-one in the order defined.
+Handlers in the chain are invoked sequentially in the order defined.
 
-The first handler that returns `true` for the `will_respond?` method will provide the final Lex response action.
+The first handler in the chain that returns `true` for the `will_respond?` method will provide the final Lex response action.
 
-### Custom Handler Example
+Here's an example for the `ServeBreakfast` and `FallbackIntent` handlers above:
 
 ```ruby
-class SayHello < Aws::Lex::Conversation::Handler::Base
+class ServeBreakfast < Aws::Lex::Conversation::Handler::Base
   def will_respond?(conversation)
-    conversation.lex.invocation_source.dialog_code_hook? && # callback is for DialogCodeHook (i.e. validation)
-    conversation.lex.current_intent.name == 'SayHello' &&   # Lex has routed to the 'SayHello' intent
-    conversation.slots[:name].filled?                       # our expected slot value is set
+    conversation.intent_name == "ServeBreakfast" &&   
+    conversation.slots[:BreakfastFood].filled?                      
   end
 
   def response(conversation)
-    name = conversation.slots[:name].value
-
-    # NOTE: you can use the Type::* classes if you wish. The final output
-    # will be normalized to a value that complies with the Lex response format.
-    #
-    # You can also specify raw values for the response:
-    #
-    # conversation.close(
-    #   fulfillment_state: 'Fulfilled',
-    #   messages: [{ content: "Hello, #{name}!", contentType: 'PlainText' }]
-    # )
-    #
+    food = conversation.slots[:BreakfastFood].value
+    emoji = food == "waffle" ? "🧇" : "🥓"
+
     conversation.close(
-      fulfillment_state: Aws::Lex::Conversation::Type::FulfillmentState.new('Fulfilled'),
+      fulfillment_state: "Fulfilled",
       messages: [
-        Aws::Lex::Conversation::Type::Message.new(
-          content: "Hello, #{name}!",
-          content_type: Aws::Lex::Conversation::Type::Message::ContentType.new('PlainText')
-        )
+        {
+          content: "Here's your #{emoji}!",
+          contentType: "PlainText"
+        }
+      ]
+    )
+  end
+end
+
+class FallbackIntent < Aws::Lex::Conversation::Handler::Base
+  def will_respond?(conversation)
+    conversation.intent_name == "FallbackIntent"
+  end
+
+  def response(conversation)
+    conversation.close(
+      fulfillment_state: 'Failed',
+      messages: [
+        {
+          content: "Sorry - I'm not sure what you said!",
+          contentType: "PlainText"
+        }
       ]
     )
   end
 end
 ```
 
-## Built-In Handlers
+### Built-In Handlers
 
-### `Aws::Lex::Conversation::Handler::Echo`
+#### `Aws::Lex::Conversation::Handler::Echo`
 
 This handler simply returns a close response with a message that matches the `inputTranscript` property of the input event.
 
@@ -140,7 +202,7 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Close' } ... }
 ```
 
-### `Aws::Lex::Conversation::Handler::Delegate`
+#### `Aws::Lex::Conversation::Handler::Delegate`
 
 This handler returns a `Delegate` response to the Lex bot (i.e. "do the next bot action").
 
@@ -163,7 +225,7 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Delegate' } }
 ```
 
-### `Aws::Lex::Conversation::Handler::SlotResolution`
+#### `Aws::Lex::Conversation::Handler::SlotResolution`
 
 This handler will set all slot values equal to their top resolution in the input event. The handler then calls the next handler in the chain for a response.
 
@@ -191,6 +253,114 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Delegate' } }
 ```
 
+## Advanced Concepts
+
+This library provides a few constructs to help manage complex interactions:
+
+### Data Stash
+
+`Aws::Lex::Conversation` instances implement a `stash` method that can be used to store temporary data within a single invocation.
+
+A conversation's stashed data will not be persisted between multiple invocations of your lambda function.
+
+The conversation stash is a great spot to store deserialized data from the session, or invocation-specific state that needs to be shared between handler classes.
+
+This example illustrates how the stash can be used to store deserialized data from the session:
+
+```ruby
+# given we have JSON-serialized data in as a persisted session value
+conversation.session[:user_data] = '{"name":"Jane","id":1234,"email":"test@example.com"}'
+# we can deserialize the data into a Hash that we store in the conversation stash
+conversation.stash[:user] = JSON.parse(conversation.session[:user_data])
+# later on we can reference our stashed data (within the same invocation)
+conversation.stash[:user] # => {"name"=>"Jane", "id"=>1234, "email"=>"test@example.com"}
+```
+
+### Checkpoints
+
+A conversation may transition between many different topics as the interaction progresses. This type of state transition can be easily handled with checkpoints.
+
+When a checkpoint is created, all intent and slot data is encoded and stored into a `checkpoints` session value. This data persists between invocations, and is not removed until the checkpoint is restored.
+
+You can create a checkpoint as follows:
+
+```ruby
+# we're ready to fulfill the OrderFlowers intent, but we want to elicit another intent first
+conversation.checkpoint!(
+  label: 'order_flowers',
+  dialog_action_type: 'Close' # defaults to 'Delegate' if not specified
+)
+conversation.elicit_intent(
+  messages: [
+    {
+      content: 'Thanks! Before I place your order, is there anything else I can help with?',
+      contentType: 'PlainText'
+    }
+  ]
+)
+```
+
+You can restore the checkpoint in one of two ways:
+
+```ruby
+# in a future invocation, we can fetch an instance of the checkpoint and easily
+# restore the conversation to the previous state
+checkpoint = conversation.checkpoint(label: 'order_flowers')
+checkpoint.restore!(
+  fulfillment_state: 'Fulfilled',
+  messages: [
+    {
+      content: 'Okay, your flowers have been ordered! Thanks!',
+      contentType: 'PlainText'
+    }
+  ]
+) # => our response object to Lex is returned
+```
+
+It's also possible to restore state from a checkpoint and utilize the conversation's handler chain:
+
+```ruby
+class AnotherIntent < Aws::Lex::Conversation::Handler::Base
+  def will_respond?(conversation)
+    conversation.intent_name == 'AnotherIntent' &&
+    conversation.checkpoint?(label: 'order_flowers')
+  end
+
+  def response(conversation)
+    checkpoint = conversation.checkpoint(label: 'order_flowers')
+    # replace the conversation's current resolved intent/slot data with the saved checkpoint data
+    conversation.restore_from!(checkpoint)
+    # call the next handler in the chain to produce a response
+    successor.handle(conversation)
+  end
+end
+
+class OrderFlowers < Aws::Lex::Conversation::Handler::Base
+  def will_respond?(conversation)
+    conversation.intent_name == 'OrderFlowers'
+  end
+
+  def response(conversation)
+    conversation.close(
+      fulfillment_state: 'Fulfilled',
+      messages: [
+        {
+          content: 'Okay, your flowers have been ordered! Thanks!',
+          contentType: 'PlainText'
+        }
+      ]
+    )
+  end
+end
+
+conversation = Aws::Lex::Conversation.new(event: event, context: context)
+conversation.handlers = [
+  { handler: AnotherIntent },
+  { handler: OrderFlowers }
+]
+conversation.respond # => returns a Lex response object
+```
+
 ## Test Helpers
 
 This library provides convenience methods to make testing easy! You can use the test helpers as follows:
@@ -251,8 +421,6 @@ end
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/amaabca/aws-lex-conversation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/amaabca/aws-lex-conversation/blob/master/CODE_OF_CONDUCT.md).
@@ -263,4 +431,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Aws::Lex::Conversation project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/amaabca/aws-lex-conversation/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `Aws::Lex::Conversation` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/amaabca/aws-lex-conversation/blob/master/CODE_OF_CONDUCT.md).

data/aws-lex-conversation.gemspec

@@ -26,9 +26,10 @@ Gem::Specification.new do |spec|
   spec.license = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
   spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|data)/}) }
   end
 
   spec.bindir = 'exe'

data/lib/aws/lex/conversation/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'base64'
+require 'forwardable'
 require 'json'
 require 'shrink/wrap'
 
@@ -25,6 +26,7 @@ require_relative 'type/sentiment_score'
 require_relative 'type/sentiment_response'
 require_relative 'type/invocation_source'
 require_relative 'type/dialog_action_type'
+require_relative 'type/slot_elicitation_style'
 require_relative 'type/dialog_action'
 require_relative 'type/confirmation_state'
 require_relative 'type/fulfillment_state'
@@ -35,11 +37,14 @@ require_relative 'type/slot_value'
 require_relative 'type/slot'
 require_relative 'type/context'
 require_relative 'type/intent'
+require_relative 'type/proposed_next_state'
 require_relative 'type/checkpoint'
 require_relative 'type/session_attributes'
 require_relative 'type/session_state'
 require_relative 'type/interpretation'
 require_relative 'type/bot'
+require_relative 'type/transcription/resolved_context'
+require_relative 'type/transcription'
 require_relative 'type/response_card/button'
 require_relative 'type/response_card'
 require_relative 'type/message/content_type'

data/lib/aws/lex/conversation/response/elicit_slot.rb

@@ -5,7 +5,7 @@ module Aws
     class Conversation
       module Response
         class ElicitSlot < Base
-          attr_accessor :slot_to_elicit
+          attr_accessor :slot_to_elicit, :slot_elicitation_style
 
           def initialize(opts = {})
             super
@@ -16,7 +16,8 @@ module Aws
           def dialog_action
             Aws::Lex::Conversation::Type::DialogAction.shrink_wrap(
               type: 'ElicitSlot',
-              slotToElicit: slot_to_elicit
+              slotToElicit: slot_to_elicit,
+              slotElicitationStyle: slot_elicitation_style
             )
           end
         end

data/lib/aws/lex/conversation/simulator.rb

@@ -120,13 +120,41 @@ module Aws
           self
         end
 
+        def proposed_next_state(opts = {})
+          data = {
+            dialogAction: lex_attributes(opts.fetch(:dialog_action)),
+            intent: lex_attributes(opts.fetch(:intent))
+          }
+          lex.proposed_next_state = Type::ProposedNextState.shrink_wrap(data)
+          self
+        end
+
         def session(data)
           lex.session_state.session_attributes.merge!(Type::SessionAttributes[data])
           self
         end
 
+        def transcription(opts = {})
+          data = {
+            transcription: opts.fetch(:transcription),
+            transcriptionConfidence: opts.fetch(:confidence, 1),
+            resolvedContext: {
+              intent: opts.fetch(:intent) { 'FallbackIntent' }
+            },
+            resolvedSlots: opts.fetch(:resolved_slots) { {} }
+          }
+          lex.transcriptions.push(Type::Transcription.shrink_wrap(data))
+          self
+        end
+
         private
 
+        def lex_attributes(instance)
+          return instance unless instance.respond_to?(:to_lex)
+
+          instance.to_lex
+        end
+
         def current_interpretation
           lex.interpretations.find { |i| i.intent.name == lex.session_state.intent.name }
         end

data/lib/aws/lex/conversation/slot/elicitation.rb

@@ -6,7 +6,7 @@ module Aws
       module Slot
         class Elicitation
           attr_accessor :name, :elicit, :messages, :follow_up_messages,
-                        :fallback, :maximum_elicitations, :conversation
+                        :fallback, :max_retries, :conversation
 
           def initialize(opts = {})
             self.name = opts.fetch(:name)
@@ -14,7 +14,7 @@ module Aws
             self.messages = opts.fetch(:messages)
             self.follow_up_messages = opts.fetch(:follow_up_messages) { opts.fetch(:messages) }
             self.fallback = opts[:fallback]
-            self.maximum_elicitations = opts.fetch(:maximum_elicitations) { 0 }
+            self.max_retries = opts[:max_retries] || opts[:maximum_elicitations] || 0
           end
 
           def elicit!
@@ -53,9 +53,7 @@ module Aws
           end
 
           def maximum_elicitations?
-            return false if maximum_elicitations.zero?
-
-            elicitation_attempts > maximum_elicitations
+            elicitation_attempts > max_retries
           end
 
           def first_elicitation?

data/lib/aws/lex/conversation/type/checkpoint.rb

@@ -20,6 +20,28 @@ module Aws
             fulfillment_state: FulfillmentState
           )
 
+          class << self
+            def build(opts = {})
+              new(normalize_parameters(opts))
+            end
+
+            private
+
+            def normalize_parameters(opts)
+              params = opts.dup # we don't want to mutate our arguments
+
+              if params[:dialog_action_type].is_a?(String)
+                params[:dialog_action_type] = DialogActionType.new(params[:dialog_action_type])
+              end
+
+              if params[:fulfillment_state].is_a?(String)
+                params[:fulfillment_state] = FulfillmentState.new(params[:fulfillment_state])
+              end
+
+              params
+            end
+          end
+
           # restore the checkpoint AND remove it from session
           def restore!(conversation, opts = {})
             conversation.checkpoints.delete_if { |c| c.label == label }

data/lib/aws/lex/conversation/type/dialog_action.rb

@@ -8,10 +8,12 @@ module Aws
           include Base
 
           optional :slot_to_elicit
+          optional :slot_elicitation_style, default: -> { 'Default' }
           required :type
 
           coerce(
-            type: DialogActionType
+            type: DialogActionType,
+            slot_elicitation_style: SlotElicitationStyle
           )
         end
       end

data/lib/aws/lex/conversation/type/event.rb

@@ -17,6 +17,8 @@ module Aws
           required :response_content_type
           required :session_id
           required :session_state
+          required :transcriptions, default: -> { [] }
+          optional :proposed_next_state
 
           computed_property(:current_intent, virtual: true) do |instance|
             instance.session_state.intent.tap do |intent|
@@ -41,9 +43,11 @@ module Aws
             input_mode: InputMode,
             interpretations: Array[Interpretation],
             invocation_source: InvocationSource,
+            proposed_next_state: ProposedNextState,
             request_attributes: symbolize_hash!,
             response_content_type: Message::ContentType,
-            session_state: SessionState
+            session_state: SessionState,
+            transcriptions: Array[Transcription]
           )
         end
       end

data/lib/aws/lex/conversation/type/message.rb

@@ -15,6 +15,11 @@ module Aws
             content_type: Message::ContentType,
             image_response_card: Aws::Lex::Conversation::Type::ResponseCard
           )
+
+          def initialize(opts = {})
+            assign_attributes!(opts)
+            self.content_type ||= ContentType.new('PlainText')
+          end
         end
       end
     end

data/lib/aws/lex/conversation/type/proposed_next_state.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class ProposedNextState
+          include Base
+
+          required :dialog_action
+          required :intent
+
+          coerce(
+            dialog_action: DialogAction,
+            intent: Intent
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/type/slot.rb

@@ -32,7 +32,7 @@ module Aws
           def value
             raise TypeError, 'use values for List-type slots' if shape.list?
 
-            lex_value.interpreted_value
+            lex_value&.interpreted_value
           end
 
           # takes an array of slot values

data/lib/aws/lex/conversation/type/slot_elicitation_style.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class SlotElicitationStyle
+          include Enumeration
+
+          enumeration('Default')
+          enumeration('SpellByLetter')
+          enumeration('SpellByWord')
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/type/transcription/resolved_context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class Transcription
+          class ResolvedContext
+            include Base
+
+            required :intent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/type/transcription.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class Transcription
+          include Base
+
+          required :transcription
+          required :transcription_confidence
+          optional :resolved_context
+          optional :resolved_slots
+          alias_method :confidence, :transcription_confidence
+
+          coerce(
+            resolved_context: Transcription::ResolvedContext,
+            resolved_slots: Array[Slot]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/version.rb

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '6.1.0'
+      VERSION = '6.4.0'
     end
   end
 end

data/lib/aws/lex/conversation.rb

@@ -5,10 +5,13 @@ require_relative 'conversation/base'
 module Aws
   module Lex
     class Conversation
+      extend Forwardable
       include Support::Mixins::Responses
 
       attr_accessor :event, :context, :lex
 
+      def_delegators :@lex, :proposed_next_state, :transcriptions
+
       def initialize(opts = {})
         self.event = opts.fetch(:event)
         self.context = opts.fetch(:context)
@@ -62,9 +65,9 @@ module Aws
         label = opts.fetch(:label)
         params = {
           label: label,
-          dialog_action_type: opts.fetch(:dialog_action_type),
+          dialog_action_type: opts.fetch(:dialog_action_type) { 'Delegate' },
           fulfillment_state: opts[:fulfillment_state],
-          intent: lex.current_intent,
+          intent: opts.fetch(:intent) { lex.current_intent },
           slot_to_elicit: opts[:slot_to_elicit]
         }.compact
 
@@ -72,9 +75,8 @@ module Aws
           # update the existing checkpoint
           checkpoint(label: label).assign_attributes!(params)
         else
-          # push a new checkpoint to the recent_intent_summary_view
           checkpoints.unshift(
-            Type::Checkpoint.new(params)
+            Type::Checkpoint.build(params)
           )
         end
       end
@@ -91,6 +93,21 @@ module Aws
         lex.session_state.session_attributes.checkpoints
       end
 
+      def restore_from!(checkpoint)
+        # we're done with the stored checkpoint once it's been restored
+        checkpoints.delete_if { |c| c.label == checkpoint.label }
+        # remove any memoized intent data
+        lex.current_intent = nil
+        # replace the intent with data from the checkpoint
+        lex.session_state.intent = checkpoint.intent
+        dialog_action = Type::DialogAction.new(
+          type: checkpoint.dialog_action_type,
+          slot_to_elicit: checkpoint.slot_to_elicit
+        )
+        lex.session_state.dialog_action = dialog_action
+        self
+      end
+
       def active_context?(name:)
         !active_context(name: name).nil?
       end
@@ -104,7 +121,7 @@ module Aws
         instance = active_context(name: name)
 
         if instance
-          lex.session_state.active_contexts.delete_if { |c| c.name == name }
+          clear_context!(name: name)
         else
           instance = Type::Context.new
         end
@@ -128,6 +145,10 @@ module Aws
         lex.session_state.active_contexts = []
       end
 
+      def proposed_next_state?
+        !proposed_next_state.nil?
+      end
+
       def stash
         @stash ||= {}
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aws-lex-conversation
 version: !ruby/object:Gem::Version
-  version: 6.1.0
+  version: 6.4.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -9,10 +9,10 @@ authors:
 - Darko Dosenovic
 - Zoie Carnegie
 - Carlos Mejia Castelo
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-08 00:00:00.000000000 Z
+date: 2022-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrink_wrap
@@ -92,6 +92,7 @@ files:
 - lib/aws/lex/conversation/type/invocation_source.rb
 - lib/aws/lex/conversation/type/message.rb
 - lib/aws/lex/conversation/type/message/content_type.rb
+- lib/aws/lex/conversation/type/proposed_next_state.rb
 - lib/aws/lex/conversation/type/response.rb
 - lib/aws/lex/conversation/type/response_card.rb
 - lib/aws/lex/conversation/type/response_card/button.rb
@@ -101,16 +102,20 @@ files:
 - lib/aws/lex/conversation/type/session_attributes.rb
 - lib/aws/lex/conversation/type/session_state.rb
 - lib/aws/lex/conversation/type/slot.rb
+- lib/aws/lex/conversation/type/slot_elicitation_style.rb
 - lib/aws/lex/conversation/type/slot_shape.rb
 - lib/aws/lex/conversation/type/slot_value.rb
 - lib/aws/lex/conversation/type/time_to_live.rb
+- lib/aws/lex/conversation/type/transcription.rb
+- lib/aws/lex/conversation/type/transcription/resolved_context.rb
 - lib/aws/lex/conversation/version.rb
 homepage: https://github.com/amaabca/aws-lex-conversation
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/amaabca/aws-lex-conversation
-post_install_message: 
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -126,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: AWS Lex Conversation Dialog Management
 test_files: []