alexa_generator 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95714b270aa9dfa94bdaf3804000a38200a89003
-  data.tar.gz: ab78ce1ab42d021cffee7eb1351da3476d66c164
+  metadata.gz: 4805b19d31381011f755d8270dc535a64bb75879
+  data.tar.gz: c0360ca35a27e1c95432681ba41c670c361e3606
 SHA512:
-  metadata.gz: b057be5889006152bafea85083c142bdf89bfa2ab2ff59731843620828653973e25178993acab399349691d40f0569506a5fa6962ce44149b9fb90c528224ed9
-  data.tar.gz: 489d2b018e6605b7ad7d64e06b8f5af47f10ea45691394cb40348b0e1be36a7d3db9e3ba6b254b982f30761a0d043962bf10b8e8680ccf8ebe001326728881e2
+  metadata.gz: 3a760ba8c02c4f78922b4e42e4f93b6795c5f4b7a0d506b6ac67231df366194b1ba0320f4dd17e6089ff13dd58994ed089aee42f9834013acb6f66683c35b67a
+  data.tar.gz: b50e3df34f7742573f1c2c49cacbe96aa96a54f358d56dc4098ae8991f0d6284ad389bfcb347fad5e88c61aa43038e2286153b1b2221384200fae7bb37c301eb

data/README.md

@@ -1,2 +1,109 @@
 # alexa_generator
-Rubygem to generate voice interface components for Amazon's Alexa API
+Rubygem to generate the [interaction model](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/alexa-skills-kit-interaction-model-reference) for Amazon's Alexa API.
+
+## Installing
+
+alexa_generator is available on [Rubygems](https://rubygems.org). You can install it with:
+
+```
+$ gem install alexa_generator
+```
+
+You can also add it to your Gemfile:
+
+```
+gem 'alexa_generator'
+```
+
+## What's this?
+
+To register a skill with Amazon's Alexa API, one must create an *intent schema* and a list of *sample utterances*. I found this process to be really tedious, and wanted an easier and more maintainable way to define interaction models.
+
+## Example usage
+
+Here's an example of building the intent schema used in [Amazon's example](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/alexa-skills-kit-interaction-model-reference):
+
+```ruby
+model = AlexaGenerator::InteractionModel.build do |model|
+  model.add_intent(:GetHoroscope) do |intent|
+    intent.add_slot(:Sign, AlexaGenerator::Slot::SlotType::LITERAL) do |slot|
+      slot.add_bindings(*%w{Aries Taurus Gemini Cancer Leo Virgo Libra Scorpio Sagittarius Capricorn Aquarius Pisces})
+    end
+    
+    intent.add_slot(:Date, AlexaGenerator::Slot::SlotType::DATE) do |slot|
+      slot.add_bindings('today', 'next Thursday', 'tomorrow')
+    end
+    
+    intent.add_utterance_template('what is the horoscope for {Sign}')
+    intent.add_utterance_template('what will the horoscope for {Sign} be {Date}')
+  end
+end
+```
+
+### Intent schema
+
+One can then get the intent schema:
+
+```ruby
+model.intent_schema
+# => {:intents=>[{:intent=>:GetHoroscope, :slots=>[{:name=>:Sign, :type=>:LITERAL}, {:name=>:Date, :type=>:DATE}]}]}
+```
+
+Amazon expects JSON as input, so you might want to convert:
+
+```ruby
+require 'json'
+JSON.pretty_generate(model.intent_schema)
+# => {
+# =>   "intents": [
+# =>     {
+# =>       "intent": "GetHoroscope",
+# =>       "slots": [
+# =>         {
+# =>           "name": "Sign",
+# =>           "type": "LITERAL"
+# =>         },
+# =>         {
+# =>           "name": "Date",
+# =>           "type": "DATE"
+# =>         }
+# =>       ]
+# =>     }
+# =>   ]
+# => }
+```
+
+### Sample utterances
+
+`alexa_generator` generates all possible combinations of slot bindings and applies them to the provided sample utterance templates. In the above example:
+
+```ruby
+model.sample_utterances(:GetHoroscope)
+```
+
+will output the following (clipped for the sake of brevity):
+
+```
+GetHoroscope what is the horoscope for {Aquarius|Sign}
+GetHoroscope what is the horoscope for {Aries|Sign}
+GetHoroscope what is the horoscope for {Cancer|Sign}
+GetHoroscope what is the horoscope for {Capricorn|Sign}
+GetHoroscope what is the horoscope for {Gemini|Sign}
+GetHoroscope what is the horoscope for {Leo|Sign}
+GetHoroscope what is the horoscope for {Libra|Sign}
+GetHoroscope what is the horoscope for {Pisces|Sign}
+GetHoroscope what is the horoscope for {Sagittarius|Sign}
+GetHoroscope what is the horoscope for {Scorpio|Sign}
+GetHoroscope what is the horoscope for {Taurus|Sign}
+GetHoroscope what is the horoscope for {Virgo|Sign}
+GetHoroscope what will the horoscope for {Aquarius|Sign} be {next Thursday|Date}
+GetHoroscope what will the horoscope for {Aquarius|Sign} be {today|Date}
+GetHoroscope what will the horoscope for {Aquarius|Sign} be {tomorrow|Date}
+[... clipped ...]
+GetHoroscope what will the horoscope for {Taurus|Sign} be {next Thursday|Date}
+GetHoroscope what will the horoscope for {Taurus|Sign} be {today|Date}
+GetHoroscope what will the horoscope for {Taurus|Sign} be {tomorrow|Date}
+GetHoroscope what will the horoscope for {Virgo|Sign} be {next Thursday|Date}
+GetHoroscope what will the horoscope for {Virgo|Sign} be {today|Date}
+GetHoroscope what will the horoscope for {Virgo|Sign} be {tomorrow|Date}
+```

data/lib/alexa_generator/alexa_syntax_error.rb

@@ -0,0 +1,4 @@
+module AlexaGenerator
+  class AlexaSyntaxError < StandardError
+  end
+end

data/lib/alexa_generator/interaction_model.rb

@@ -28,6 +28,16 @@ module AlexaGenerator
     end
 
     def initialize(intents, utterance_templates, slot_bindings)
+      # Validate that utterance templates reference only defined slots
+      all_referenced_slots = utterance_templates.map(&:referenced_slots).flatten
+      slot_names = Set.new(slot_bindings.map(&:slot_name))
+      undefined_slots = all_referenced_slots.reject { |x| slot_names.include?(x) }
+
+      if undefined_slots.any?
+        raise AlexaSyntaxError,
+              "The following slots referenced in utterances are undefined: #{undefined_slots.join ','}"
+      end
+
       @intents = Hash[ intents.map {|x| [x.name, x]} ]
 
       @utterance_templates = utterance_templates.group_by { |x| x.intent_name }

data/lib/alexa_generator/slot.rb

@@ -22,7 +22,7 @@ module AlexaGenerator
       end
 
       def add_bindings(*values)
-        values.map { |v| @bindings.push(v) }
+        @bindings.concat(values)
       end
 
       def create

data/lib/alexa_generator/version.rb

@@ -1,3 +1,3 @@
 module AlexaGenerator
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

data/lib/alexa_generator.rb

@@ -1,2 +1,3 @@
 require 'alexa_generator/interaction_model'
+require 'alexa_generator/alexa_syntax_error'
 require 'alexa_generator/version'

data/spec/alexa_generator/interaction_model_spec.rb

@@ -2,6 +2,18 @@ require 'spec_helper'
 require 'json'
 
 describe AlexaGenerator::InteractionModel do
+  context 'invalid slot bindings' do
+    it 'should throw an exception' do
+      expect {
+        AlexaGenerator::InteractionModel.build do |iface|
+          iface.add_intent(:Intent) do |intent|
+            intent.add_utterance_template('{UndefinedSlot}')
+          end
+        end
+      }.to raise_error(AlexaGenerator::AlexaSyntaxError)
+    end
+  end
+
   context 'builder' do
     it 'should build a valid voice interface' do
       iface = AlexaGenerator::InteractionModel.build do |iface|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alexa_generator
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Christopher Mullins
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-06 00:00:00.000000000 Z
+date: 2015-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -51,6 +51,7 @@ files:
 - Rakefile
 - alexa_generator.gemspec
 - lib/alexa_generator.rb
+- lib/alexa_generator/alexa_syntax_error.rb
 - lib/alexa_generator/intent.rb
 - lib/alexa_generator/intent_schema.rb
 - lib/alexa_generator/interaction_model.rb