adhearsion-asr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c04b1a33ab083f07c27fcb249b183b1261fd24ff
+  data.tar.gz: 30b74b8f7774084d0ba658b207330ba6070ea19e
+SHA512:
+  metadata.gz: 812e7c4fceaed9eccf44d9443ad42341b9f4c7bcc7b7b7a35b21e68813c316b7427de465fe01a42dbbc98474853bf0c9ef65e502a21c526e62b0a1d7c77cb3e9
+  data.tar.gz: ca1aff66a38dc817b8929ed2229323736aedcb86c2d32778e8ed7832b0d5fb4baf31b2bb2a74a92b288df40d77dca35a77f9b04af9580aec5cde016648e7b6f6

data/.gitignore

@@ -0,0 +1,21 @@
+# Gem related stuff
+*.gem
+/pkg
+/.bundle
+/Gemfile.lock
+/vendor
+
+# RBX stuff
+/.rbx/
+
+# Editor temp/backup files
+*~
+.*.sw?
+
+# General
+/nbproject
+.DS_Store
+/.rvmrc
+/.yardoc
+/doc
+/tmp

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--colour
+--tty

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - jruby-19mode
+  - rbx-19mode
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: jruby-19mode
+notifications:
+  irc: "irc.freenode.org#adhearsion"

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# [develop](https://github.com/adhearsion/adhearsion-asr)
+
+# [v0.1.0](https://github.com/adhearsion/adhearsion-asr/compare/6216ddb0a8b8c0ac5d1731ec154fe6d6abfea692...0.1.0) - [2013-05-07](https://rubygems.org/gems/adhearsion-asr/versions/0.1.0)
+  * Feature: #ask and #menu from Adhearsion core
+    * Mostly API compatible, with some very minor differences
+    * Use Rayo Prompt component
+    * Support for arbitrary grammars (ASR) in #ask

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'adhearsion', github: 'adhearsion', branch: 'feature/rayo_prompt'
+gem 'punchblock', github: 'adhearsion/punchblock', branch: 'feature/new_rayo'

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :cli => '--format documentation' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (C) 2013 Adhearsion Foundation Inc
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# adhearsion-asr
+
+Adds speech recognition support to Adhearsion as a plugin. Overrides `CallController#ask` and `#menu` to pass all recognition responsibility to the recognizer instead of invoking it multiple times.
+
+## Features
+
+* #ask API from Adhearsion core supporting digit limits, terminators, timeouts, inline grammars and grammar references
+* #menu API from Adhearsion core supporting DTMF input and recognition failure
+
+## Install
+
+Add the following entries to your Adhearsion application's Gemfile:
+
+```ruby
+gem 'adhearsion-asr'
+gem 'adhearsion', github: 'adhearsion', branch: 'feature/rayo_prompt'
+gem 'punchblock', github: 'adhearsion/punchblock', branch: 'feature/new_rayo'
+```
+
+The dependencies on Adhearsion and Punchblock from git are temporary and are required because this plugin uses functionality that is unreleased in those gems (mostly changes to keep up to date with the Rayo specification; they will be released once the Rayo specification has been advanced to Draft by the XSF).
+
+Be sure to check out the plugin config by running `rake config:show` and adjust to your requirements.
+
+## Examples
+
+### Simple collection of 5 DTMF digits
+
+```ruby
+class MyController < Adhearsion::CallController
+  include AdhearsionASR::ControllerMethods
+
+  def run
+    result = ask limit: 5
+    case result.status
+    when :match
+      speak "You entered #{result.response}"
+    when :noinput
+      speak "Hellooo? Anyone there?"
+    when :nomatch
+      speak "That doesn't make sense."
+    end
+  end
+end
+```
+
+### Collecting an arbitrary number of digits until '#' is received:
+
+```ruby
+class MyController < Adhearsion::CallController
+  include AdhearsionASR::ControllerMethods
+
+  def run
+    result = ask terminator: '#'
+    case result.status
+    when :match
+      speak "You entered #{result.response}"
+    when :noinput
+      speak "Hellooo? Anyone there?"
+    when :nomatch
+      speak "That doesn't make sense."
+    end
+  end
+end
+```
+
+### Collecting input from an inline speech grammar
+
+```ruby
+class MyController < Adhearsion::CallController
+  include AdhearsionASR::ControllerMethods
+
+  def run
+    grammar = RubySpeech::GRXML.draw root: 'main', language: 'en-us', mode: :voice do
+      rule id: 'main', scope: 'public' do
+        one_of do
+          item { 'yes' }
+          item { 'no' }
+        end
+      end
+    end
+
+    result = ask grammar: grammar, input_options: { mode: :speech }
+    case result.status
+    when :match
+      speak "You said #{result.response}"
+    when :noinput
+      speak "Hellooo? Anyone there?"
+    when :nomatch
+      speak "That doesn't make sense."
+    end
+  end
+end
+```
+
+### Collecting input from a speech grammar by URL
+
+```ruby
+class MyController < Adhearsion::CallController
+  include AdhearsionASR::ControllerMethods
+
+  def run
+    result = ask grammar_url: 'http://example.com/mygrammar.grxml', input_options: { mode: :speech }
+    case result.status
+    when :match
+      speak "You said #{result.response}"
+    when :noinput
+      speak "Hellooo? Anyone there?"
+    when :nomatch
+      speak "That doesn't make sense."
+    end
+  end
+end
+```
+
+### Executing a DTMF menu
+
+```ruby
+class MyController < Adhearsion::CallController
+  def run
+    answer
+    menu "Where can we take you today?", timeout: 8.seconds, tries: 3 do
+      match 1, BooController
+      match '2', MyOtherController
+      match(3, 4) { pass YetAnotherController }
+      match 5, FooController
+      match 6..10 do |dialed|
+        say_dialed dialed
+      end
+
+      timeout { do_this_on_timeout }
+
+      invalid do
+        invoke InvalidController
+      end
+
+      failure do
+        speak 'Goodbye'
+        hangup
+      end
+    end
+
+    speak "This code gets executed unless #pass is used"
+  end
+
+  def say_dialed(dialed)
+    speak "#{dialed} was dialed"
+  end
+
+  def do_this_on_timeout
+    speak 'Timeout'
+  end
+end
+```
+
+Check out the [API documentation](http://rdoc.info/gems/adhearsion-asr/frames) for more details.
+
+## Links:
+* [Source](https://github.com/adhearsion/adhearsion-asr)
+* [Documentation](http://rdoc.info/gems/adhearsion-asr/frames)
+* [Bug Tracker](https://github.com/adhearsion/adhearsion-asr/issues)
+
+## Author
+
+[Ben Langfeld](https://github.com/benlangfeld)
+
+### Contributions
+
+Adhearsion has a set of [contribution guidelines](https://github.com/adhearsion/adhearsion/wiki/Contributing) which help to smooth the contribution process.
+
+### Copyright
+
+Copyright (c) 2013 Adhearsion Foundation Inc. MIT LICENSE (see LICENSE for details).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new :spec
+
+task default: :spec

data/adhearsion_asr.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "adhearsion-asr/version"
+
+Gem::Specification.new do |s|
+  s.name        = "adhearsion-asr"
+  s.version     = AdhearsionASR::VERSION
+  s.authors     = ["Ben Langfeld"]
+  s.email       = ["ben@langfeld.me"]
+  s.homepage    = "https://github.com/adhearsion/adhearsion-asr"
+  s.summary     = %q{Adds speech recognition support to Adhearsion as a plugin}
+  s.description = %q{Adds speech recognition support to Adhearsion as a plugin}
+
+  s.rubyforge_project = "adhearsion-asr"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency %q<adhearsion>, ["~> 2.1"]
+  s.add_runtime_dependency %q<ruby_speech>, ["~> 2.1"]
+
+  s.add_development_dependency %q<bundler>, ["~> 1.0"]
+  s.add_development_dependency %q<rspec>, ["~> 2.5"]
+  s.add_development_dependency %q<rake>, [">= 0"]
+  s.add_development_dependency %q<guard-rspec>
+  s.add_development_dependency %q<rb-fsevent>, ['~> 0.9']
+ end

data/lib/adhearsion-asr/ask_grammar_builder.rb

@@ -0,0 +1,38 @@
+module AdhearsionASR
+  class AskGrammarBuilder
+    def initialize(options)
+      @options = options
+    end
+
+    def grammars
+      @grammars ||= build_grammars
+    end
+
+    private
+
+    def build_grammars
+      grammars = []
+
+      grammars.concat [@options[:grammar]].flatten.compact.map { |val| {value: val} } if @options[:grammar]
+      grammars.concat [@options[:grammar_url]].flatten.compact.map { |val| {url: val} } if @options[:grammar_url]
+
+      if grammars.empty?
+        limit = @options[:limit]
+        grammar = RubySpeech::GRXML.draw mode: :dtmf, root: 'digits' do
+          rule id: 'digits', scope: 'public' do
+            item repeat: "0-#{limit}" do
+              one_of do
+                0.upto(9) { |d| item { d.to_s } }
+                item { "#" }
+                item { "*" }
+              end
+            end
+          end
+        end
+        grammars << {value: grammar}
+      end
+
+      grammars
+    end
+  end
+end

data/lib/adhearsion-asr/controller_methods.rb

@@ -0,0 +1,112 @@
+require 'adhearsion-asr/ask_grammar_builder'
+require 'adhearsion-asr/prompt_builder'
+require 'adhearsion-asr/menu_builder'
+
+module AdhearsionASR
+  module ControllerMethods
+
+    #
+    # Prompts for input, handling playback of prompts, DTMF grammar construction, and execution
+    #
+    # @example A basic DTMF digit collection:
+    #   ask "Welcome, ", "/opt/sounds/menu-prompt.mp3",
+    #       timeout: 10, terminator: '#', limit: 3
+    #
+    # The first arguments will be a list of sounds to play, as accepted by #play, including strings for TTS, Date and Time objects, and file paths.
+    # :timeout, :terminator and :limit options may be specified to automatically construct a grammar, or grammars may be manually specified.
+    #
+    # @param [Object, Array<Object>] args A list of outputs to play, as accepted by #play
+    # @param [Hash] options Options to modify the grammar
+    # @option options [Boolean] :interruptible If the prompt should be interruptible or not. Defaults to true
+    # @option options [Integer] :limit Digit limit (causes collection to cease after a specified number of digits have been collected)
+    # @option options [Integer] :timeout Timeout in seconds before the first and between each input digit
+    # @option options [String] :terminator Digit to terminate input
+    # @option options [RubySpeech::GRXML::Grammar, Array<RubySpeech::GRXML::Grammar>] :grammar One of a collection of grammars to execute
+    # @option options [String, Array<String>] :grammar_url One of a collection of URLs for grammars to execute
+    # @option options [Hash] :input_options A hash of options passed directly to the Punchblock Input constructor
+    # @option options [Hash] :output_options A hash of options passed directly to the Punchblock Output constructor
+    #
+    # @return [Result] a result object from which the details of the response may be established
+    #
+    # @see Output#play
+    # @see Punchblock::Component::Input.new
+    # @see Punchblock::Component::Output.new
+    #
+    def ask(*args)
+      options = args.last.kind_of?(Hash) ? args.pop : {}
+      prompts = args.flatten
+
+      options[:grammar] || options[:grammar_url] || options[:limit] || options[:terminator] || raise(ArgumentError, "You must specify at least one of limit, terminator or grammar")
+
+      output_document = output_formatter.ssml_for_collection(prompts)
+      grammars = AskGrammarBuilder.new(options).grammars
+
+      PromptBuilder.new(output_document, grammars, options).execute self
+    end
+
+    # Creates and manages a multiple choice menu driven by DTMF, handling playback of prompts,
+    # invalid input, retries and timeouts, and final failures.
+    #
+    # @example A complete example of the method is as follows:
+    #   menu "Welcome, ", "/opt/sounds/menu-prompt.mp3", tries: 2, timeout: 10 do
+    #     match 1, OperatorController
+    #
+    #     match 10..19 do
+    #       pass DirectController
+    #     end
+    #
+    #     match 5, 6, 9 do |exten|
+    #       play "The #{exten} extension is currently not active"
+    #     end
+    #
+    #     match '7', OfficeController
+    #
+    #     invalid { play "Please choose a valid extension" }
+    #     timeout { play "Input timed out, try again." }
+    #     failure { pass OperatorController }
+    #   end
+    #
+    # The first arguments will be a list of sounds to play, as accepted by #play, including strings for TTS, Date and Time objects, and file paths.
+    # :tries and :timeout options respectively specify the number of tries before going into failure, and the timeout in seconds allowed on each digit input.
+    # The most important part is the following block, which specifies how the menu will be constructed and handled.
+    #
+    # #match handles connecting an input pattern to a payload.
+    # The pattern can be one or more of: an integer, a Range, a string, an Array of the possible single types.
+    # Input is matched against patterns, and the first exact match has it's payload executed.
+    # Matched input is passed in to the associated block, or to the controller through #options.
+    #
+    # Allowed payloads are the name of a controller class, in which case it is executed through its #run method, or a block, which is executed in the context of the current controller.
+    #
+    # #invalid has its associated block executed when the input does not possibly match any pattern.
+    # #timeout's block is run when timeout expires before receiving any input
+    # #failure runs its block when the maximum number of tries is reached without an input match.
+    #
+    # Execution of the current context resumes after #menu finishes. If you wish to jump to an entirely different controller, use #pass.
+    # Menu will return :failed if failure was reached, or :done if a match was executed.
+    #
+    # @param [Object] args A list of outputs to play, as accepted by #play
+    # @param [Hash] options Options to use for the menu
+    # @option options [Integer] :tries Number of tries allowed before failure
+    # @option options [Integer] :timeout Timeout in seconds before the first and between each input digit
+    # @option options [Boolean] :interruptible If the prompt should be interruptible or not. Defaults to true
+    # @option options [Hash] :input_options A hash of options passed directly to the Punchblock Input constructor
+    # @option options [Hash] :output_options A hash of options passed directly to the Punchblock Output constructor
+    #
+    # @return [Result] a result object from which the details of the response may be established
+    #
+    # @see Output#play
+    # @see CallController#pass
+    #
+    def menu(*args, &block)
+      raise ArgumentError, "You must specify a block to build the menu" unless block
+      options = args.last.kind_of?(Hash) ? args.pop : {}
+      prompts = args.flatten
+
+      menu_builder = MenuBuilder.new(options, &block)
+
+      output_document = output_formatter.ssml_for_collection(prompts)
+
+      menu_builder.execute output_document, self
+    end
+  end
+end

data/lib/adhearsion-asr/menu_builder.rb

@@ -0,0 +1,122 @@
+require 'adhearsion-asr/prompt_builder'
+
+module AdhearsionASR
+  class MenuBuilder
+    def initialize(options, &block)
+      @options = options
+      @matchers = []
+      @callbacks = {}
+      build(&block)
+    end
+
+    def match(*args, &block)
+      payload = block || args.pop
+
+      @matchers << Matcher.new(payload, args)
+    end
+
+    def invalid(&block)
+      register_user_supplied_callback :nomatch, &block
+    end
+
+    def timeout(&block)
+      register_user_supplied_callback :noinput, &block
+    end
+
+    def failure(&block)
+      register_user_supplied_callback :failure, &block
+    end
+
+    def execute(output_document, controller)
+      catch :match do
+        (@options[:tries] || 1).times do
+          result = PromptBuilder.new(output_document, grammars, @options).execute(controller)
+          process_result result
+        end
+        execute_hook :failure
+      end
+    end
+
+    private
+
+    def grammars
+      @grammar ||= [{value: build_grammar}]
+    end
+
+    def process_result(result)
+      if result.status == :match
+        handle_match result
+      else
+        execute_hook result.status
+      end
+    end
+
+    def register_user_supplied_callback(name, &block)
+      @callbacks[name] = block
+    end
+
+    def execute_hook(hook_name)
+      callback = @callbacks[hook_name]
+      return unless callback
+      @context.instance_exec(&callback)
+    end
+
+    def handle_match(result)
+      match = @matchers[result.interpretation.to_i]
+      match.dispatch @context, result.response
+      throw :match
+    end
+
+    def build(&block)
+      @context = eval "self", block.binding
+      instance_eval(&block)
+    end
+
+    def build_grammar
+      raise ArgumentError, "You must specify one or more matches." if @matchers.count < 1
+      matchers = @matchers
+
+      RubySpeech::GRXML.draw mode: :dtmf, root: 'options', tag_format: 'semantics/1.0-literals' do
+        rule id: 'options', scope: 'public' do
+          item do
+            one_of do
+              matchers.each_with_index do |matcher, index|
+                item do
+                  tag { index.to_s }
+                  matcher.apply_to_grammar self
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    Matcher = Struct.new(:payload, :keys) do
+      def dispatch(controller, response)
+        if payload.is_a?(Proc)
+          controller.instance_exec response, &payload
+        else
+          controller.invoke payload, extension: response
+        end
+      end
+
+      def apply_to_grammar(grammar)
+        possible_options = calculate_possible_options
+        if possible_options.count > 1
+          grammar.one_of do
+            possible_options.each do |key|
+              item { key.to_s }
+            end
+          end
+        else
+          keys.first.to_s
+        end
+      end
+
+      def calculate_possible_options
+        keys.map { |key| key.respond_to?(:to_a) ? key.to_a : key }.flatten
+      end
+    end
+  end
+end

data/lib/adhearsion-asr/plugin.rb

@@ -0,0 +1,11 @@
+module AdhearsionASR
+  class Plugin < Adhearsion::Plugin
+    config :adhearsion_asr do
+      min_confidence 0.5, desc: 'The default minimum confidence level used for all recognizer invocations.', transform: Proc.new { |v| v.to_f }
+      timeout 5, desc: 'The default timeout (in seconds) used for all recognizer invocations.', transform: Proc.new { |v| v.to_i }
+      recognizer nil, desc: 'The default recognizer used for all input. Set nil to use platform default.'
+      input_language 'en-US', desc: 'The default language set on generated grammars. Set nil to use platform default.'
+      renderer nil, desc: 'The default renderer used for all output. Set nil to use platform default.'
+    end
+  end
+end

data/lib/adhearsion-asr/prompt_builder.rb

@@ -0,0 +1,54 @@
+require 'adhearsion-asr/result'
+
+module AdhearsionASR
+  class PromptBuilder
+    def initialize(output_document, grammars, options)
+      output_options = {
+        render_document: {value: output_document},
+        renderer: Plugin.config.renderer
+      }.merge(options[:output_options] || {})
+
+      input_options = {
+        mode: :dtmf,
+        initial_timeout: (options[:timeout] || Plugin.config.timeout) * 1000,
+        inter_digit_timeout: (options[:timeout] || Plugin.config.timeout) * 1000,
+        max_silence: (options[:timeout] || Plugin.config.timeout) * 1000,
+        min_confidence: Plugin.config.min_confidence,
+        grammars: grammars,
+        recognizer: Plugin.config.recognizer,
+        language: Plugin.config.input_language,
+        terminator: options[:terminator]
+      }.merge(options[:input_options] || {})
+
+      @prompt = Punchblock::Component::Prompt.new output_options, input_options, barge_in: options.has_key?(:interruptible) ? options[:interruptible] : true
+    end
+
+    def execute(controller)
+      controller.execute_component_and_await_completion @prompt
+
+      result @prompt.complete_event.reason
+    end
+
+    private
+
+    def result(reason)
+      Result.new.tap do |result|
+        case reason
+        when proc { |r| r.respond_to? :nlsml }
+          result.status         = :match
+          result.confidence     = reason.confidence
+          result.response       = reason.utterance
+          result.interpretation = reason.interpretation
+          result.nlsml          = reason.nlsml
+        when Punchblock::Event::Complete::Error
+          raise Error, reason.details
+        when Punchblock::Event::Complete::Reason
+          result.status = reason.name
+        else
+          raise "Unknown completion reason received: #{reason}"
+        end
+        logger.debug "Ask completed with result #{result.inspect}"
+      end
+    end
+  end
+end

data/lib/adhearsion-asr/result.rb

@@ -0,0 +1,11 @@
+module AdhearsionASR
+  Result = Struct.new(:status, :confidence, :response, :interpretation, :nlsml) do
+    def to_s
+      response
+    end
+
+    def inspect
+      "#<#{self.class} status=#{status.inspect}, confidence=#{confidence.inspect}, response=#{response.inspect}, interpretation=#{interpretation.inspect}, nlsml=#{nlsml.inspect}>"
+    end
+  end
+end

data/lib/adhearsion-asr/version.rb

@@ -0,0 +1,3 @@
+module AdhearsionASR
+  VERSION = "0.1.0"
+end

data/lib/adhearsion-asr.rb

@@ -0,0 +1,7 @@
+module AdhearsionASR
+  Error = Class.new Adhearsion::Error
+end
+
+require "adhearsion-asr/version"
+require "adhearsion-asr/plugin"
+require "adhearsion-asr/controller_methods"