api_ai_wrapper 1.0.0 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 469724d657925c38ac67bf0c138f213735ed032a
-  data.tar.gz: ccc0bd55f2401a5a57766bb53fd030076a528b52
+  metadata.gz: bad5503f39dd701eed3c4dfd90d830632a37fd2c
+  data.tar.gz: 5f847be711f203214eef3ea1340011bb7f2233ec
 SHA512:
-  metadata.gz: 3b58704d1d01e1e063e562d349d6dd2379256d52f192c5298616ff0f6a98bb2ca5644beff1fc184abc3bab00ac28c67acd4064f93de4b9c0969f8135fce5891f
-  data.tar.gz: a941104c2cb448f049048fe366877863efff846252b3523b62a06b4c9e28e8f085b924872dddaabfe7d603f8781153f44cae6c356a72286d192477ff0c6e9771
+  metadata.gz: 59f828697c158ca608501b3901d39784e9a6fb86874ec5e8a464e0983490b629c037257ab29faee484d3879c28868a20adfbceefb725dab2663c1876c44bb0ec
+  data.tar.gz: 5507caece3003dc208f206be234c7390360985718507e8f7fbac02b4533f772601c0165e0ac17f7944d61b0590ef17047f1c0d992daf8cfe32680762d7e1f5ac

data/Gemfile.lock

@@ -1,3 +1,9 @@
+PATH
+  remote: .
+  specs:
+    api_ai_wrapper (1.0.3)
+      httpclient (~> 2.8, >= 2.8.0)
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -39,6 +45,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  api_ai_wrapper!
   httpclient
   rspec
   simplecov

data/README.md

@@ -1,2 +1,140 @@
-# api_ai_wrapper
+# The API.AI ruby wrapper
 A simple library that let's any developer automate the training process of a Natural Language Processing Engine on API.AI, and retrieve meaning from new utterances.
+
+# To install
+Directly from a bash console
+
+```ruby
+gem install api_ai_wrapper
+```
+
+Or in your Gemfile
+```ruby
+gem "api_ai_wrapper"
+```
+
+
+The only gem dependency is `http_client` to manage HTTP calls to API.AI.
+
+# To start things up
+The gem is centered around the ApiAiWrapper::Engine model that will be the gateway to all the gem's available endpoints. To make such calls, just instantiate an Engine with the correct developer and client tokens (for training and meaning retrieval) like so (in an initializer for instance) :
+
+```ruby
+$engine = ApiAiWrapper::Engine.new({
+  developer_token: "YOUR DEVELOPER TOKEN",
+  client_token: "YOUR CLIENT TOKEN"
+})
+```
+
+That's for the basic usage, if you want complete control over your API.AI engine initialization, you might do : 
+
+```ruby
+$engine = ApiAiWrapper::Engine.new({
+  developer_token: "YOUR DEVELOPER TOKEN",
+  client_token: "YOUR CLIENT TOKEN",
+  client_timeout: HTTPCLIENT TIMEOUT IN SECONDS (defaults to 50000),
+  locale: "YOUR ENGINE REQUIRED LOCALE" (defaults to "en"),
+  version: "YOUR PREFERRED API.AI VERSION" (defaults to "20150910")
+})
+```
+
+Because we use HTTPClient for calls, you can override the client_timeout attribute to pick your prefered timeout. As a default, it is set to 50000 seconds.
+
+# To actually use the gem
+The API.AI API (that's a mouthful) offers two modes : the Training mode and the Query mode.
+
+## Training Mode
+Included in this gem are all endpoints available in API.AI around [entities](https://api.ai/docs/reference/agent/entities) and [intents](https://api.ai/docs/reference/agent/intents).
+
+To use them, initializing an engine with the code above (`developer_token` is required) gives you access to an `IntentTrainer` and `EntityTrainer` instances that serve as proxy to call the corresponding endpoints. For example, assuming `$engine` has been initialized, fetching all entities on a given engine can be done as follows : 
+
+```ruby
+  entity_trainer = $engine.entity_trainer
+  entities = entity_trainer.get_entities
+```
+
+Posting a new intent can be as easy as that :
+
+```ruby
+  intent_trainer = $engine.intent_trainer
+  intent_trainer.post_intent({
+    name: "some-name",
+    user_says_data: [
+      {
+        data: [
+          {
+            text: "A sample "
+          },
+          {
+            text: "utterance",
+            alias: "object",
+            meta: "@object"
+          },
+          {
+            text: " for you"
+          }
+        ],
+        isTemplate: false,
+        count: 0
+      },
+      {
+        data: ...
+      }
+    ]
+  })
+```
+
+### Endpoints list
+
+All available methods/endpoints are listed in the tables below
+
+#### IntentTrainer
+
+Use these methods on `intent_trainer = $engine.intent_trainer`
+
+Name | Arguments | Description
+--- | --- | ---
+*get_intents* | none | Retrieves a list of all intents for the agent.
+*get_intent* | `intent_id` | Retrieves the specified intent.
+*post_intent* | `name`, `user_says_data`, `options` | Creates a new intent (options is a hash containing additional info about an intent specified in API.AI documentation).
+*put_intent* | `intent_id`, `options` | Updates the specified intent. (options is a hash containing intent fields to modify)
+*delete_intent* | `intent_id` | Deletes the specified entity.
+
+#### EntityTrainer
+
+Use these methods on `entity_trainer = $engine.entity_trainer`
+
+Name | Arguments | Description
+--- | --- | ---
+*get_entities* | none | Retrieves a list of all entities for the agent.
+*get_entity* | `entity_id` | Retrieves the specified entity.
+*post_entity* | `name`, `entries` | Creates a new entity.
+*post_entity_entries* | `entity_id`, `entries` | Adds an array of entity entries to the specified entity.
+*put_entity* | `entity_id`, `options` | Creates or updates multiple entities. (options is a hash containing entity fields to modify)
+*put_entity_entries* | `entity_id`, `entries` | Updates an array of entity entries in the specified entity.
+*delete_entity* | `entity_id` | Deletes the specified entity.
+*delete_entity_entries* | `entity_id`, `entries` | Deletes an array of entity entries from the specified entity.
+
+## Query mode
+After your API.AI engine is properly trained, you can retrieve meaning (intents and entities) from a novel utterance via the `query` endpoint.
+
+To use is, initializing an engine with the code above (`client_token` is required) gives you access to a `MeaningExtractor` instance that serves as proxy to call the `query` endpoint. Assuming `$engine` has been initialized, extracting the meaning from a sentence can be done as follows : 
+
+```ruby
+  meaning_extractor = $engine.meaning_extractor
+  meaning_extractor.post_query("A sample utterance")
+```
+
+This call will return a JSON parsed hash with the utterance meaning returned by API.AI
+
+Name | Arguments | Description
+--- | --- | ---
+*post_query* | `query`, `options` | Takes natural language text and information, returns intent and entity information. (options is a hash containing additional info about an intent specified in API.AI documentation).
+
+# Errors
+`ApiAiWrapper::Errors::Engine::MissingTokens` error is returned when an `ApiAiWrapper::Engine` is instantiated without any token.
+
+`ApiAiWrapper::Errors::Engine::MissingToken` errors are returned when a call is made to `entity_trainer`, `intent_trainer` or `meaning_extractor` but the appropriate token (either `developer_token` or `client_token`) has not been defined in the Engine.
+
+`ApiAiWrapper::Errors::Engine::ApiError` error is returned whenever something goes wrong during a request to API.AI. The error contains a `error.message`, `error.code` and `error.status` identical to the ones returned by API.AI for full transparency.
+

data/api_ai_wrapper.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'api_ai_wrapper'
-  s.version     = '1.0.0'
+  s.version     = '1.0.4'
   s.date        = '2017-08-04'
   s.summary     = "An API.AI Ruby Wrapper"
   s.description = "A simple ruby library that let's any developer automate the training process of a Natural Language Processing Engine on API.AI, and retrieve meaning from new utterances."

data/lib/api_ai_wrapper/components/component.rb

@@ -1,6 +1,7 @@
 module ApiAiWrapper::Components
 
   class Component
+
     attr_accessor :engine
 
     # We define http_verb methods get/post/put/delete to add correct headers and parse result automatically
@@ -20,16 +21,20 @@ module ApiAiWrapper::Components
     # Throws an error if the call is not successful
     # Returns response if no error is returned
     def handle_response(response_body)
-      response = response_body.deep_symbolize_keys
-      response_status = response[:status]
-      response_code = response_status[:code]
 
-      if response_code != 200
-        raise ApiAiWrapper::Errors::Engine::ApiError.new(response_status[:errorDetails], response_code, response_status[:errorType])
+      if response_body.is_a?(Hash) && response_body.has_key?("status")
+        response_body = response_body.deep_symbolize_keys
+        response_status = response_body[:status]
+        response_code = response_status[:code]
+
+        if response_code != 200
+          raise ApiAiWrapper::Errors::Engine::ApiError.new(response_status[:errorDetails], response_code, response_status[:errorType])
+        end
       end
 
-      response
+      response_body
     end
+
   end
   
 end

data/lib/api_ai_wrapper/extensions/hash.rb

@@ -1,3 +1,4 @@
+# Hash Override taken from Rails
 class Hash
 
   def transform_keys

data/lib/api_ai_wrapper/extensions/object.rb

@@ -1,3 +1,4 @@
+# Object Override taken from Rails
 class Object
   def blank?
     respond_to?(:empty?) ? empty? : !self

data/lib/api_ai_wrapper/extensions/string.rb

@@ -1,3 +1,4 @@
+# String Override taken from Rails
 class String
 
   def demodulize

data/lib/api_ai_wrapper/trainers/intent_trainer.rb

@@ -7,23 +7,17 @@ module ApiAiWrapper::Trainers
     # https://api.ai/docs/reference/agent/intents#get_intents
     # Fetches all intents for a given token
     def get_intents
-      set_headers
       endpoint_url = URI.join(self.engine.base_url, "intents?v=#{self.engine.version}")
 
-      res = self.engine.client.get(endpoint_url, {}, self.engine.headers)
-
-      JSON.parse(res.body)
+      self.get(endpoint_url, {})
     end
 
     # https://api.ai/docs/reference/agent/intents#get_intentsiid
     # Retrieves intent info
     def get_intent(iid)
-      set_headers
       endpoint_url = URI.join(self.engine.base_url, "intents/#{iid}?v=#{self.engine.version}")
 
-      res = self.engine.client.get(endpoint_url, {}, self.engine.headers)
-
-      JSON.parse(res.body)
+      self.get(endpoint_url, {})
     end
 
     # https://api.ai/docs/reference/agent/intents#post_intents
@@ -33,7 +27,6 @@ module ApiAiWrapper::Trainers
     # - templates
     # - responses
     def post_intent(name, user_says_data, options = {})
-      set_headers
       body = options.merge({
         name: name,
         auto: true, # ML activated
@@ -41,31 +34,23 @@ module ApiAiWrapper::Trainers
       })
       endpoint_url = URI.join(self.engine.base_url, "intents?v=#{self.engine.version}")
 
-      res = self.engine.client.post(endpoint_url, body.to_json, self.engine.headers)
-
-      JSON.parse(res.body)
+      self.post(endpoint_url, body.to_json)
     end
 
     # https://api.ai/docs/reference/agent/intents#put_intentsiid
     # Update an intent
     def put_intent(iid, options = {})
-      set_headers
       endpoint_url = URI.join(self.engine.base_url, "intents/#{iid}?v=#{self.engine.version}")
 
-      res = self.engine.client.put(endpoint_url, options.to_json, self.engine.headers)
-
-      JSON.parse(res.body)
+      self.put(endpoint_url, options.to_json)
     end
 
     # https://api.ai/docs/reference/agent/entities#delete_entitieseid
     # Delete an intent
     def delete_intent(iid)
-      set_headers
       endpoint_url = URI.join(self.engine.base_url, "intents/#{iid}?v=#{self.engine.version}")
 
-      res = self.engine.client.delete(endpoint_url, {}, self.engine.headers)
-
-      JSON.parse(res.body)
+      self.delete(endpoint_url, {})
     end
 
   end

data/spec/api_ai_wrapper/components/component_spec.rb

@@ -57,11 +57,27 @@ RSpec.describe ApiAiWrapper::Components::Component do
   end
 
   describe "#handle_response(response)" do
-    context "when API.AI call is successful (code is 200)" do
-      it "should return JSON parsed response" do
-        response = { "status" => { "code" => 200, "errorType" => "success" } }
+    context "when API.AI call is successful" do
+      context "from a GET request" do
+        it "should return JSON parsed array for a list GET" do
+          response = [{ "object-column" => "object-value" }]
+
+          expect(component.send(:handle_response, response)).to eq(response)
+        end
+
+        it "should return JSON parsed object for an instance GET" do
+          response = { "object-column" => "object-value" }
+
+          expect(component.send(:handle_response, response)).to eq(response)
+        end
+      end
+
+      context "from a POST/PUT/DELETE request" do
+        it "should return JSON parsed response" do
+          response = { "status" => { "code" => 200, "errorType" => "success" } }
 
-        expect(component.send(:handle_response, response)).to eq(response.deep_symbolize_keys)
+          expect(component.send(:handle_response, response)).to eq(response.deep_symbolize_keys)
+        end
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_ai_wrapper
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.4
 platform: ruby
 authors:
 - Vincent Gabou