aws-lex-conversation 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb6d1313f30041f9896bccc30fe2511d7eb0f377f505dc3c3c8e153e2838151d
-  data.tar.gz: aa0804ca414e0c68d982ae8ba601a7f46a729678130babb56d7eb87edf119cd3
+  metadata.gz: 3d7e1994eb1948eceb9d236d65c0cc449e5120b6c91fb86585a7225e660cbc84
+  data.tar.gz: 071c8e344b1c6d78597986f679a7446250d2d2d75a001d4af7d393043c567529
 SHA512:
-  metadata.gz: 3471ce6eddb122e71cb81aad093e663165bae469b8317c045eddb4f3ba21412ed3815e3f9e895aea121a6af61ae143abb15c0cff1520c10243bfe51a807b09b8
-  data.tar.gz: 906124b34ad1218de0c2725942620fc530120b855cf8e12552c8fc9b841fa18894a7327d92e908ff02e8e3bf276da7d1c4a951efcb87bb2c8f4dd19ecf057bc0
+  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

@@ -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/type/base.rb

@@ -53,8 +53,12 @@ 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!

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/{current_intent.rb → intent.rb}

@@ -4,13 +4,14 @@ module Aws
   module Lex
     class Conversation
       module Type
-        class CurrentIntent
+        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|
@@ -38,7 +39,8 @@ module Aws
 
           coerce(
             slot_details: slot_details!,
-            confirmation_status: ConfirmationStatus
+            confirmation_status: ConfirmationStatus,
+            nlu_intent_confidence_score: float!(nilable: true)
           )
         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/version.rb

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '1.2.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.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-07-22 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