kairos-api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 60d71f53ebc7fcbeda278dcddb8b4ff4b41b0dd7
+  data.tar.gz: 8e6ddb4107be8be6ecb4980df08916da31c9fb21
+SHA512:
+  metadata.gz: 09692f660ee32c292dab10c7e8ae7b501761cc1b9433a37396aaef9c8229d4fdf48079bf6b09c72488d15ceef01046ade03938b9b06673739f9c8935f84a8548
+  data.tar.gz: 5ca4bd9a3fcd21a84adfd1e9c66fdff743761dd11c053df0059b95438723cb4b7270eebe5700804b3008d57e21ba560216824a15220981cfb195203037325182

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format progress

data/.ruby-gemset

@@ -0,0 +1 @@
+kairos

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kairos.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Frank Kany
+
+MIT License
+
+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,62 @@
+# Kairos
+
+Ruby gem for the Kairos facial recognition API - https://developer.kairos.io/
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kairos-api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kairos-api
+
+## Usage
+https://developer.kairos.io/docs
+
+1. Kairos::Client.enroll(:url => 'https://some.url.com/to_some.jpg', :subject_id => 'gemtest', :gallery_name => 'testgallery'):
+
+Takes an image and stores it as a face template into a gallery you define
+
+    $ require 'kairos'
+
+    $ client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+
+    $ client.enroll(:url => 'https://some.url.com/to_some.jpg', :subject_id => 'gemtest', :gallery_name => 'testgallery')
+
+2. Kairos::Client.recognize(:url => 'https://some.image.url/123abc.jpg', :gallery_name => 'randomgallery', :threshold => '.2', :max_num_results => '5'):
+ - Takes an image and tries to match it against the already enrolled images in a gallery you define
+
+3. Kairos::Client.detect(:url => 'https://some.url.com/to_some.jpg', :selector => 'FULL'):
+ - Takes an image and returns the facial features found within it
+
+4. Kairos::Client.gallery_list_all:
+ - Lists out all the galleries you have subjects enrolled in
+
+5. Kairos::Client.gallery_view(:gallery_name => 'testgallery'):
+ - Lists out all the subjects you have enrolled in a specified gallery
+
+6. Kairos::Client.gallery_remove_subject(:gallery_name => 'randomgallery', :subject_id => 'image123abc'):
+ - Removes a subject from a specified gallery
+
+## To Do List
+1) Trim unnessary gem dependencies
+2) Expand documentation
+3) Expand test specs to cover more scenarios and edge cases
+4) DRY up code where possible
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## References
+Thank you to gregmoreno for creating this api template - https://github.com/gregmoreno/awesome

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/kairos.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kairos/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "kairos-api"
+  spec.version       = Kairos::VERSION
+  spec.authors       = ["Frank Kany"]
+  spec.email         = ["frankkany@gmail.com"]
+  spec.description   = %q{Ruby gem for the Kairos facial recognition API}
+  spec.summary       = %q{Ruby gem for the Kairos facial recognition API}
+  spec.homepage      = "https://github.com/kany/kairos-api"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.6"
+  spec.add_development_dependency "webmock", '~> 1.6'
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "typhoeus"
+
+  spec.add_runtime_dependency "faraday", "~> 0.8.0"
+  spec.add_runtime_dependency "faraday_middleware", "~> 0.8.7"
+  spec.add_runtime_dependency "hashie", "~> 1.2.0"
+  spec.add_runtime_dependency "multi_json", "~> 1.3"
+end

data/lib/kairos.rb

@@ -0,0 +1,10 @@
+require "kairos/version"
+require "kairos/configuration"
+require "kairos/client"
+
+require "faraday"
+require "faraday_middleware"
+
+module Kairos
+  extend Configuration
+end

data/lib/kairos/client.rb

@@ -0,0 +1,114 @@
+require 'multi_json'
+require 'hashie'
+require 'json'
+
+module Kairos
+  class Client
+    # Define the same set of accessors as the Kairos module
+    attr_accessor *Configuration::VALID_CONFIG_KEYS
+
+    def initialize(options={})
+      # Merge the config values from the module and those passed
+      # to the client.
+      merged_options = Kairos.options.merge(options)
+
+      # Copy the merged values to this client and ignore those
+      # not part of our configuration
+      Configuration::VALID_CONFIG_KEYS.each do |key|
+        send("#{key}=", merged_options[key])
+      end
+    end
+
+    # Enroll an Image
+    #
+    # Example Usage:
+    #  - require 'kairos'
+    #  - client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+    #  - client.enroll(:url => 'https://some.url.com/to_some.jpg', :subject_id => 'gemtest', :gallery_name => 'testgallery')
+    def enroll(options={})
+      post_to_api(Kairos::Configuration::ENROLL, options)
+    end
+
+    # Recognize an Image
+    #
+    # Example Usage:
+    #  - require 'kairos'
+    #  - client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+    #  - client.recognize(:url => 'https://some.url.com/to_some_other_image.jpg', :gallery_name => 'testgallery', :threshold => '.2', :max_num_results => '5')
+    def recognize(options={})
+      post_to_api(Kairos::Configuration::RECOGNIZE, options)
+    end
+
+    # Remove Subject from Gallery
+    #
+    # Example Usage:
+    #  - require 'kairos'
+    #  - client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+    #  - client.gallery_remove_subject(:gallery_name => 'testgallery', :subject_id => 'gemtest')
+    def gallery_remove_subject(options={})
+      post_to_api(Kairos::Configuration::GALLERY_REMOVE_SUBJECT, options)
+    end
+
+    # Detect faces in Image
+    #
+    # Example Usage:
+    #  - require 'kairos'
+    #  - client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+    #  - client.detect(:url => 'https://some.url.com/to_some_other_image.jpg', :selector => 'FULL')
+    def detect(options={})
+      post_to_api(Kairos::Configuration::DETECT, options)
+    end
+
+    # List all Galleries
+    #
+    # Example Usage:
+    #  - require 'kairos'
+    #  - client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+    #  - client.gallery_list_all
+    def gallery_list_all
+      # ToDo: Research why Typhoeus works better than Faraday for this endpoint
+      request = Typhoeus::Request.new(
+        "#{Kairos::Configuration::GALLERY_LIST_ALL}",
+        method: :post,
+        headers: { "Content-Type" => "application/x-www-form-urlencoded",
+                   "app_id"       => "#{@app_id}",
+                   "app_key"      => "#{@app_key}" }
+      )
+      response = request.run
+      JSON.parse(response.body) rescue "INVALID_JSON: #{response.body}"
+    end
+
+    # View subjects in Gallery
+    #
+    # Example Usage:
+    #  - require 'kairos'
+    #  - client = Kairos::Client.new(:app_id => '1234', :app_key => 'abcde1234')
+    #  - client.gallery_view(:gallery_name => 'testgallery')
+    def gallery_view(options={})
+      post_to_api(Kairos::Configuration::GALLERY_VIEW, options)
+    end
+
+    private
+
+    def post_to_api(endpoint, options={})
+      connection = api_set_connection(endpoint)
+      response   = options.empty? ? api_post(connection) : api_post(connection, options)
+      JSON.parse(response.body) rescue "INVALID_JSON: #{response.body}"
+    end
+
+    def api_set_connection(endpoint)
+      Faraday.new(:url => endpoint) do |builder|
+        builder.use Faraday::Adapter::NetHttp
+      end
+    end
+
+    def api_post(connection, options={})
+      connection.post do |request|
+        request.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+        request.headers['app_id']       = @app_id
+        request.headers['app_key']      = @app_key
+        request.body                    = options.empty? ? nil : options.to_json
+      end
+    end
+  end
+end

data/lib/kairos/configuration.rb

@@ -0,0 +1,43 @@
+module Kairos
+
+  module Configuration
+    VALID_CONNECTION_KEYS  = [:app_id, :app_key].freeze
+    VALID_OPTIONS_KEYS     = [:url, :subject_id, :gallery_name, :threshold, :max_num_results, :selector].freeze
+    VALID_CONFIG_KEYS      = VALID_CONNECTION_KEYS + VALID_OPTIONS_KEYS
+
+    DEFAULT_USER_AGENT     = "Kairos API Ruby Gem #{Kairos::VERSION}".freeze
+    DEFAULT_APP_ID         = nil
+    DEFAULT_APP_KEY        = nil
+
+    ENROLL                 = 'http://api.kairos.io/enroll'
+    RECOGNIZE              = 'http://api.kairos.io/recognize'
+    DETECT                 = 'http://api.kairos.io/detect'
+    GALLERY_LIST_ALL       = 'http://api.kairos.io/gallery/list_all'
+    GALLERY_VIEW           = 'http://api.kairos.io/gallery/view'
+    GALLERY_REMOVE_SUBJECT = 'http://api.kairos.io/gallery/remove_subject'
+
+    # Build accessor methods for every config options so we can do this, for example:
+    #   Kairos.format = :xml
+    attr_accessor *VALID_CONFIG_KEYS
+
+    # Make sure we have the default values set when we get 'extended'
+    def self.extended(base)
+      base.reset
+    end
+
+    def reset
+      self.app_id  = DEFAULT_APP_ID
+      self.app_key = DEFAULT_APP_KEY
+    end
+
+    def configure
+      yield self
+    end
+
+    # Return the configuration values set in this module
+    def options
+      Hash[ * VALID_CONFIG_KEYS.map { |key| [key, send(key)] }.flatten ]
+    end
+  end
+
+end

data/lib/kairos/version.rb

@@ -0,0 +1,3 @@
+module Kairos
+  VERSION = "0.0.1"
+end

data/spec/kairos/client_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe Kairos::Client do
+
+  before do
+    @keys = Kairos::Configuration::VALID_CONFIG_KEYS
+  end
+
+  describe 'with module configuration' do
+    before do
+      Kairos.configure do |config|
+        @keys.each do |key|
+          config.send("#{key}=", key)
+        end
+      end
+    end
+
+    after do
+      Kairos.reset
+    end
+
+    it "should inherit module configuration" do
+      api = Kairos::Client.new
+      @keys.each do |key|
+        api.send(key).should eq(key)
+      end
+    end
+
+    describe 'with class configuration' do
+      before do
+        @config = {
+          :app_id          => 'zz',
+          :app_key         => 'ak',
+          :url             => 'of',
+          :subject_id      => 'ep',
+          :gallery_name    => 'ua',
+          :threshold       => 'hm',
+          :max_num_results => 'bc',
+          :selector        => 'uy'
+        }
+      end
+
+      it 'should override module configuration' do
+        api = Kairos::Client.new(@config)
+        @keys.each do |key|
+          api.send(key).should eq(@config[key])
+        end
+      end
+
+      it 'should override module configuration after' do
+        api = Kairos::Client.new
+
+        @config.each do |key, value|
+          api.send("#{key}=", value)
+        end
+
+        @keys.each do |key|
+          api.send("#{key}").should eq(@config[key])
+        end
+      end
+    end
+
+  end
+
+end

data/spec/kairos/configuration_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe Kairos::Configuration do
+
+  after do
+    Kairos.reset
+  end
+
+  describe '.configure' do
+    Kairos::Configuration::VALID_CONFIG_KEYS.each do |key|
+      it "should set the #{key}" do 
+        Kairos.configure do |config|
+          config.send("#{key}=", key)
+          Kairos.send(key).should eq(key)
+        end
+      end
+    end
+  end
+
+  Kairos::Configuration::VALID_CONNECTION_KEYS.each do |key|
+    describe ".#{key}" do
+      it 'should return the default value' do
+        Kairos.send(key).should eq( Kairos::Configuration.const_get("DEFAULT_#{key.upcase}") )
+      end
+    end
+  end
+
+end

data/spec/kairos/detect_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe Kairos::Client do
+
+  describe '#detect' do
+    before do
+      @config = {
+        :app_id          => 'abc1234',
+        :app_key         => 'asdfadsfasdfasdfasdf'
+      }
+      @client = Kairos::Client.new(@config)
+    end
+
+    it 'responds to detect' do
+      @client.should respond_to(:detect)
+    end
+
+    context 'with valid credentials' do
+      context 'with missing parameters' do
+        it 'should not detect faces' do
+          VCR.use_cassette('detect_with_missing_parameters') do
+            response = @client.detect(:selector => 'FULL')
+            response.should eq("INVALID_JSON: [\"errors:\"{\"Errcode\":5001,\"Message\":\"some unknown service error\"}]")
+          end
+        end
+      end
+      context 'with image with no faces' do
+        it 'should not detect faces' do
+          VCR.use_cassette('detect_with_no_faces_in_image') do
+            response = @client.detect(:url => 'http://upload.wikimedia.org/wikipedia/commons/thumb/2/23/Seal_of_the_US_Air_Force.svg/356px-Seal_of_the_US_Air_Force.svg.png', :selector => 'FULL')
+            response.should eq("INVALID_JSON: [\"errors:\"{\"Errcode\":5002,\"Message\":No face(s) found}]")
+          end
+        end
+      end
+      context 'with required parameters' do
+        before(:each) do
+          VCR.use_cassette('detect') do
+            @response = @client.detect(:url => 'http://www.history.com/s3static/video-thumbnails/AETN-History_Prod/24/226/History_First_Combat_By_Black_Pilots_Speech_SF_still_624x352.jpg', :selector => 'FULL')
+          end
+        end
+        describe 'response' do
+          it 'detects faces of Tuskegee Airman' do
+            @response['images'][0]['status'].should eq("Complete")
+            @response['images'][0]['faces'].size.should eq(3)
+          end
+        end
+      end
+    end
+  end
+
+end