aws-lex-conversation 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 148e207d8dcce051f2fc01244390021ae5734037a3b856462cd76ccd9e4cde8a
-  data.tar.gz: 7f019bdc51b68e037575a60784dbe76217aabccdf15e3394515d4a404dbdd85a
+  metadata.gz: 3d7e1994eb1948eceb9d236d65c0cc449e5120b6c91fb86585a7225e660cbc84
+  data.tar.gz: 071c8e344b1c6d78597986f679a7446250d2d2d75a001d4af7d393043c567529
 SHA512:
-  metadata.gz: 856f7ab5e25ffc87f93f3ee6f2b834acdd47cbc28adf334a22af4b152b37de435f54d3715374f33acfdf4ceebca1e2945b3557b5f72c4c5873e4b8761af5758a
-  data.tar.gz: e6dff0de003696ef87460e6dfdb54b94e470d4ff5b6470f43642dd259fa13b645b276d5d88413369dcacc7368004f4c93d92f38c1c50a5a18487c6cb2210e62d
+  metadata.gz: c83c69dfb06fd6faa16af4dfeb37119b84054c473e11929f201b34b419aba071918405635587ad38b21ce6d97862f60f1e360d9867059942deaea348a9eab176
+  data.tar.gz: f3cb8c0162884104b0ccb6f921c3cacdd08412d83b32e2463178b0a945b8e795de8da9bb99eabaaaf814de3b19b930e0a59972aea0dd128d8ca29d0da7e05982

data/.rubocop.yml

@@ -9,6 +9,14 @@ Documentation:
   Enabled: false
 Gemspec/RequiredRubyVersion:
   Enabled: false
+Layout/FirstArrayElementIndentation:
+  Enabled: false
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
+Metrics/AbcSize:
+  Max: 18
 Metrics/ClassLength:
   Max: 150
 Metrics/BlockLength:
@@ -27,3 +35,5 @@ Style/Lambda:
   EnforcedStyle: literal
 Style/GuardClause:
   Enabled: false
+Style/SlicingWithRange:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 2.0.0 - August 19, 2020
+
+* **breaking change:** Rename `Aws::Lex::Conversation::Type::CurrentIntent` to `Aws::Lex::Conversation::Type::Intent`.
+* **breaking change:** Built-in handlers now default the `options` attribute to an empty hash.
+* Add Lex NLU model improvement functionality (see: https://aws.amazon.com/about-aws/whats-new/2020/08/amazon-lex-launches-accuracy-improvements-and-confidence-scores/).
+* Add the `intent_confidence` method to the conversation class that may be used as follows:
+
+```ruby
+# NOTE: Lex model improvements must be enabled on the bot to get confidence data.
+# SEE: https://aws.amazon.com/about-aws/whats-new/2020/08/amazon-lex-launches-accuracy-improvements-and-confidence-scores/
+conversation.intent_confidence.ambiguous?         # true/false
+conversation.intent_confidence.unambiguous?       # true/false
+conversation.intent_confidence.candidates         # [...] the array contains the current_intent and all similar intents
+conversation.intent_confidence.similar_alternates # [...] the array doesn't contain the current_intent
+```
+
+* The calculation used to determine intent ambiguity by default looks for confidence scores that are within a standard deviation of the current intent's confidence score.
+* You can pass your own static `threshold` parameter if you wish to change this behaviour:
+
+```ruby
+conversation.intent_confidence.ambiguous?(threshold: 0.4) # true/false
+```
+
+* Implement a built-in `SlotResolution` handler that is intended to act as the initial handler in the chain. This handler will resolve all slot values to their top resolution, then call the successor handler.

data/README.md

@@ -58,13 +58,13 @@ The first handler that returns `true` for the `will_respond?` method will provid
 ```ruby
 class SayHello < Aws::Lex::Conversation::Handler::Base
   def will_respond?(conversation)
-    conversation.lex.incovation_source.dialog_code_hook? && # callback is for DialogCodeHook (i.e. validation)
+    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]                               # our expected slot value is set
+    conversation.slots[:name].filled?                       # our expected slot value is set
   end
 
   def response(conversation)
-    name = conversation.slots[:name]
+    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.
@@ -141,6 +141,34 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Delegate' } }
 ```
 
+### `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.
+
+**NOTE:** This handler must not be the final handler in the chain. An exception of type `Aws::Lex::Conversation::Exception::MissingHandler` will be raised if there is no successor handler.
+
+| Option           | Required | Description                                                  | Default Value                       |
+|------------------|----------|--------------------------------------------------------------|-------------------------------------|
+| respond_on       | No       | A callable that provides the condition for `will_handle?`.   | `->(c) { true }`                   |
+
+i.e.
+
+```ruby
+conversation = Aws::Lex::Conversation.new(event: event, context: context)
+conversation.handlers = [
+  {
+    handler: Aws::Lex::Conversation::Handler::SlotResolution
+  },
+  {
+    handler: Aws::Lex::Conversation::Handler::Delegate,
+    options: {
+      respond_on: ->(c) { true }
+    }
+  }
+]
+conversation.respond # => { dialogAction: { type: 'Delegate' } }
+```
+
 ## Development
 
 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.

data/lib/aws/lex/conversation.rb

@@ -42,6 +42,10 @@ module Aws
         chain.first.handle(self)
       end
 
+      def intent_confidence
+        @intent_confidence ||= Type::IntentConfidence.new(event: lex)
+      end
+
       def intent_name
         lex.current_intent.name
       end

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

@@ -4,6 +4,7 @@ require 'json'
 require 'shrink/wrap'
 
 require_relative 'version'
+require_relative 'exception/missing_handler'
 require_relative 'response/base'
 require_relative 'response/close'
 require_relative 'response/confirm_intent'
@@ -24,11 +25,12 @@ require_relative 'type/invocation_source'
 require_relative 'type/dialog_action_type'
 require_relative 'type/confirmation_status'
 require_relative 'type/fulfillment_state'
+require_relative 'type/intent_confidence'
 require_relative 'type/recent_intent_summary_view'
 require_relative 'type/slot'
 require_relative 'type/slot_resolution'
 require_relative 'type/slot_detail'
-require_relative 'type/current_intent'
+require_relative 'type/intent'
 require_relative 'type/output_dialog_mode'
 require_relative 'type/bot'
 require_relative 'type/message/content_type'
@@ -42,3 +44,4 @@ require_relative 'type/event'
 require_relative 'handler/base'
 require_relative 'handler/echo'
 require_relative 'handler/delegate'
+require_relative 'handler/slot_resolution'

data/lib/aws/lex/conversation/exception/missing_handler.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Exception
+        class MissingHandler < StandardError
+        end
+      end
+    end
+  end
+end

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

@@ -9,7 +9,7 @@ module Aws
 
           def initialize(opts = {})
             self.successor = opts[:successor]
-            self.options = opts[:options]
+            self.options = opts[:options] || {}
           end
 
           def will_respond?(conversation)

data/lib/aws/lex/conversation/handler/slot_resolution.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Handler
+        class SlotResolution < Base
+          def will_respond?(conversation)
+            # respond by default unless told otherwise
+            callable = options.fetch(:respond_on) { ->(_c) { true } }
+            callable.call(conversation)
+          end
+
+          def response(conversation)
+            # resolve all slots to their top resolution
+            conversation.slots.values.each(&:resolve!)
+
+            unless successor
+              msg = 'Handler `SlotResolution` must not be the final handler in the chain'
+              raise Exception::MissingHandler, msg
+            end
+
+            # call the next handler in the chain
+            successor.handle(conversation)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -45,7 +45,11 @@ module Aws
           end
 
           def elicitation_content
-            first_elicitation? ? message : follow_up_message
+            first_elicitation? ? compose_message(message) : compose_message(follow_up_message)
+          end
+
+          def compose_message(msg)
+            msg.is_a?(Proc) ? msg.call(conversation) : msg
           end
 
           def increment_slot_elicitations!

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

@@ -19,7 +19,8 @@ module Aws
 
           module InstanceMethods
             def assign_attributes!(opts = {})
-              self.class.attributes.each do |attribute|
+              attributes = self.class.attributes | self.class.virtual_attributes
+              attributes.each do |attribute|
                 instance_variable_set("@#{attribute}", opts[attribute])
               end
             end
@@ -52,14 +53,29 @@ module Aws
           end
 
           module ClassMethods
-            def integer!
-              ->(v) { v.to_i }
+            def integer!(nilable: false)
+              nilable ? ->(v) { v&.to_i } : ->(v) { v.to_i }
+            end
+
+            def float!(nilable: false)
+              nilable ? ->(v) { v&.to_f } : ->(v) { v.to_f }
             end
 
             def symbolize_hash!
               ->(v) { v.transform_keys(&:to_sym) }
             end
 
+            def computed_property(attribute, callable)
+              mapping[attribute] = attribute
+              attr_writer(attribute)
+
+              # dynamically memoize the result
+              define_method(attribute) do
+                instance_variable_get("@#{attribute}") ||
+                  instance_variable_set("@#{attribute}", callable.call(self))
+              end
+            end
+
             def required(attribute, opts = {})
               property(attribute, opts.merge(allow_nil: false))
             end
@@ -76,7 +92,12 @@ module Aws
 
               attr_accessor(attribute)
 
-              mapping[attribute] = from
+              if opts.fetch(:virtual) { false }
+                virtual_attributes << attribute
+              else
+                mapping[attribute] = from
+              end
+
               translate(attribute => params)
             end
 
@@ -84,6 +105,10 @@ module Aws
               @attributes ||= mapping.keys
             end
 
+            def virtual_attributes
+              @virtual_attributes ||= []
+            end
+
             def mapping
               @mapping ||= {}
             end

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

@@ -7,6 +7,7 @@ module Aws
         class Event
           include Base
 
+          required :alternative_intents, default: -> { [] }
           required :current_intent
           required :bot
           required :user_id
@@ -20,8 +21,13 @@ module Aws
           optional :sentiment_response
           optional :kendra_response
 
+          computed_property :intents, ->(instance) do
+            [instance.current_intent] | instance.alternative_intents
+          end
+
           coerce(
-            current_intent: CurrentIntent,
+            alternative_intents: Array[Intent],
+            current_intent: Intent,
             bot: Bot,
             invocation_source: InvocationSource,
             output_dialog_mode: OutputDialogMode,

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class Intent
+          include Base
+
+          required :name
+          required :raw_slots, from: :slots, virtual: true
+          required :slot_details
+          required :confirmation_status
+          optional :nlu_intent_confidence_score
+
+          computed_property :slots, ->(instance) do
+            instance.raw_slots.each_with_object({}) do |(key, value), hash|
+              hash[key.to_sym] = Slot.shrink_wrap(
+                name: key,
+                value: value,
+                # pass a reference to the parent down to the slot so that each slot
+                # instance can view a broader scope such as slot_details/resolutions
+                current_intent: instance
+              )
+            end
+          end
+
+          class << self
+            def slot_details!
+              ->(val) do
+                val
+                  .reject { |_, v| v.nil? }
+                  .each_with_object({}) do |(key, value), hash|
+                    hash[key.to_sym] = SlotDetail.shrink_wrap(value)
+                  end
+              end
+            end
+          end
+
+          coerce(
+            slot_details: slot_details!,
+            confirmation_status: ConfirmationStatus,
+            nlu_intent_confidence_score: float!(nilable: true)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class IntentConfidence
+          include Base
+
+          required :event
+
+          def ambiguous?(threshold: standard_deviation)
+            candidates(threshold: threshold).size > 1
+          end
+
+          def unambiguous?(threshold: standard_deviation)
+            !ambiguous?(threshold: threshold)
+          end
+
+          # NOTE: by default this method looks for candidates
+          # with a confidence score within one standard deviation
+          # of the current intent. Confidence scores may not be
+          # normally distributed, so it's very possible that this
+          # method will return abnormal results for skewed sample sets.
+          #
+          # If you want a consistent threshold for the condition, pass
+          # a static `threshold` parameter.
+          def candidates(threshold: standard_deviation)
+            intents = event.intents.select do |intent|
+              diff = event.current_intent
+                .nlu_intent_confidence_score
+                .to_f
+                .-(intent.nlu_intent_confidence_score.to_f)
+                .abs
+
+              diff <= threshold
+            end
+
+            # sort descending
+            intents.sort do |a, b|
+              b.nlu_intent_confidence_score.to_f <=> a.nlu_intent_confidence_score.to_f
+            end
+          end
+
+          def mean
+            @mean ||= calculate_mean
+          end
+
+          def similar_alternates(threshold: standard_deviation)
+            # remove the first element (current intent) from consideration
+            candidates(threshold: threshold)[1..-1]
+          end
+
+          def standard_deviation
+            @standard_deviation ||= calculate_standard_deviation
+          end
+
+          private
+
+          def calculate_mean
+            sum = event.intents.sum { |i| i.nlu_intent_confidence_score.to_f }
+            sum / event.intents.size
+          end
+
+          def calculate_standard_deviation
+            normalized = event.intents.map do |intent|
+              (intent.nlu_intent_confidence_score.to_f - mean) ** 2
+            end
+            normalized_mean = normalized.sum / normalized.size
+            Math.sqrt(normalized_mean)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,9 +7,14 @@ module Aws
         class Slot
           include Base
 
+          required :current_intent, from: :current_intent, virtual: true
           required :name
           required :value
 
+          def as_json(_opts = {})
+            to_lex
+          end
+
           def to_lex
             value
           end
@@ -17,6 +22,28 @@ module Aws
           def filled?
             value.to_s != ''
           end
+
+          def resolve!(index: 0)
+            self.value = resolved(index: index)
+          end
+
+          def resolved(index: 0)
+            details.resolutions.fetch(index) { SlotResolution.new(value: value) }.value
+          end
+
+          def original_value
+            details.original_value
+          end
+
+          def resolvable?
+            details.resolutions.any?
+          end
+
+          def details
+            @details ||= current_intent.slot_details.fetch(name.to_sym) do
+              SlotDetail.new(name: name, resolutions: [], original_value: value)
+            end
+          end
         end
       end
     end

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

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '1.0.0'
+      VERSION = '2.0.0'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aws-lex-conversation
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-26 00:00:00.000000000 Z
+date: 2020-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrink_wrap
@@ -44,6 +44,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".simplecov"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.md
@@ -55,9 +56,11 @@ files:
 - lib/aws-lex-conversation.rb
 - lib/aws/lex/conversation.rb
 - lib/aws/lex/conversation/base.rb
+- lib/aws/lex/conversation/exception/missing_handler.rb
 - lib/aws/lex/conversation/handler/base.rb
 - lib/aws/lex/conversation/handler/delegate.rb
 - lib/aws/lex/conversation/handler/echo.rb
+- lib/aws/lex/conversation/handler/slot_resolution.rb
 - lib/aws/lex/conversation/response/base.rb
 - lib/aws/lex/conversation/response/close.rb
 - lib/aws/lex/conversation/response/confirm_intent.rb
@@ -72,11 +75,12 @@ files:
 - lib/aws/lex/conversation/type/base.rb
 - lib/aws/lex/conversation/type/bot.rb
 - lib/aws/lex/conversation/type/confirmation_status.rb
-- lib/aws/lex/conversation/type/current_intent.rb
 - lib/aws/lex/conversation/type/dialog_action_type.rb
 - lib/aws/lex/conversation/type/enumeration.rb
 - lib/aws/lex/conversation/type/event.rb
 - lib/aws/lex/conversation/type/fulfillment_state.rb
+- lib/aws/lex/conversation/type/intent.rb
+- lib/aws/lex/conversation/type/intent_confidence.rb
 - lib/aws/lex/conversation/type/invocation_source.rb
 - lib/aws/lex/conversation/type/message.rb
 - lib/aws/lex/conversation/type/message/content_type.rb

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

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Aws
-  module Lex
-    class Conversation
-      module Type
-        class CurrentIntent
-          include Base
-
-          required :name
-          required :slots
-          required :slot_details
-          required :confirmation_status
-
-          class << self
-            def slots!
-              ->(v) do
-                v.each_with_object({}) do |(key, value), hash|
-                  hash[key.to_sym] = Slot.shrink_wrap(
-                    name: key,
-                    value: value
-                  )
-                end
-              end
-            end
-
-            def slot_details!
-              ->(v) do
-                v.each_with_object({}) do |(key, value), hash|
-                  hash[key.to_sym] = SlotDetail.shrink_wrap(value)
-                end
-              end
-            end
-          end
-
-          coerce(
-            slots: slots!,
-            slot_details: slot_details!,
-            confirmation_status: ConfirmationStatus
-          )
-        end
-      end
-    end
-  end
-end