aws-lex-conversation 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 113a515e1c05389f5ab8d57fae23a54fc6cc212645d2bea1e091c5f750aabe08
-  data.tar.gz: b9233099ad5faae9ce4c530565be798703d5bfedccd981ab6835a8b6c01d5f82
+  metadata.gz: 50a4b4cc2a28aa4251723f715953de0a102e7cabb0268db095e50470e49e2772
+  data.tar.gz: a5bd7550ef4a7391c0d9221ac86b3c1760053b03dda9932d8416778f4ea319e5
 SHA512:
-  metadata.gz: b712aef8787b4b0754b420027abddcee9ea51fe030c590c0caea229629099542d44979d1b8bf6b5a1e29a5bbf37c6ec10c33ac9493fbffbeeb6b84deb9daaaf3
-  data.tar.gz: 0cf7de36b758c798068ac23b4d1e73b07252b9ed39ed36bebdd648d0aa060088bfd5c77ea21fed00c8338ca9a434c540f0c5fd08f695011705672c24c7bfb926
+  metadata.gz: 48883e2e7ce637dc0b6a327bdf839b9e233a3a1bc06f99b318f5bdbf83e91c762fb8c2bbe1ffc597ac8a6900d7a01ee4dfab7a67a52c2f941595754e13f8cb06
+  data.tar.gz: 3bf93255a75da95213ffc74a7a3a86785bba94ea70d758c53dbad1c351b3567f5bb6f23adffafbf67e7581ad9f4a9ece31a489ef35b9cd3ad31311121a209105

data/.rubocop.yml

@@ -5,25 +5,42 @@ AllCops:
   Exclude:
     - 'bin/**/*'
     - 'vendor/**/*'
-Documentation:
-  Enabled: false
+  SuggestExtensions: false
 Gemspec/RequiredRubyVersion:
   Enabled: false
+Layout/FirstArrayElementIndentation:
+  Enabled: false
+Layout/LineLength:
+  Max: 130
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
+Metrics/AbcSize:
+  Max: 20
 Metrics/ClassLength:
   Max: 150
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
     - '*.gemspec'
-Metrics/LineLength:
-  Max: 130
 Metrics/MethodLength:
   Max: 25
 Naming/FileName:
   Enabled: true
   Exclude:
     - lib/aws-lex-conversation.rb
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+Style/Documentation:
+  Enabled: false
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false
 Style/Lambda:
   EnforcedStyle: literal
 Style/GuardClause:
   Enabled: false
+Style/RedundantFetchBlock:
+  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/Gemfile

@@ -8,5 +8,5 @@ gem 'factory_bot'
 gem 'pry'
 gem 'rake'
 gem 'rspec'
-gem 'rubocop', '0.85.1'
+gem 'rubocop', '~> 1.9', require: false
 gem 'simplecov'

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,14 @@ 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/time_to_live'
 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/context'
+require_relative 'type/intent'
 require_relative 'type/output_dialog_mode'
 require_relative 'type/bot'
 require_relative 'type/message/content_type'
@@ -42,3 +46,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/response/base.rb

@@ -5,11 +5,16 @@ module Aws
     class Conversation
       module Response
         class Base
-          attr_accessor :session_attributes, :recent_intent_summary_view
+          attr_accessor(
+            :active_contexts,
+            :recent_intent_summary_view,
+            :session_attributes
+          )
 
           def initialize(opts = {})
-            self.session_attributes = opts[:session_attributes]
+            self.active_contexts = opts[:active_contexts]
             self.recent_intent_summary_view = opts[:recent_intent_summary_view]
+            self.session_attributes = opts[:session_attributes]
           end
 
           def dialog_action
@@ -18,9 +23,10 @@ module Aws
 
           def to_lex
             Type::Response.new(
-              session_attributes: session_attributes,
+              active_contexts: active_contexts,
+              dialog_action: dialog_action,
               recent_intent_summary_view: recent_intent_summary_view,
-              dialog_action: dialog_action
+              session_attributes: session_attributes
             ).to_lex
           end
         end

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

@@ -20,7 +20,7 @@ module Aws
               fulfillmentState: fulfillment_state,
               message: message,
               responseCard: response_card
-            }.reject { |_, v| v.nil? }
+            }.compact
           end
         end
       end

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

@@ -22,7 +22,7 @@ module Aws
               slots: slots,
               message: message,
               responseCard: response_card
-            }.reject { |_, v| v.nil? }
+            }.compact
           end
         end
       end

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

@@ -20,7 +20,7 @@ module Aws
               slots: slots,
               kendraQueryRequestPayload: kendra_query_request_payload,
               kendraQueryFilterString: kendra_query_filter_string
-            }.reject { |_, v| v.nil? }
+            }.compact
           end
         end
       end

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

@@ -18,7 +18,7 @@ module Aws
               type: 'ElicitIntent',
               message: message,
               responseCard: response_card
-            }.reject { |_, v| v.nil? }
+            }.compact
           end
         end
       end

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

@@ -24,7 +24,7 @@ module Aws
               slotToElicit: slot_to_elicit,
               message: message,
               responseCard: response_card
-            }.reject { |_, v| v.nil? }
+            }.compact
           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/support/mixins/responses.rb

@@ -8,17 +8,19 @@ module Aws
           module Responses
             def close(opts = {})
               params = {
-                session_attributes: lex.session_attributes,
-                recent_intent_summary_view: lex.recent_intent_summary_view
+                active_contexts: lex.active_contexts,
+                recent_intent_summary_view: lex.recent_intent_summary_view,
+                session_attributes: lex.session_attributes
               }.merge(opts)
               Response::Close.new(params).to_lex
             end
 
             def confirm_intent(opts = {})
               params = {
-                session_attributes: lex.session_attributes,
-                recent_intent_summary_view: lex.recent_intent_summary_view,
+                active_contexts: lex.active_contexts,
                 intent_name: lex.current_intent.name,
+                recent_intent_summary_view: lex.recent_intent_summary_view,
+                session_attributes: lex.session_attributes,
                 slots: lex.current_intent.slots
               }.merge(opts)
               Response::ConfirmIntent.new(params).to_lex
@@ -26,8 +28,9 @@ module Aws
 
             def delegate(opts = {})
               params = {
-                session_attributes: lex.session_attributes,
+                active_contexts: lex.active_contexts,
                 recent_intent_summary_view: lex.recent_intent_summary_view,
+                session_attributes: lex.session_attributes,
                 slots: lex.current_intent.slots
               }.merge(opts)
               Response::Delegate.new(params).to_lex
@@ -35,18 +38,20 @@ module Aws
 
             def elicit_intent(opts = {})
               params = {
-                session_attributes: lex.session_attributes,
-                recent_intent_summary_view: lex.recent_intent_summary_view
+                active_contexts: lex.active_contexts,
+                recent_intent_summary_view: lex.recent_intent_summary_view,
+                session_attributes: lex.session_attributes
               }.merge(opts)
               Response::ElicitIntent.new(params).to_lex
             end
 
             def elicit_slot(opts = {})
               params = {
-                session_attributes: lex.session_attributes,
+                active_contexts: lex.active_contexts,
+                intent_name: lex.current_intent.name,
                 recent_intent_summary_view: lex.recent_intent_summary_view,
-                slots: lex.current_intent.slots,
-                intent_name: lex.current_intent.name
+                session_attributes: lex.session_attributes,
+                slots: lex.current_intent.slots
               }.merge(opts)
               Response::ElicitSlot.new(params).to_lex
             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/context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class Context
+          include Base
+
+          required :time_to_live
+          required :name
+          required :parameters
+
+          coerce(
+            time_to_live: TimeToLive,
+            parameters: symbolize_hash!
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,8 @@ module Aws
         class Event
           include Base
 
+          required :active_contexts, default: -> { [] }
+          required :alternative_intents, default: -> { [] }
           required :current_intent
           required :bot
           required :user_id
@@ -20,8 +22,14 @@ module Aws
           optional :sentiment_response
           optional :kendra_response
 
+          computed_property :intents, ->(instance) do
+            [instance.current_intent] | instance.alternative_intents
+          end
+
           coerce(
-            current_intent: CurrentIntent,
+            active_contexts: Array[Context],
+            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|
@@ -26,17 +27,20 @@ module Aws
 
           class << self
             def slot_details!
-              ->(v) do
-                v.each_with_object({}) do |(key, value), hash|
-                  hash[key.to_sym] = SlotDetail.shrink_wrap(value)
-                end
+              ->(val) do
+                val
+                  .compact
+                  .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
+            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/type/response.rb

@@ -10,6 +10,7 @@ module Aws
           required :dialog_action
           optional :session_attributes
           optional :recent_intent_summary_view
+          optional :active_contexts
         end
       end
     end

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

@@ -11,6 +11,10 @@ module Aws
           required :name
           required :value
 
+          def as_json(_opts = {})
+            to_lex
+          end
+
           def to_lex
             value
           end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class TimeToLive
+          include Base
+
+          required :time_to_live_in_seconds
+          required :turns_to_live
+
+          coerce(
+            time_to_live_in_seconds: integer!,
+            turns_to_live: integer!
+          )
+
+          alias_method :seconds, :time_to_live_in_seconds
+          alias_method :seconds=, :time_to_live_in_seconds=
+          alias_method :turns, :turns_to_live
+          alias_method :turns=, :turns_to_live=
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '1.1.0'
+      VERSION = '2.1.0'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aws-lex-conversation
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-29 00:00:00.000000000 Z
+date: 2021-02-11 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,13 @@ 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/context.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
@@ -93,6 +98,7 @@ files:
 - lib/aws/lex/conversation/type/slot.rb
 - lib/aws/lex/conversation/type/slot_detail.rb
 - lib/aws/lex/conversation/type/slot_resolution.rb
+- lib/aws/lex/conversation/type/time_to_live.rb
 - lib/aws/lex/conversation/version.rb
 homepage: https://github.com/amaabca/aws-lex-conversation
 licenses:
@@ -114,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: AWS Lex Conversation Dialog Management