RecastAI 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8fc4edaf1b82d336f4b13e82dd68b45bacc60bd
-  data.tar.gz: 031d2d8409dc6abd4679cfa69b9c92199205bead
+  metadata.gz: b8ad1ab3c3644a475ee1ef6cb9d2fc1ff9cc2576
+  data.tar.gz: b8aa64148bc4fa52e834baa5f7e0a1519f198459
 SHA512:
-  metadata.gz: 97f198079573ac33474efdc4bdfd4d0c287d30eca3d1f861ce598811bc89ea3bd86793debcf7ef63271841c854505659a7f38932accd01ae94a512abec5b4086
-  data.tar.gz: e26c419f1c4762c9fc446494ba7f9407ea1f769ce784bed6827c3ce2b534430e8312c29448c8132c2ca83d5636e62807ce9f843531336ec9c2bf15ce060ebb31
+  metadata.gz: 8fbb4fba5c6df33976ba39903ec228e33c152e333879ef17a9b72e646d4d85bfaf543b3de1b4842c01fd03390e15cff0734a5eb565eeef676b9d6061ff67ae1a
+  data.tar.gz: 86ef258e86abcebf37bc945d3cc3cf58a634416e3eab53e12bc68ce1b5919b6f1eaa9e706a51337ed35a37e94f8f4e941142509e0664a904f8b5430869ebece3

data/README.md

@@ -1,4 +1,4 @@
-# RecastAI - Ruby SDK
+# Recast.AI - Ruby SDK
 
 [![Version](https://badge.fury.io/rb/RecastAI.svg)](https://badge.fury.io/rb/RecastAI)
 
@@ -19,63 +19,26 @@ This gem is a pure Ruby interface to the [Recast.AI](https://recast.ai) API. It
 
 ## Installation
 
-### Via Gemfile
-
-From [rubygems.org](https://rubygems.org/):
-
-```bash
-gem 'RecastAI'
-```
-
-From [github.com](https://github.com/):
-
-```bash
-gem 'RecastAI', github: 'RecastAI/SDK-ruby'
-```
-
-### Via Terminal
-
-From [rubygems.org](https://rubygems.org/):
-
 ```bash
 gem install 'RecastAI'
 ```
 
-From [github.com](https://github.com/):
-
-```bash
-git clone https://github.com/RecastAI/SDK-ruby
-gem build recastai.gemspec
-gem install RecastAI-*.gem
-```
-
-
 ## Usage
 
-### Gem
-
 ```ruby
 require 'recastai'
 
 client = RecastAI::Client.new(YOUR_TOKEN, YOUR_LANGUAGE)
-response = client.text_request(YOUR_TEXT)
-#response = client.file_request(File.new(File.join(File.dirname(__FILE__), YOUR_FILE)))
 
-if response.intent == YOUR_EXPECTED_INTENT
-  # Do your code...
-end
-```
-
-### CLI
+# text request
+responseFromText = client.text_request(YOUR_TEXT)
 
-```bash
-./bin/text YOUR_TOKEN YOUR_TEXT
-# => Recast.AI's response
-```
+# file request
+responseFromFile = client.file_request(File.new(File.join(File.dirname(__FILE__), YOUR_FILE)))
 
-```bash
-./bin/file YOUR_TOKEN YOUR_VOICE_FILE
-# => Recast.AI's response
+if responseFromText.intent == YOUR_EXPECTED_INTENT
+  # Do your code...
+end
 ```
 
 ## Specs
@@ -92,139 +55,215 @@ This gem contains 5 main classes, as follows:
 
 Don't hesitate to dive into the code, it's commented ;)
 
-### RecastAI::Client
+## RecastAI::Client
 
-The Recast.AI Client can be instanciated with a token (optional) and a language (optional) and provides the two following methods:
+The Client can be instanciated with a token and a language (both optional)
 
-* text_request(text, options = {}) *Performs a text request*
-* file_request(file, options = {}) *Performs a voice file request*
+```ruby
+client = RecastAI::Client.new(YOUR_TOKEN, YOUR_LANGUAGE)
+```
 
-On each call to `text_request` or `file_request` your can override either your token or your language by passing a hash of options.
+__Your tokens__
 
-If no language is provided in the request, Recast.AI does the following:
+[token]: https://github.com/RecastAI/SDK-NodeJs/blob/master/misc/recast-ai-tokens.png "Tokens"
 
-* text_request: 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.
-* voice_request: your bot's primary language is used for processing as we do not provide language detection for speech.
+![alt text][token]
 
-If a language is provided, Recast.AI does the following:
+*Copy paste your request access token from your bot's settings*
 
-* text_request: the language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used.
-* voice_request: the language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used
+__Your language__
 
-*Accepted options are :token, :language, to override the defaults provided at initialization*
+```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
-require 'recastai'
+response = client.text_request(YOUR_TEXT)
 
-client = RecastAI::Client.new(YOUR_TOKEN, YOUR LANGUAGE)
+if response.intent == YOUR_EXPECTED_INTENT
+  # Do your code...
+end
+```
 
-# Performs a text request on Recast.AI
+```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 == YOUR_EXPECTED_INTENT
   # Do your code...
 end
+```
 
-# Performs a voice file request on Recast.AI
+```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 == YOUR_EXPECTED_INTENT
   # Do your code...
 end
 ```
 
-### RecastAI::Response
-
-The Recast.AI Response is generated after a call with the two previous methods and contains the following methods:
+### Get the first sentence
 
-* raw(\*) *Returns the raw unparsed response*
-* source(\*) *Returns the source sentence Recast.AI processed*
-* intents(\*) *Returns all the matched intents*
-* intent(\*) *Returns the first matched intent*
-* sentences(\*) *Returns all the detected sentences*
-* sentence(\*) *Returns the first detected sentence*
-* get(name) *Returns the first entity matching -name-*
-* all(name) *Returns all the entities matching -name-*
-* entities(\*) *Returns all the entities*
-* version(\*) *Returns the version of the JSON*
-* timestamp(\*) *Returns the timestamp at the end of the processing*
-* status(\*) *Returns the status of the response*
+| Method          | Params | Return             |
+| --------------- |:------:| :------------------|
+| sentence()      |        | the first sentence |
 
 ```ruby
-response = client.text_request('Give me some recipes with potatoes. And cheese.')
+response = client.text_request(YOUR_TEXT)
 
-# Get the first sentence, aka 'Give me some recipes with potatoes'
 first_sentence = response.sentence
+```
 
-# If the first intent matched 'recipe'...
-if response.intent == 'recipe'
-  # ...get all the entities matching 'ingredient'
-  ingredients = response.all('ingredient')
+### Get the first entity matching name
 
-  puts "The request has been filled at #{response.timestamp}"
-end
+| Method     | Params        | Return                   |
+| ---------- |:-------------:| :------------------------|
+| get(name)  | name: String  | the first Entity matched |
+
+```ruby
+response = client.text_request(YOUR_TEXT)
+
+location = response.get('location')
 ```
 
-### RecastAI::Sentence
+### Get all entities matching name
+
+| Method     | Params        | Return                   |
+| ---------- |:-------------:| :------------------------|
+| all(name)  | name: String  | all the Entities matched |
 
-The Recast.AI Sentence is generated by the Recast.AI Response initializer and provides the following methods:
+```ruby
+response = client.text_request(YOUR_TEXT)
 
-* source(\*) *Returns the source of the sentence*
-* type(\*) *Returns the type of the sentence*
-* action(\*) *Returns the action of the sentence*
-* agent(\*) *Returns the agent of the sentence*
-* polarity(\*) *Returns the polarity (negation or not) of the sentence*
-* get(name) *Returns the first entity matching -name-*
-* all(name) *Returns all the entities matching -name-*
-* entities(\*) *Returns all the entities detected in the sentence*
+locations = response.all('location')
+```
+
+### Getters
+
+Each of the following methods corresponds to a Response attribute
+
+| Method        | Params | Return                                              |
+| ------------- |:------:| :---------------------------------------------------|
+| raw()         |        | String: the raw unparsed json response              |
+| source()      |        | String: the user input                              |
+| intents()     |        | Array[object]: all the matched intents              |
+| sentences()   |        | Array[Sentence]: all the detected sentences         |
+| version()     |        | String: the version of the json                     |
+| timestamp()   |        | String: the timestamp at the end of the processing  |
+| status()      |        | String: the status of the response                  |
+| type()        |        | String: the type of the response                    |
+
+
+## RecastAI::Sentence
+
+The Sentence is generated by the Recast.AI Response initializer
+
+### Get the first entity matching name
+
+| Method     | Params        | Return                   |
+| ---------- |:-------------:| :------------------------|
+| get(name)  | name: String  | the first Entity matched |
 
 ```ruby
-response = client.text_request('Tell me a joke.')
-# Get the first sentence
+response = client.text_request(YOUR_TEXT)
+
 sentence = response.sentence
 
-if sentence.action == 'tell' && sentence.polarity == 'positive'
-  # Tell a joke...
-end
+location = sentence.get('location')
 ```
 
-### RecastAI::Entity
+### Get all entities matching name
 
-The Recast.AI Entity is generated by the Recast.AI Sentence initializer and provides the following method:
+| Method     | Params        | Return                   |
+| ---------- |:-------------:| :------------------------|
+| all(name)  | name: String  | all the Entities matched |
 
-* name(\*) *Returns the name of the entity*
-* raw(\*) *Returns the raw text on which the entity was detected*
+```ruby
+response = client.text_request(YOUR_TEXT)
 
-In addition to this method, more attributes are generated depending of the nature of the entity, which can be one of the following:
+sentence = response.sentence
 
-* hex(\*)
-* value(\*)
-* deg(\*)
-* formated(\*)
-* lng(\*)
-* lat(\*)
-* unit(\*)
-* code(\*)
-* person(\*)
-* number(\*)
-* gender(\*)
-* next(\*)
-* grain(\*)
-* order(\*)
+locations = sentence.all('location')
+```
 
-```ruby
-response = client.text_request('What can I cook with salmon ?')
+### Getters
 
-if response.intent == 'recipe'
-  # Get the ingredient
-  ingredient = response.get('ingredient')
+Each of the following methods corresponds to a Response attribute
 
-  puts "You asked me for a recipe with #{ingredient.value}"
-end
+| Method      | Params | Return                                               |
+| ----------- |:------:| :----------------------------------------------------|
+| source      |        | String: the source of the sentence                   |
+| type        |        | String: the type of the sentence                     |
+| action      |        | String: The action of the sentence                   |
+| agent       |        | String: the agent of the sentence                    |
+| polarity    |        | String: the polarity of the sentence                 |
+| entities    |        | Array[Entity]: the entities detected in the sentence |
+
+## RecastAI::Entity
+
+Each of the following methods corresponds to a Response attribute
+
+| Attributes  | Description                                                   |
+| ----------- |:--------------------------------------------------------------|
+| name        | String: the name of the entity                                |
+| raw         | String: the unparsed json value of the entity                 |
+
+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
+## RecastAI::RecastError
 
 The Recast.AI Error is thrown when receiving an non-200 response from Recast.AI.
 

data/lib/recastai.rb

@@ -10,5 +10,3 @@ require 'recastai/client'
 require 'recastai/response'
 require 'recastai/sentence'
 require 'recastai/entity'
-
-require 'awesome_print'

data/lib/recastai/utils.rb

@@ -3,7 +3,7 @@ module RecastAI
     # Versioning
     MAJOR   = '1'.freeze
     MINOR   = '1'.freeze
-    MICRO   = '0'.freeze
+    MICRO   = '1'.freeze
     VERSION = "#{MAJOR}.#{MINOR}.#{MICRO}".freeze
 
     # Endpoints

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: RecastAI
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Paul Renvoisé
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-16 00:00:00.000000000 Z
+date: 2016-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -121,6 +121,7 @@ files:
 - lib/recastai/utils.rb
 - misc/.gitkeep
 - misc/logo-inline.png
+- misc/recast-ai-tokens.png
 - recastai.gemspec
 homepage: https://github.com/RecastAI/SDK-ruby
 licenses: