aws-lex-conversation 6.1.1 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f15c999ea65d5d749443fbed6e0871abe69ffa65d399febdd2900d5d99b9730c
-  data.tar.gz: 21165febaf008f32900422e98dffa448dc6caefade98908c5dc6e0b32e97cab9
+  metadata.gz: 3a4ab092d321df0c71e5f16cf1021e87358b1b39ab025eaf5555e3e3da7894c1
+  data.tar.gz: a0332c4f2f73b35972c83a0740e1adfa4d724fe5d9861087d348e905e3e15633
 SHA512:
-  metadata.gz: a6a2fbd9f33532e9e73bd130bd42983ebc1bc8398c9425ac9f8d82f12d55e941d8979bdc498341a85a99462f74b0de5a42afea61ad15422c0b0032d55d8fd207
-  data.tar.gz: 929adca898e5825a5eb7b9261ad78647487a9d452e66d83c06035f3c0fc564ae01035f6df8143e201ea12db976144980c04d7b1f842deb60ccbc1b8fd7c537a1
+  metadata.gz: 734b1ec8921c8982a3e123520b08b0d0b9e655159c781f7df18d106b8de635815bc026862fd6a4ec7a3d2665d47393bb8d977cf530a1331e2f3c2bea543b4a94
+  data.tar.gz: 2c4c43bafd522791d6f5f39596c7b594d3788098876b51fc8294cf2304a23c42a06fd6635e15e791410bc824273599f9afab3935fd853981f81b732672d03d96

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 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

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

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '6.1.1'
+      VERSION = '6.2.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aws-lex-conversation
 version: !ruby/object:Gem::Version
-  version: 6.1.1
+  version: 6.2.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-22 00:00:00.000000000 Z
+date: 2021-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrink_wrap