RecastAI 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb697ada3b68765c4aaa58a74aecb84b4abd6ce1
-  data.tar.gz: aea0d30db62c6f16036f5bfb05d4192fabb79586
+  metadata.gz: c0cfad488e50151e132f8abb790be62c97652ded
+  data.tar.gz: 79e4585edf1ad61f8d140a536bdf1f9e8fda883e
 SHA512:
-  metadata.gz: 4c8345542618e865f9fe864661f68ffc1e0b5ba482cc7bc367ae50c2d055fc1c2c85dcf2ed04de031c46574d0de1b6f5adee8c489797a5a991183c91db4a6a0a
-  data.tar.gz: 39b7610d272e106875fa4feb59b25db4db1e802d461e2adb8e3a871ba0fe5d55744220fe798caf22fb01bcbdc1f335a1bed5318bc79fdaeae6b62581a89088b3
+  metadata.gz: 534d1820d0711cf6cced848521a7fe2aee894f9c4e8b9b2fc8cc07aae1fbaeb25e525f1f00c51513ac328044425d712189bba66fedaa6f6708874cd9509a6bf4
+  data.tar.gz: e25c33badd056b347f23a5584492773f47d69ebc7e002c1af3758d403fb727c8179c9f075b21a568bcb4f3dfe527248721e4c7d0d288ad8f4805f59a28dd34fb

data/README.md

@@ -1,21 +1,16 @@
-# Recast.AI - Ruby SDK
+# Recast.AI - SDK Ruby
 
-[![Version](https://badge.fury.io/rb/RecastAI.svg)](https://badge.fury.io/rb/RecastAI)
+[logo]: https://github.com/RecastAI/SDK-Ruby/blob/master/misc/logo-inline.png "Recast.AI"
 
-![logo](https://raw.githubusercontent.com/RecastAI/SDK-ruby/master/misc/logo-inline.png "Recast.AI")
-
-Recast.AI official SDK in Ruby.
+![alt text][logo]
 
+Recast.AI official SDK in Ruby
 
 ## Synospis
 
-This gem is a pure Ruby interface to the [Recast.AI](https://recast.ai) API. It allows you to make requests to your bots.
-
-
-## Requirements
-
-* Ruby 2.2+
-
+This module is a wrapper around the [Recast.AI](https://recast.ai) API, and allows you to:
+* [build a bot](https://github.com/RecastAI/SDK-Ruby/wiki/Build-your-bot)
+* [analyze your text](https://github.com/RecastAI/SDK-Ruby/wiki/Analyse-text)
 
 ## Installation
 
@@ -23,236 +18,26 @@ This gem is a pure Ruby interface to the [Recast.AI](https://recast.ai) API. It
 gem install 'RecastAI'
 ```
 
-## Usage
-
-```ruby
-require 'recastai'
+## Documentation
 
-client = RecastAI::Client.new(YOUR_TOKEN, YOUR_LANGUAGE)
-
-# text request
-response = client.text_request(YOUR_TEXT)
-if response.intent.slug == YOUR_EXPECTED_INTENT
-  # Do your code...
-end
-```
+You can find the full documentation [here](https://github.com/RecastAI/SDK-Ruby/wiki).
 
 ## Specs
 
 ### Classes
 
-This gem contains 5 main classes, as follows:
-
-* RecastAI::Client is the client allowing you to make requests.
-* RecastAI::Response contains the response from [Recast.AI](https://recast.ai).
-* RecastAI::Intent represents an intent of the response.
-* RecastAI::Entity represents an entity found by Recast.AI in your user's input.
-* RecastAI::RecastError is the error thrown by the gem.
-
-Don't hesitate to dive into the code, it's commented :)
-
-## RecastAI::Client
-
-The Client can be instanciated with a token and a language (both optional)
-
-```ruby
-client = RecastAI::Client.new(YOUR_TOKEN, YOUR_LANGUAGE)
-```
-
-__Your tokens__
-
-[token]: https://github.com/RecastAI/SDK-NodeJs/blob/master/misc/recast-ai-tokens.png "Tokens"
-
-![alt text][token]
-
-*Copy paste your request access token from your bot's settings*
-
-__Your language__
-
-```ruby
-client = RecastAI::Client.new(YOUR_TOKEN, 'en')
-```
-
-*The language is a lowercase 639-1 isocode.*
-
-## Text Request
-
-text_request(text, options = {})
-
-If you pass a token or a language in the options parameter, it will override your default client language or token
-
-```ruby
-response = client.text_request(YOUR_TEXT)
-
-if response.intent == YOUR_EXPECTED_INTENT
-  # Do your code...
-end
-```
-
-```ruby
-# With optional parameters
-response = client.text_request(YOUR_TEXT, { token: YOUR_TOKEN, language: YOUR_LANGUAGE })
-```
-
-__If a language is provided:__ the language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used.
-
-__If no language is provided:__ the language of the text is detected and is used for processing if your bot has expressions for it, else your bot's primary language is used for processing.
-
-## File request
-
-file_request(file, options = {})
-
-If you pass a token or a language in the option parameter, it will override your default client language or token.
-
-__file format: .wav__
-```ruby
-response = client.file_request(File.new(File.join(File.dirname(__FILE__),YOUR_FILE)))
-
-if response.intent.slug == YOUR_EXPECTED_INTENT
-  # Do your code...
-end
-```
-
-```ruby
-# with optional parameters
-response = client.file_request(File.new(File.join(File.dirname(__FILE__),YOUR_FILE)), { token: YOUR_TOKEN, language: YOUR_LANGUAGE })
-```
-
-__If a language is provided:__ the language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used
-
-__If no language is provided:__ your bot's primary language is used for processing as we do not provide language detection for speech.
-
-
-## RecastAI::Response
-
-The Response is generated after a call to either file_request or text_request.
-
-### Get the first detected intent
-
-| Method        | Params | Return                    |
-| ------------- |:------:| :-------------------------|
-| intent()      |        | the first detected intent |
-
-```ruby
-response = client.text_request(YOUR_TEXT)
-
-if response.intent.slug == YOUR_EXPECTED_INTENT
-  # Do your code...
-end
-```
-
-### Get the first entity matching name
-
-| Method     | Params        | Return                   |
-| ---------- |:-------------:| :------------------------|
-| get(name)  | name: String  | the first Entity matched |
-
-```ruby
-response = client.text_request(YOUR_TEXT)
-
-location = response.get('location')
-```
-
-### Get all entities matching name
-
-| Method     | Params        | Return                   |
-| ---------- |:-------------:| :------------------------|
-| all(name)  | name: String  | all the Entities matched |
-
-```ruby
-response = client.text_request(YOUR_TEXT)
-
-locations = response.all('location')
-```
-
-
-
-### Act helpers
-
-| Method        | Params | Return                                                 |
-| ------------- |:------:| :----------------------------------------------------- |
-| assert?       |        | Bool: whether or not the sentence is an assertion      |
-| command?      |        | Bool: whether or not the sentence is a command         |
-| wh\_query?    |        | Bool: whether or not the sentence is a question        |
-| yn\_query?    |        | Bool: whether or not the sentence is a query           |
-
-### Type helpers
-
-| Method        | Params | Return                                                 |
-| ------------- |:------:| :----------------------------------------------------- |
-| abbreviation? |        | Bool: is the answer of the sentence an abbreviation?   |
-| entity?       |        | Bool: is the answer of the sentence an entity?         |
-| description?  |        | Bool: is the answer of the sentence an description?    |
-| human?        |        | Bool: is the answer of the sentence an human?          |
-| location?     |        | Bool: is the answer of the sentence a location?        |
-| number?       |        | Bool: is the answer of the sentence an number?         |
-
-### Sentiment helpers
-
-| Method        | Params | Return                                                 |
-| ------------- |:------:| :----------------------------------------------------- |
-| vpositive?    |        | Bool: is the sentence very positive?                   |
-| positive?     |        | Bool: is the sentence positive?                        |
-| neutral?      |        | Bool: is the sentence neutral?                         |
-| negative?     |        | Bool: is the sentence negative?                        |
-| vnegative?    |        | Bool: is the sentence very negative?                   |
-
-### Getters
-
-Each of the following methods corresponds to a Response attribute
-
-| Method        | Params | Return                                              |
-| ------------- |:------:| :---------------------------------------------------|
-| raw()         |        | String: the raw unparsed json response              |
-| uuid()        |        | String: the universal unique id of the request      |
-| source()      |        | String: the user input                              |
-| intents()     |        | Array[Intent]: all the matched intents              |
-| act()         |        | String: the act of the sentence                     |
-| type()        |        | String: the type of the sentence                    |
-| sentiment()   |        | String: the sentiment of the sentence               |
-| entities()    |        | Array[Entity]: all the detected entities            |
-| language()    |        | String: the language of the sentence                |
-| version()     |        | String: the version of the json                     |
-| timestamp()   |        | String: the timestamp at the end of the processing  |
-| status()      |        | String: the status of the response                  |
-
-## RecastAI::Intent
-
-Each of the following methods corresponds to an Intent attribute
-
-| Attributes  | Description                                                   |
-| ----------- |:--------------------------------------------------------------|
-| slug        | String: the slug of the intent                                |
-| confidence  | Float: the unparsed json value of the intent                  |
-
-## RecastAI::Entity
-
-Each of the following methods corresponds to an Entity attribute
-
-| Attributes  | Description                                                   |
-| ----------- |:--------------------------------------------------------------|
-| name        | String: the name of the entity                                |
-| raw         | String: the raw value extracted from the sentence             |
-| confidence  | Float: the detection score between 0 and 1 excluded           |
-
-In addition to those methods, more attributes are generated depending of the nature of the entity.
-The full list can be found there: [man.recast.ai](https://man.recast.ai/#list-of-entities)
-
-```ruby
-response = client.text_request(YOUR_TEXT)
-
-location = response.get('location')
-
-puts location.raw
-puts location.name
-```
-
-## RecastAI::RecastError
-
-The Recast.AI Error is thrown when receiving an non-200 response from Recast.AI.
+This module contains 7 classes, as follows:
 
-As it inherits from ::Exception, it implements the default exception methods.
+* [Client](https://github.com/RecastAI/SDK-Ruby/wiki/Class-Client) is the client allowing you to make requests.
+* [Response](https://github.com/RecastAI/SDK-Ruby/wiki/Class-Response) wraps the response from a call to [Recast.AI](https://recast.ai) API with the text_request or file_request Client methods. 
+* [Conversation](https://github.com/RecastAI/SDK-Ruby/wiki/Class-Conversation) wraps the response from a call to [Recast.AI](https://recast.ai) API with the text_converse Client method.
+* [Action](https://github.com/RecastAI/SDK-Ruby/wiki/Class-Action) represents an action to do when using the text_converse method.
+* [Intent](https://github.com/RecastAI/SDK-Ruby/wiki/Class-Intent) represents an intent matched when using either the text_request, file_request or text_converse methods.
+* [Entity](https://github.com/RecastAI/SDK-Ruby/wiki/Class-Entity) represents an entity extracted from an input.
+* [RecastError](https://github.com/RecastAI/SDK-Ruby/wiki/Class-RecastError) is the error returned by the module.
 
+Don't hesitate to dive into the code, it's commented ;)
+`
 ## More
 
 You can view the whole API reference at [man.recast.ai](https://man.recast.ai).

data/lib/recastai.rb

@@ -10,5 +10,7 @@ require 'recastai/utils'
 require 'recastai/errors'
 require 'recastai/client'
 require 'recastai/response'
+require 'recastai/conversation'
+require 'recastai/action'
 require 'recastai/intent'
 require 'recastai/entity'

data/lib/recastai/action.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+##
+# This class builds an action used by RecastAI:::Conversation
+module RecastAI
+  class Action
+    attr_reader :slug
+    attr_reader :done
+    attr_reader :reply
+
+    def initialize(action)
+      @slug  = action['slug']
+      @done  = action['done']
+      @reply = action['reply']
+    end
+
+    def done?
+      @done
+    end
+  end
+end

data/lib/recastai/client.rb

@@ -1,14 +1,50 @@
 # encoding: utf-8
 
+##
+# This class is the main entrypoint to Recast.AI
+# When using *_converse, a RecastAI::Conversation object is returned
+# When using *_request, a RecastAI::Response object is returned
 module RecastAI
   class Client
     attr_accessor :token
+    attr_accessor :language
 
     def initialize(token = nil, language = nil)
       @token = token
       @language = language
     end
 
+    ##
+    # Perform a text converse to Recast.AI
+    #
+    # * *Args* :
+    #   - +text+ - String, the text to process
+    #   - +options+ - Hash, request's options
+    # * *Returns* :
+    #   - An instance of Conversation
+    # * *Throws* :
+    #   - RecastError
+    def text_converse(text, options = {})
+      token = options[:token] || @token
+      raise(RecastError.new('Token is missing')) if token.nil?
+
+      language = options[:language] || @language
+
+      body = { text: text }
+      body[:language] = language unless language.nil?
+      body[:conversation_token] = options[:conversation_token] unless options[:conversation_token].nil?
+      body[:memory] = options[:memory] unless options[:memory].nil?
+
+      response = HTTParty.post(
+        Utils::CONVERSE_ENDPOINT,
+        body: body,
+        headers: { Authorization: "Token #{token}" }
+      )
+      raise(RecastError.new(response.message)) if response.code != 200
+
+      Conversation.new(response.body)
+    end
+
     ##
     # Perform a text request to Recast.AI
     #
@@ -25,12 +61,12 @@ module RecastAI
 
       language = options[:language] || @language
 
-      body = { 'text' => text }
-      body['language'] = language unless language.nil?
+      body = { text: text }
+      body[:language] = language unless language.nil?
       response = HTTParty.post(
-        Utils::API_ENDPOINT,
+        Utils::REQUEST_ENDPOINT,
         body: body,
-        headers: { 'Authorization' => "Token #{token}" }
+        headers: { Authorization: "Token #{token}" }
       )
       raise(RecastError.new(response.message)) if response.code != 200
 
@@ -53,12 +89,12 @@ module RecastAI
 
       language = options[:language] || @language
 
-      body = { 'voice' => File.new(file) }
-      body['language'] = language unless language.nil?
+      body = { voice: File.new(file) }
+      body[:language] = language unless language.nil?
       response = HTTMultiParty.post(
-        Utils::API_ENDPOINT,
+        Utils::REQUEST_ENDPOINT,
         body: body,
-        headers: { 'Authorization' => "Token #{token}" }
+        headers: { Authorization: "Token #{token}" }
       )
       raise(RecastError.new(response.message)) if response.code != 200
 

data/lib/recastai/conversation.rb

@@ -0,0 +1,182 @@
+# encoding: utf-8
+
+##
+# This class builds a conversation from *_converse
+module RecastAI
+  class Conversation
+    attr_reader :raw
+    attr_reader :uuid
+    attr_reader :source
+    attr_reader :replies
+    attr_reader :action
+    attr_reader :next_actions
+    attr_reader :memory
+    attr_reader :entities
+    attr_reader :intents
+    attr_reader :conversation_token
+    attr_reader :language
+    attr_reader :version
+    attr_reader :timestamp
+    attr_reader :status
+
+    def initialize(response)
+      @raw = response
+
+      response = JSON.parse(response)
+      response = response['results']
+
+      @uuid               = response['uuid']
+      @source             = response['source']
+      @replies            = response['replies']
+      @action             = Action.new(response['action'])
+      @next_actions       = response['next_actions'].map{ |i| Action.new(i) }
+      @memory             = response['memory'].select{ |n, e| !e.nil? }.map{ |n, e| Entity.new(n, e) }
+      @entities           = response['entities'].flat_map{ |n, e| e.map{ |ee| Entity.new(n, ee) } }
+      @intents            = response['intents'].map{ |i| Intent.new(i) }
+      @conversation_token = response['conversation_token']
+      @language           = response['language']
+      @version            = response['version']
+      @timestamp          = response['timestamp']
+      @status             = response['status']
+    end
+
+    ##
+    # Returns the first reply provided there is one
+    #
+    # * *Args* :
+    # * *Returns* :
+    #   - A String or nil
+    def reply
+      @replies.any? ? @replies.first : nil
+    end
+
+    ##
+    # Returns the first next action provided there is one
+    #
+    # * *Args* :
+    # * *Returns* :
+    #   - An instance of Action or nil
+    def next_action
+      @next_actions.any? ? @next_actions.first : nil
+    end
+
+    ##
+    # Returns the replies joined with sep
+    #
+    # * *Args* :
+    #   - +sep+ - String, the separator (default: ' ')
+    # * *Returns* :
+    #   - A String or nil
+    def joined_replies(sep=' ')
+      @replies.join(sep)
+    end
+
+    ##
+    # Returns the first entity in the memory name matches the parameter
+    # If no name is provided, returns the full memory
+    #
+    # * *Args* :
+    #   - +key+ - String, the memory's field name
+    # * *Returns* :
+    #   - An instance of Entity or a Memory
+    def get_memory(key=nil)
+      return @memory if key.nil?
+
+      @memory.each do |entity|
+        return entity if entity.name.casecmp(key.to_s) == 0
+      end
+
+      nil
+    end
+
+    ##
+    # Returns the first intent provided there is one
+    #
+    # * *Args* :
+    # * *Returns* :
+    #   - A String or nil
+    def intent
+      @intents.any? ? @intents.first : nil
+    end
+
+    class << self
+      ##
+      # Merges the conversation memory with the one given
+      #
+      # * *Args* :
+      #   - +token+ - String, your request_token
+      #   - +conversation_token+ String, the token of the conversation whose memory will be updated
+      #   - +memory+ Hash, the memory you want to update with
+      # * *Returns* :
+      #   - An updated Memory
+      # * *Throws* :
+      #   - RecastError
+      def set_memory(token, conversation_token, memory)
+        body = { conversation_token: conversation_token, memory: memory }
+        response = HTTParty.put(
+          Utils::CONVERSE_ENDPOINT,
+          body: body,
+          headers: { Authorization: "Token #{token}" }
+        )
+        raise(RecastError.new(response.message)) if response.code != 200
+
+        response = JSON.parse(response.body)
+        response = response['results']
+        response['memory'].select{ |n, e| !e.nil? }.map{ |n, e| Entity.new(n, e) }
+      end
+
+      ##
+      # Reset the conversation memory fully or partially with the one given
+      #
+      # * *Args* :
+      #   - +token+ - String, your request_token
+      #   - +conversation_token+ String, the token of the conversation whose memory will be updated
+      #   - +memory+ Hash, the memory you want to update with
+      # * *Returns* :
+      #   - A fully or partially reset Memory
+      # * *Throws* :
+      #   - RecastError
+      def reset_memory(token, conversation_token, name=nil)
+        body = { conversation_token: conversation_token }
+        unless name.nil?
+          body[:memory] = { name => nil }
+        end
+        response = HTTParty.put(
+          Utils::CONVERSE_ENDPOINT,
+          body: body,
+          headers: { Authorization: "Token #{token}" }
+        )
+        raise(RecastError.new(response.message)) if response.code != 200
+
+        response = JSON.parse(response.body)
+        response = response['results']
+        response['memory'].select{ |n, e| !e.nil? }.map{ |n, e| Entity.new(n, e) }
+      end
+
+      ##
+      # Resets the conversation state by setting every memory field to nil,
+      # all actions to not done, and the last action to nil
+      #
+      # * *Args* :
+      #   - +token+ - String, your request_token
+      #   - +conversation_token+ - String, the token of the conversation to reset
+      # * *Returns* :
+      #   - A fully reset Memory
+      # * *Throws* :
+      #   - RecastError
+      def reset_conversation(token, conversation_token)
+        body = { conversation_token: conversation_token }
+        response = HTTParty.delete(
+          Utils::CONVERSE_ENDPOINT,
+          body: body,
+          headers: { Authorization: "Token #{token}" }
+        )
+        raise(RecastError.new(response.message)) if response.code != 200
+
+        response = JSON.parse(response.body)
+        response = response['results']
+        response['memory'].select{ |n, e| !e.nil? }.map{ |n, e| Entity.new(n, e) }
+      end
+    end
+  end
+end

data/lib/recastai/entity.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 
+##
+# This class build an Entity used in RecastAI::Response and RecastAI::Conversation
 module RecastAI
   class Entity
     attr_reader :name

data/lib/recastai/intent.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 
+##
+# This class builds an intent from RecastAI::Request and RecastAI::Conversation
 module RecastAI
   class Intent
     attr_reader :slug

data/lib/recastai/response.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 
+##
+# This class builds a response from *_request
 module RecastAI
   class Response
     attr_reader :raw

data/lib/recastai/utils.rb

@@ -4,13 +4,13 @@ module RecastAI
   class Utils
     # Versioning
     MAJOR = '2'.freeze
-    MINOR = '0'.freeze
+    MINOR = '1'.freeze
     MICRO = '0'.freeze
     VERSION = "#{MAJOR}.#{MINOR}.#{MICRO}".freeze
 
     # Endpoints
-    API_ENDPOINT = 'https://api.recast.ai/v2/request'.freeze
-    WS_ENDPOINT = 'wss://api.recast.ai/v2/request'.freeze
+    REQUEST_ENDPOINT = 'https://api.recast.ai/v2/request'.freeze
+    CONVERSE_ENDPOINT = 'https://api.recast.ai/v2/converse'.freeze
 
     # Act constants
     ACT_ASSERT = 'assert'.freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: RecastAI
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Paul Renvoisé
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-03 00:00:00.000000000 Z
+date: 2016-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -113,7 +113,9 @@ files:
 - bin/file
 - bin/text
 - lib/recastai.rb
+- lib/recastai/action.rb
 - lib/recastai/client.rb
+- lib/recastai/conversation.rb
 - lib/recastai/entity.rb
 - lib/recastai/errors.rb
 - lib/recastai/intent.rb