aws-lex-conversation 6.0.0 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c078b6b854b3df1824942655b7dd763f72dcc1a439c61e0830e1a644a0c2a65
-  data.tar.gz: 8f279c911fceacdc67005e02a09b04bd854e71f30d1212a92ca9d6aff5fe1f75
+  metadata.gz: 33df2c318e3e0d2e3157ebe43e27b38855334518efa5fa957be0e1035e6454f2
+  data.tar.gz: 5f7db4ab55ef155967688aae6a85781b1fca26860574d45280cfceb2e410b730
 SHA512:
-  metadata.gz: 41b0d384f766900de162b9b7a49d9e4ffc0375168c9f33a7c7e238dfe72fdeb7d21a9ad366c3f9f7b31b2dffde1b06c02a6f6c164fddec5453915bf4403cb8d7
-  data.tar.gz: ab4d16c2892aa0f8bf2c25e67f133a64d6c7e583283a1a960f12602da69cedf83d7242960d789e77d03b43c3ba43411fbabfc8a147668cd4f79151eea078886e
+  metadata.gz: 4831b1eed996b95384635c446a2432efbb765900a8ef814c089ab4bbbfa5311708b0f71fe080d5b4910110448c698dfe855747bc2d9b9a8b19643743581b9c86
+  data.tar.gz: 53cdad241f6ace96a3ea1cb7be904f3518edbab40a403c8ab0641ea26cc6629ae1e0ce16b642cf08217a6f06017936e5865ac01be74e3fdeb620f4654edad52c

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,3 +1,36 @@
+# 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.
@@ -55,6 +88,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

@@ -191,6 +191,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:

data/aws-lex-conversation.gemspec

@@ -26,6 +26,7 @@ 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)/}) }

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

@@ -25,6 +25,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'

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/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/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/version.rb

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '6.0.0'
+      VERSION = '6.3.0'
     end
   end
 end

data/lib/aws/lex/conversation.rb

@@ -62,9 +62,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 +72,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 +90,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 +118,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
@@ -120,6 +134,14 @@ module Aws
         instance
       end
 
+      def clear_context!(name:)
+        lex.session_state.active_contexts.delete_if { |c| c.name == name }
+      end
+
+      def clear_all_contexts!
+        lex.session_state.active_contexts = []
+      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.0.0
+  version: 6.3.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-07 00:00:00.000000000 Z
+date: 2021-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrink_wrap
@@ -101,6 +101,7 @@ 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
@@ -110,6 +111,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/amaabca/aws-lex-conversation
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: