google_assistant 0.0.6 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ec771654a969d6e004c2da5c88350943facf8f4
-  data.tar.gz: 08c5f4e0f7c3440ad6d05a7ba3e5859cbbdad37c
+  metadata.gz: dfd97fdfaea944f3be60796786ec4f2d9e43f8cc
+  data.tar.gz: a1d07df44788b57d8e4c7bf81cde7506cf41d1be
 SHA512:
-  metadata.gz: 5ac7fab096ea512ea289a5cfde7004d064dfa9cb8e7843fcc0dd76bbb87a2c1b5f6ae8465d1b5bd2081e5c42334a74c2fb72bd4c09ccda5d1f09256af196f309
-  data.tar.gz: e016e2b76126a8f283f5b1b05887ffc9d74fc5173cb2e5b3fb7b849e0aeb61a73e14a59b1fd066295bca1baaf1f870bb4e735951522cca024ad0a3bb12641248
+  metadata.gz: b048a4da4c4e612b38b676a0622bcda406dc1e5f2b31e94a8f0ed042432285662dee80c49c633df24d3272e5fa88eb426bc4f2111ef59441deedfd7f0e08d6f2
+  data.tar.gz: e3bab745f936fcee45e80936d3b45517542bc1b3f2f9deb1b5d03461b6577792ed73462ef6b4619f73a740e85f68ed311322fd31c07a4eea107bcd7441ddb907

data/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+*.gem

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+ruby "2.3.1"

data/Gemfile.lock

@@ -0,0 +1,14 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+
+RUBY VERSION
+   ruby 2.3.1p112
+
+BUNDLED WITH
+   1.13.6

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Aaron Milam
+
+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,215 @@
+# Google Assistant Ruby
+
+Write Google Assistant actions in Ruby.
+
+GoogleAssistant parses Google Assistant requests and provides the framework to respond appropriately. It works with the Google Assistant API v1.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```rb
+gem "google_assistant"
+```
+
+## Get started
+
+### Rails 4 and higher
+
+In your routes file, allow a `POST` request to your action. All requests from Google Assistant will come here.
+
+```rb
+Rails.application.routes.draw do
+  post "/google_assistant" => "google_assistant#conversation"
+end
+```
+
+Write your controller to handle the request. Use GoogleAssistant to respond to the requests.
+
+```rb
+class GoogleAssistantController < ApplicationController
+
+  def conversation
+    assistant_response = GoogleAssistant.respond_to(params, response) do |assistant|
+      assistant.intent.main do
+        assistant.ask(
+          prompt: "<speak>Hi there! Say something, please.</speak>",
+          no_input_prompt: [
+            "<speak>If you said something, I didn't hear you.</speak>",
+            "<speak>Did you say something?</speak>"
+          ]
+        )
+      end
+
+      assistant.intent.text do
+        assistant.tell("<speak>I can respond, too!</speak>")
+      end
+    end
+
+    render assistant_response
+  end
+end
+```
+
+## Usage
+
+GoogleAssistant parses the request from the Google Assistant API and helps you build your response. It takes the `params` and `response` objects in Rails and Sinatra.
+
+```rb
+assistant_response = GoogleAssistant.respond_to(params, response) do |assistant|
+  # Response logic goes here
+end
+```
+
+The Google Assistant API sends a request using the `MAIN` intent for the initial request from the user. This is when the user says "OK Google, talk to #{name_of_your_app}".
+
+```rb
+assistant_response = GoogleAssistant.respond_to(params, response) do |assistant|
+  assistant.intent.main do
+    # Initial request's response goes here. You may want to introduce the app here.
+  end
+end
+```
+
+The Google Assistant API sends a request using the `TEXT` intent for subsequent requests from the user. When your app asks for input from the user, the conversation continues. When the user finishes the conversation with "Goodbye" or your app finishes the conversation with a `tell` response, the conversation ends and any new conversations start again with the `MAIN` intent.
+
+```rb
+assistant_response = GoogleAssistant.respond_to(params, response) do |assistant|
+  assistant.intent.text do
+    # Respond to user input here.
+  end
+end
+```
+
+### Ask
+
+Request user input by sending an `ask` response. Send a prompt and a set of follow-up prompts for when the user fails to respond.
+
+```rb
+assistant.intent.main do
+  assistant.ask(
+    prompt: "<speak>Hi there! Say something, please.</speak>",    # The voice prompt the user will hear.
+    no_input_prompt: [
+      "<speak>If you said something, I didn't hear you.</speak>", # You can provide a number of "no input prompts". A random
+      "<speak>Did you say something?</speak>"                     # one will be spoken if the user takes too long to respond.
+    ]
+  )
+end
+```
+
+### Tell
+
+Send a final response, ending the conversation.
+
+```rb
+assistant.intent.text do
+  assistant.tell("<speak>Thanks for talking! Goodbye!</speak>")   # Both SSML and plain text work here and anywhere you send a prompt.
+end
+```
+
+### User input
+
+GoogleAssistant allows you to read the user's input using `assistant.arguments` so that you can respond appropriately.
+
+```rb
+assistant.intent.text do
+  case assistant.arguments[0].text_value.downcase
+  when "hello"
+    respond_with = "Hi there!"
+  when "goodbye"
+    respond_with = "See you later!"
+  else
+    respond_with "I heard you say #{assistant.arguments[0].text_value}, but I don't know what that means."
+  end
+
+  assistant.tell(respond_with)
+end
+```
+
+### Conversation state and data
+
+You can keep data on the Conversation object. This data will be sent to the Google Assistant API, which will return that data back when the user responds. This way, you can keep ongoing information about the conversation without having to use a database to store that information.
+
+You can also send a state value with your responses to keep track of where your conversation is at.
+
+```rb
+GoogleAssistant.respond_to(params, response) do |assistant|
+  assistant.intent.main do
+    assistant.conversation.state = "asking favorite color"
+
+    assistant.ask(
+      prompt: "What is your favorite color?",
+      no_input_prompt: ["What did you say your favorite color is?"]
+    )
+  end
+
+  assistant.intent.text do
+    if assistant.conversation.state == "asking favorite color"
+      assistant.conversation.data["favorite_color"] = assistant.arguments[0].text_value
+
+      assistant.conversation.state = "asking lucky number"
+
+      assistant.ask(
+        prompt: "What is your lucky number?",
+        no_input_prompt: ["What did you say your lucky number is?"]
+      )
+    elsif assistant.conversation.state == "asking lucky number"
+      favorite_color = assistant.conversation.data["favorite_color"]
+      lucky_number = assistant.arguments[0].text_value
+
+      assistant.tell("Your favorite color is #{favorite_color} and your lucky number is #{lucky_number}. Neat!")
+    end
+  end
+end
+```
+
+### SSML
+
+SSML is Google Assistant's markup language for text to speech. It provides options to pause, interpret dates and numbers, and more. You can provide SSML responses or plain text. See [Google's documentation on SSML](https://developers.google.com/actions/reference/ssml).
+
+### Testing your assistant
+
+You can use any hosting platform.
+
+1. [Download the `gactions` CLI](https://developers.google.com/actions/tools/gactions-cli) and add it to your PATH.
+    - Or if you'd rather not put it in your path, you'll simply need to call it by referencing its full path.
+2. Visit the [Google Cloud Console projects page](https://console.cloud.google.com/project). Create a project and make note of the project ID for configuration and deployment.
+3. Deploy your app to the web. Heroku is a good choice. See [Heroku's documentation](https://devcenter.heroku.com/articles/getting-started-with-ruby#introduction) for more info on how to do this.
+4. Add an `action.json` file at the root of your project.
+
+    ```json
+    {
+      "versionLabel": "1.0.0",
+      "agentInfo": {
+        "languageCode": "en-US",
+        "projectId": "your-google-project-id",
+        "voiceName": "male_1"
+      },
+      "actions": [
+        {
+          "initialTrigger": {
+            "intent": "assistant.intent.action.MAIN"
+          },
+          "httpExecution": {
+            "url": "https://yourapp.domain.com/path-to-your-assistant"
+          }
+        }
+      ]
+    }
+    ```
+
+5. Run the following command from the root directory of your project. The `invocation_name` is what you will use to activate your assistant. For example, "OK Google, talk to my action". Name it something unique.
+
+    ```
+    gactions preview -action_package=action.json -invocation_name="my action"
+    ```
+
+    - `gactions` will ask to access your account and Google developer project. Follow the onscreen instructions to do so.
+
+6. Use the [web simulator](https://developers.google.com/actions/tools/web-simulator) to simulate. Or better yet, if your Google Home device is logged into the same account you're using to build your action, you can say "OK Google, talk to my action" to test it out directly on your device.
+
+## More information
+
+Check out Google's instructions at https://developers.google.com/actions/develop/sdk/getting-started for more detail on writing and testing a Google Assistant action.
+
+Check out https://github.com/armilam/google_assistant_example for a simple example of this gem in action.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+desc "Run tests"
+task default: :test

data/google_assistant.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "google_assistant/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "google_assistant"
+  spec.version       = GoogleAssistant::VERSION
+  spec.authors       = ["Aaron Milam"]
+  spec.email         = ["armilam@gmail.com"]
+
+  spec.summary       = "Ruby SDK for the Google Assistant API"
+  spec.description   = "This SDK provides the framework for creating Google Assistant actions in Ruby. It works in Ruby on Rails and Sinatra (and probably others)."
+  spec.homepage      = "https://github.com/armilam/google-assistant-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 12.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/google_assistant.rb

@@ -2,148 +2,9 @@
 
 Dir["#{File.dirname(__FILE__)}/google_assistant/**/*.rb"].each { |file| require file }
 
-class GoogleAssistant
-  attr_reader :params
-  attr_reader :response
+module GoogleAssistant
 
-  def initialize(params, response)
-    @params = params
-    @response = response
-  end
-
-  def respond_to(&block)
-    yield(self)
-
-    response.headers["Google-Assistant-API-Version"] = "v1"
-
-    intent.call
-  end
-
-  def intent
-    @_intent ||= Intent.new(intent_string)
-  end
-
-  def arguments
-    @_arguments ||= inputs[0]["arguments"].map do |argument|
-      Argument.new(argument)
-    end
-  end
-
-  def conversation
-    @_conversation ||= Conversation.new(conversation_params)
-  end
-
-  def tell(message)
-    final_response = { speech_response: {} }
-
-    if is_ssml(message)
-      final_response[:speech_response][:ssml] = message
-    else
-      final_response[:speech_response][:text_to_speech] = message
-    end
-
-    build_response(nil, false, nil, final_response)
-  end
-
-  def ask(input_prompt)
-    if input_prompt.nil?
-      return handle_error("Invalid input prompt")
-    end
-
-    if input_prompt.is_a?(String)
-      input_prompt = build_input_prompt(is_ssml(input_prompt), input_prompt)
-    end
-
-    expected_intent = build_expected_intent(StandardIntents::TEXT)
-
-    expected_inputs = [{
-      input_prompt: input_prompt,
-      possible_intents: [expected_intent]
-    }]
-
-    build_response(
-      conversation.dialog_state,
-      true,
-      expected_inputs,
-      nil
-    )
-  end
-
-  def build_input_prompt(is_ssml, initial_prompt, no_inputs = [])
-    if is_ssml
-      initial_prompts = [
-        { ssml: initial_prompt }
-      ]
-
-      no_input_prompts = no_inputs.map do |no_input_prompt|
-        { ssml: no_input_prompt }
-      end
-
-      {
-        initial_prompts: initial_prompts,
-        no_input_prompts: no_input_prompts
-      }
-    else
-      initial_prompts = [
-        { text_to_speech: initial_prompt }
-      ]
-
-      no_input_prompts = no_inputs.map do |no_input_prompt|
-        { text_to_speech: no_input_prompt }
-      end
-
-      {
-        initial_prompts: initial_prompts,
-        no_input_prompts: no_input_prompts
-      }
-    end
-  end
-
-  private
-
-  def build_response(dialog_state, expect_user_response, expected_input, final_response)
-    response = {}
-
-    response[:conversation_token] = dialog_state.to_json if dialog_state
-    response[:expect_user_response] = expect_user_response
-    response[:expected_inputs] = expected_input if expected_input
-    response[:final_response] = final_response if !expect_user_response && final_response
-
-    {
-      json: response
-    }
-  end
-
-  def build_expected_intent(intent)
-    if intent.nil? || intent == ""
-      return handle_error("Invalid intent")
-    end
-
-    { intent: intent }
-  end
-
-  def is_ssml(text)
-    if text.nil?
-      handle_error("Missing text")
-      return false
-    end
-
-    text =~ /^<speak\b[^>]*>(.*?)<\/speak>$/
-  end
-
-  def inputs
-    params["inputs"] || handle_error("Missing inputs from request body")
-  end
-
-  def intent_string
-    inputs[0]["intent"] || handle_error("Missing intent from request body")
-  end
-
-  def conversation_params
-    params["conversation"] || {}
-  end
-
-  def handle_error(message)
-    raise message
+  def self.respond_to(params, response, &block)
+    Assistant.new(params, response).respond_to(&block)
   end
 end

data/lib/google_assistant/argument.rb

@@ -1,10 +1,10 @@
-class GoogleAssistant
+module GoogleAssistant
   class Argument
     attr_reader :name, :raw_text, :text_value
 
     def initialize(opts)
       @name = opts["name"]
-      @raw_text = opts ["raw_text"]
+      @raw_text = opts["raw_text"]
       @text_value = opts["text_value"]
     end
   end

data/lib/google_assistant/assistant.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GoogleAssistant
+  class Assistant
+    InvalidIntent = Class.new(StandardError)
+    InvalidMessage = Class.new(StandardError)
+    InvalidInputPrompt = Class.new(StandardError)
+    MissingRequestInputs = Class.new(StandardError)
+    MissingRequestIntent = Class.new(StandardError)
+
+    attr_reader :params, :response
+
+    def initialize(params, response)
+      @params = params
+      @response = response
+    end
+
+    def respond_to(&block)
+      yield(self)
+
+      response.headers["Google-Assistant-API-Version"] = "v1"
+
+      intent.call
+    end
+
+    def intent
+      @_intent ||= Intent.new(intent_string)
+    end
+
+    def arguments
+      @_arguments ||= inputs[0]["arguments"].map do |argument|
+        Argument.new(argument)
+      end
+    end
+
+    def conversation
+      @_conversation ||= Conversation.new(conversation_params)
+    end
+
+    def tell(message)
+      raise InvalidMessage if message.nil? || message.empty?
+
+      final_response = { speech_response: {} }
+
+      if is_ssml?(message)
+        final_response[:speech_response][:ssml] = message
+      else
+        final_response[:speech_response][:text_to_speech] = message
+      end
+
+      build_response(nil, false, nil, final_response)
+    end
+
+    def ask(prompt:, no_input_prompt: [])
+      raise InvalidInputPrompt if prompt.nil? || prompt.empty?
+
+      no_input_prompt = [*no_input_prompt].compact
+
+      prompt = build_input_prompt(prompt, no_input_prompt)
+
+      expected_intent = build_expected_intent(StandardIntents::TEXT)
+
+      expected_inputs = [{
+        input_prompt: prompt,
+        possible_intents: [expected_intent]
+      }]
+
+      build_response(
+        conversation.dialog_state,
+        true,
+        expected_inputs,
+        nil
+      )
+    end
+
+    private
+
+    def build_input_prompt(initial_prompt, no_inputs = [])
+      initial_prompts = [
+        { prompt_type(initial_prompt) => initial_prompt }
+      ]
+
+      no_input_prompts = no_inputs.map do |prompt|
+        { prompt_type(prompt) => prompt }
+      end
+
+      {
+        initial_prompts: initial_prompts,
+        no_input_prompts: no_input_prompts
+      }
+    end
+
+    def build_response(dialog_state, expect_user_response, expected_input, final_response)
+      response = {}
+
+      response[:conversation_token] = dialog_state.to_json if dialog_state
+      response[:expect_user_response] = expect_user_response
+      response[:expected_inputs] = expected_input if expected_input
+      response[:final_response] = final_response if !expect_user_response && final_response
+
+      response
+    end
+
+    def build_expected_intent(intent)
+      raise InvalidIntent if intent.nil? || intent.empty?
+
+      { intent: intent }
+    end
+
+    def is_ssml?(text)
+      text =~ /^<speak\b[^>]*>(.*?)<\/speak>$/
+    end
+
+    def prompt_type(text)
+      is_ssml?(text) ? :ssml : :text_to_speech
+    end
+
+    def inputs
+      raise MissingRequestInputs if params["inputs"].nil?
+      params["inputs"]
+    end
+
+    def intent_string
+      raise MissingRequestIntent if inputs[0]["intent"].nil?
+      inputs[0]["intent"]
+    end
+
+    def conversation_params
+      params["conversation"] || {}
+    end
+  end
+end

data/lib/google_assistant/conversation.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class GoogleAssistant
+module GoogleAssistant
   class Conversation
     class Type
       TYPE_UNSPECIFIED = 0

data/lib/google_assistant/dialog_state.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GoogleAssistant
+  class DialogState
+    DEFAULT_STATE = { "state" => nil, "data" => {} }.freeze
+
+    def initialize(state_hash_or_conversation_token = nil)
+      if state_hash_or_conversation_token.is_a?(String)
+        @raw_token = state_hash_or_conversation_token
+        @state_hash = parse_token(state_hash_or_conversation_token)
+      elsif state_hash_or_conversation_token.is_a?(Hash)
+        @state_hash = state_hash_or_conversation_token
+      else
+        @state_hash = DEFAULT_STATE.dup
+      end
+    end
+
+    def state
+      state_hash["state"]
+    end
+
+    def state=(state)
+      state_hash["state"] = state
+    end
+
+    def data
+      state_hash["data"]
+    end
+
+    def data=(data)
+      raise "DialogState data must be a hash" unless data.is_a?(Hash)
+
+      state_hash["data"] = data
+    end
+
+    def to_json
+      state_hash.to_json
+    end
+
+    private
+
+    attr_reader :state_hash, :raw_token
+
+    def parse_token(token)
+      JSON.parse(token)
+    rescue JSON::ParserError, TypeError
+      DEFAULT_STATE.dup
+    end
+  end
+end

data/lib/google_assistant/intent.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class GoogleAssistant
+module GoogleAssistant
   class StandardIntents
 
     # Assistant fires MAIN intent for queries like [talk to $action].

data/lib/google_assistant/version.rb

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

metadata

@@ -1,25 +1,81 @@
 --- !ruby/object:Gem::Specification
 name: google_assistant
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors:
 - Aaron Milam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-26 00:00:00.000000000 Z
-dependencies: []
-description: Ruby SDK for the Google Assistant API
-email: armilam@gmail.com
+date: 2017-01-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: This SDK provides the framework for creating Google Assistant actions
+  in Ruby. It works in Ruby on Rails and Sinatra (and probably others).
+email:
+- armilam@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".editorconfig"
+- ".gitignore"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- google_assistant.gemspec
 - lib/google_assistant.rb
 - lib/google_assistant/argument.rb
+- lib/google_assistant/assistant.rb
 - lib/google_assistant/conversation.rb
+- lib/google_assistant/dialog_state.rb
 - lib/google_assistant/intent.rb
+- lib/google_assistant/version.rb
 homepage: https://github.com/armilam/google-assistant-ruby
 licenses:
 - MIT