aws-lex-conversation 6.3.0 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33df2c318e3e0d2e3157ebe43e27b38855334518efa5fa957be0e1035e6454f2
-  data.tar.gz: 5f7db4ab55ef155967688aae6a85781b1fca26860574d45280cfceb2e410b730
+  metadata.gz: 61c4edf66e617becb5f2c7aa3611e32c7eeef58ab2cb9533f1816abcaf675ab8
+  data.tar.gz: 485e85d4c07d25527752e2451e99c02af1eae808dfd9e048efa147a8042d76aa
 SHA512:
-  metadata.gz: 4831b1eed996b95384635c446a2432efbb765900a8ef814c089ab4bbbfa5311708b0f71fe080d5b4910110448c698dfe855747bc2d9b9a8b19643743581b9c86
-  data.tar.gz: 53cdad241f6ace96a3ea1cb7be904f3518edbab40a403c8ab0641ea26cc6629ae1e0ce16b642cf08217a6f06017936e5865ac01be74e3fdeb620f4654edad52c
+  metadata.gz: 03f8814a82e0f6cea94033ef13d4f59ade4bb74a1cee26fe554151bff1b0785f32f0c3aef17e2a2293a1c71dd4442679ee516a9d16bd1bc94069e0e00dccfb3f
+  data.tar.gz: 360cb550a21e90e6063722c676071ed59d083e6a03eb44281f2517b79b8e2a70ccfeb435ad0df4b37b1c46a8e6e9e4258505622b6396f3168a140eb9e2998524

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 6.4.0 - Feb 10, 2022
+
+* Add support for the new protocol properties of `proposedNextState` and `transcriptions`. This enables support for [transcription confidence scores](https://docs.aws.amazon.com/lexv2/latest/dg/using-transcript-confidence-scores.html).
+* Expose the following methods on `Aws::Lex::Conversation` instances:
+  - `proposed_next_state?`: Returns `true` if a `proposedNextState` value is present or `false` otherwise.
+  - `proposed_next_state`: Returns an `Aws::Lex::Conversation::Type::ProposedNextState` instance. May return `nil`.
+  - `transcriptions`: Returns an array of `Aws::Lex::Conversation::Type::Transcription` instances. Defaults to a empty array if the `transcriptions` property is not present.
+* Make the `content_type` attribute in the constructor for `Aws::Lex::Conversation::Type::Message` default to `PlainText` when not present.
+
 # 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)).

data/README.md

@@ -1,19 +1,15 @@
-# Aws::Lex::Conversation
+# `Aws::Lex::Conversation`
 
-Have you played around with [AWS Lex](https://aws.amazon.com/lex/) and quickly realized you were duplicating code to read and generate the [Lex Lambda input event and response format](https://docs.aws.amazon.com/lex/latest/dg/lambda-input-response-format.html)?
+Building a chatbot with [AWS Lex](https://aws.amazon.com/lex/) is really fun! Unfortunately implementing your bot's behaviour with the [Lex/Lambda event protocol](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html) is less fun.
 
-`Aws::Lex::Conversation` provides a mechanism to define the flow of a Lex conversation with a user easily!
+But don't worry - we've done the hard work for you!
 
-## Installation
-
-### Lex V1
-
-Version 3.x is the last major version of this gem that will support Lex V1.
+`Aws::Lex::Conversation` makes it simple to build dynamic, conversational chatbots with AWS Lex and AWS Lambda!
 
-Add this line to your application's Gemfile:
+## Installation
 
 ```ruby
-gem 'aws-lex-conversation', '~> 3.0'
+gem 'aws-lex-conversation'
 ```
 
 And then execute:
@@ -22,96 +18,162 @@ And then execute:
 bundle install
 ```
 
-### Lex V2
+**Please Note:** This library currently supports [AWS Lex Version 2](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html). If you're looking for Lex V1 support, lock `aws-lex-conversation` to `~> 3.0` in your `Gemfile`.
+
+## Core Concepts
+
+### The Conversation Instance
 
-Version 4.x and higher support Lex V2.
+Instances of `Aws::Lex::Conversation` wrap the Lex input/output event format and make it easy to manage conversation dialog.
 
-Add this line to your application's Gemfile:
+Imagine you have a `ButlerBot` configured with a `ServeBreakfast` intent and `BreakfastFood` slot.
+
+The backing lambda handler for your bot might look something like:
 
 ```ruby
-gem 'aws-lex-conversation', '>= 4.0'
+require "aws-lex-conversation"
+
+def lambda_handler(event:, context:)
+  # The conversation instance validates and wraps the Lex input event
+  conversation = Aws::Lex::Conversation.new(event: event, context: context)
+
+  # Return a Close dialog action to our Lex bot and end the conversation
+  conversation.close(
+    fulfillment_state: "Fulfilled",
+    messages: [
+      # We can construct response messages using wrapper classes.
+      Aws::Lex::Conversation::Type::Message.new(
+        content: "Hi - I'm a 🤖!"
+      ),
+      # Or we can pass a Hash that directly maps to the Lex response format
+      {
+        content: "Your intent is: #{conversation.intent_name}",
+        contentType: "PlainText"
+      },
+      {
+        content: "Here's your #{conversation.slots[:BreakfastFood].value}!",
+        contentType: "PlainText"
+      }
+    ]
+  )
+end
 ```
 
-And then execute:
+This lambda handler would generate the following dialog:
 
-```bash
-bundle install
+![ButlerBot Dialog](https://raw.github.com/amaabca/aws-lex-conversation/master/data/butler_bot.png)
+
+All data from the Lex input event is exposed via the `lex` attribute. By convention, the `lex` attribute directly translates input event attributes from `camelCase` to `snake_case`.
+
+We also provide some helpers to help manage the conversation. For example:
+
+```ruby
+# returns true if the lambda function was invoked as a DialogCodeHook
+conversation.lex.invocation_source.dialog_code_hook?
+
+# returns true if the InputMode is Speech
+conversation.lex.input_mode.speech?
+
+# you can easily set or retrieve a session values
+conversation.session[:name] = "Jane"
+conversation.session[:name] # => "Jane"
+
+# dealing with slot data is simple
+conversation.slots[:BreakfastFood].filled? # returns true if a slot value is present
+conversation.slots[:Hometown].blank?       # returns true if a slot value is nil/empty
+conversation.slots[:FirstName].value       # => "John"
 ```
 
-## Usage
+### The Handler Chain
+
+Conversational dialog gets complex quickly! Conversation instances include a handler chain that can help manage this complexity.
 
-At a high level, you must create a new instance of `Aws::Lex::Conversation`.
+Each handler in the chain defines the prerequisites necessary for the handler to generate a response.
 
-Generally the conversation instance will be initialized inside your Lambda handler method as follows:
+You can configure the handler chain as follows:
 
 ```ruby
-def my_lambda_handler(event:, context:)
+def lambda_handler(event:, context:)
   conversation = Aws::Lex::Conversation.new(event: event, context: context)
 
-  # define a chain of your own Handler classes
   conversation.handlers = [
+    # You need to define custom handler classes yourself
+    { handler: ServeBreakfast },
+    { handler: FallbackIntent },
+    # We offer a few "built in" handlers
     {
       handler: Aws::Lex::Conversation::Handler::Delegate,
       options: {
-        respond_on: ->(conversation) { conversation.current_intent.name == 'MyIntent' }
+        # If we get this far, always return a Delegate action
+        respond_on: ->(_) { true }
       }
     }
   ]
 
-  # return a response object to indicate Lex's next action
+  # The respond method will execute each handler sequentially and return a Lex response
   conversation.respond
 end
 ```
 
-Any custom behaviour in your flow is achieved by defining a Handler class. Handler classes must provide the following:
+### Writing Your Own Handler
+
+Generally, custom behaviour in your flow is achieved by defining your own handler class. Handler classes must:
 
 1. Inherit from `Aws::Lex::Conversation::Handler::Base`.
 2. Define a `will_respond?(conversation)` method that returns a boolean value.
 3. Define a `response(conversation)` method to return final response to Lex. This method is called if `will_respond?` returns `true`.
 
-The handlers defined on an `Aws::Lex::Conversation` instance will be called one-by-one in the order defined.
+Handlers in the chain are invoked sequentially in the order defined.
 
-The first handler that returns `true` for the `will_respond?` method will provide the final Lex response action.
+The first handler in the chain that returns `true` for the `will_respond?` method will provide the final Lex response action.
 
-### Custom Handler Example
+Here's an example for the `ServeBreakfast` and `FallbackIntent` handlers above:
 
 ```ruby
-class SayHello < Aws::Lex::Conversation::Handler::Base
+class ServeBreakfast < Aws::Lex::Conversation::Handler::Base
   def will_respond?(conversation)
-    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].filled?                       # our expected slot value is set
+    conversation.intent_name == "ServeBreakfast" &&   
+    conversation.slots[:BreakfastFood].filled?                      
   end
 
   def response(conversation)
-    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.
-    #
-    # You can also specify raw values for the response:
-    #
-    # conversation.close(
-    #   fulfillment_state: 'Fulfilled',
-    #   messages: [{ content: "Hello, #{name}!", contentType: 'PlainText' }]
-    # )
-    #
+    food = conversation.slots[:BreakfastFood].value
+    emoji = food == "waffle" ? "🧇" : "🥓"
+
     conversation.close(
-      fulfillment_state: Aws::Lex::Conversation::Type::FulfillmentState.new('Fulfilled'),
+      fulfillment_state: "Fulfilled",
       messages: [
-        Aws::Lex::Conversation::Type::Message.new(
-          content: "Hello, #{name}!",
-          content_type: Aws::Lex::Conversation::Type::Message::ContentType.new('PlainText')
-        )
+        {
+          content: "Here's your #{emoji}!",
+          contentType: "PlainText"
+        }
+      ]
+    )
+  end
+end
+
+class FallbackIntent < Aws::Lex::Conversation::Handler::Base
+  def will_respond?(conversation)
+    conversation.intent_name == "FallbackIntent"
+  end
+
+  def response(conversation)
+    conversation.close(
+      fulfillment_state: 'Failed',
+      messages: [
+        {
+          content: "Sorry - I'm not sure what you said!",
+          contentType: "PlainText"
+        }
       ]
     )
   end
 end
 ```
 
-## Built-In Handlers
+### Built-In Handlers
 
-### `Aws::Lex::Conversation::Handler::Echo`
+#### `Aws::Lex::Conversation::Handler::Echo`
 
 This handler simply returns a close response with a message that matches the `inputTranscript` property of the input event.
 
@@ -140,7 +202,7 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Close' } ... }
 ```
 
-### `Aws::Lex::Conversation::Handler::Delegate`
+#### `Aws::Lex::Conversation::Handler::Delegate`
 
 This handler returns a `Delegate` response to the Lex bot (i.e. "do the next bot action").
 
@@ -163,7 +225,7 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Delegate' } }
 ```
 
-### `Aws::Lex::Conversation::Handler::SlotResolution`
+#### `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.
 
@@ -359,8 +421,6 @@ end
 
 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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/amaabca/aws-lex-conversation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/amaabca/aws-lex-conversation/blob/master/CODE_OF_CONDUCT.md).
@@ -371,4 +431,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Aws::Lex::Conversation project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/amaabca/aws-lex-conversation/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `Aws::Lex::Conversation` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/amaabca/aws-lex-conversation/blob/master/CODE_OF_CONDUCT.md).

data/aws-lex-conversation.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   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)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|data)/}) }
   end
 
   spec.bindir = 'exe'

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'base64'
+require 'forwardable'
 require 'json'
 require 'shrink/wrap'
 
@@ -36,11 +37,14 @@ require_relative 'type/slot_value'
 require_relative 'type/slot'
 require_relative 'type/context'
 require_relative 'type/intent'
+require_relative 'type/proposed_next_state'
 require_relative 'type/checkpoint'
 require_relative 'type/session_attributes'
 require_relative 'type/session_state'
 require_relative 'type/interpretation'
 require_relative 'type/bot'
+require_relative 'type/transcription/resolved_context'
+require_relative 'type/transcription'
 require_relative 'type/response_card/button'
 require_relative 'type/response_card'
 require_relative 'type/message/content_type'

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

@@ -120,13 +120,41 @@ module Aws
           self
         end
 
+        def proposed_next_state(opts = {})
+          data = {
+            dialogAction: lex_attributes(opts.fetch(:dialog_action)),
+            intent: lex_attributes(opts.fetch(:intent))
+          }
+          lex.proposed_next_state = Type::ProposedNextState.shrink_wrap(data)
+          self
+        end
+
         def session(data)
           lex.session_state.session_attributes.merge!(Type::SessionAttributes[data])
           self
         end
 
+        def transcription(opts = {})
+          data = {
+            transcription: opts.fetch(:transcription),
+            transcriptionConfidence: opts.fetch(:confidence, 1),
+            resolvedContext: {
+              intent: opts.fetch(:intent) { 'FallbackIntent' }
+            },
+            resolvedSlots: opts.fetch(:resolved_slots) { {} }
+          }
+          lex.transcriptions.push(Type::Transcription.shrink_wrap(data))
+          self
+        end
+
         private
 
+        def lex_attributes(instance)
+          return instance unless instance.respond_to?(:to_lex)
+
+          instance.to_lex
+        end
+
         def current_interpretation
           lex.interpretations.find { |i| i.intent.name == lex.session_state.intent.name }
         end

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

@@ -17,6 +17,8 @@ module Aws
           required :response_content_type
           required :session_id
           required :session_state
+          required :transcriptions, default: -> { [] }
+          optional :proposed_next_state
 
           computed_property(:current_intent, virtual: true) do |instance|
             instance.session_state.intent.tap do |intent|
@@ -41,9 +43,11 @@ module Aws
             input_mode: InputMode,
             interpretations: Array[Interpretation],
             invocation_source: InvocationSource,
+            proposed_next_state: ProposedNextState,
             request_attributes: symbolize_hash!,
             response_content_type: Message::ContentType,
-            session_state: SessionState
+            session_state: SessionState,
+            transcriptions: Array[Transcription]
           )
         end
       end

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

@@ -15,6 +15,11 @@ module Aws
             content_type: Message::ContentType,
             image_response_card: Aws::Lex::Conversation::Type::ResponseCard
           )
+
+          def initialize(opts = {})
+            assign_attributes!(opts)
+            self.content_type ||= ContentType.new('PlainText')
+          end
         end
       end
     end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class ProposedNextState
+          include Base
+
+          required :dialog_action
+          required :intent
+
+          coerce(
+            dialog_action: DialogAction,
+            intent: Intent
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/type/transcription/resolved_context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class Transcription
+          class ResolvedContext
+            include Base
+
+            required :intent
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Type
+        class Transcription
+          include Base
+
+          required :transcription
+          required :transcription_confidence
+          optional :resolved_context
+          optional :resolved_slots
+          alias_method :confidence, :transcription_confidence
+
+          coerce(
+            resolved_context: Transcription::ResolvedContext,
+            resolved_slots: Array[Slot]
+          )
+        end
+      end
+    end
+  end
+end

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

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

data/lib/aws/lex/conversation.rb

@@ -5,10 +5,13 @@ require_relative 'conversation/base'
 module Aws
   module Lex
     class Conversation
+      extend Forwardable
       include Support::Mixins::Responses
 
       attr_accessor :event, :context, :lex
 
+      def_delegators :@lex, :proposed_next_state, :transcriptions
+
       def initialize(opts = {})
         self.event = opts.fetch(:event)
         self.context = opts.fetch(:context)
@@ -142,6 +145,10 @@ module Aws
         lex.session_state.active_contexts = []
       end
 
+      def proposed_next_state?
+        !proposed_next_state.nil?
+      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.3.0
+  version: 6.4.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-22 00:00:00.000000000 Z
+date: 2022-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrink_wrap
@@ -92,6 +92,7 @@ files:
 - lib/aws/lex/conversation/type/invocation_source.rb
 - lib/aws/lex/conversation/type/message.rb
 - lib/aws/lex/conversation/type/message/content_type.rb
+- lib/aws/lex/conversation/type/proposed_next_state.rb
 - lib/aws/lex/conversation/type/response.rb
 - lib/aws/lex/conversation/type/response_card.rb
 - lib/aws/lex/conversation/type/response_card/button.rb
@@ -105,6 +106,8 @@ files:
 - 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
+- lib/aws/lex/conversation/type/transcription.rb
+- lib/aws/lex/conversation/type/transcription/resolved_context.rb
 - lib/aws/lex/conversation/version.rb
 homepage: https://github.com/amaabca/aws-lex-conversation
 licenses: