eclaircir 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 82949b54ab4bb6cf95d31e2a463792c865412137
+  data.tar.gz: 84da4238a63460cf6c0b1d92502462586c2de59d
+SHA512:
+  metadata.gz: 0493fe176bba3a735e5bb5b3b1b533bd617334657519d74a567215ae496f5961a0d455ea8000a49d789c3380b5c0cfc65a0e49bc66409749d37b6d0dfa632c8c
+  data.tar.gz: c7a7831b5afb741d095305ec90fdda0d502204525aa60e0c2b71a16e2dbbb6fc6209c0db2dd30d00a9f9dda7496b12aebc65cd26083c2fdaf98f13aa83c0c5ed

data/.gitignore

@@ -0,0 +1,27 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile ~/.gitignore_global
+
+# Ignore bundler config
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*.log
+/tmp
+/coverage
+/public
+/debug
+/.bundle
+/doc
+/db/schema.rb
+
+# Ignore dotenv config
+/.env
+
+# Ignore rspec customization
+/.rspec
+
+# Ignore Gemfile.lock as this is a gem
+/Gemfile.lock

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+bundler_args: --jobs=2
+before_install: gem install bundler
+script: 'bundle exec rake spec'
+rvm:
+- 2.4.0
+- 2.3.0
+- 2.2.0
+- 2.1.0
+- 2.0.0
+cache: bundler

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+gemspec
+
+gem 'rake'
+gem 'virtus'
+
+group :test, :development do
+  gem 'rspec', '~> 3.4'
+  gem 'rspec-its'
+  gem 'byebug'
+  gem 'dotenv'
+  gem 'simplecov', require: false
+  gem 'coveralls', require: false
+  gem 'factory_bot'
+  gem 'faker'
+  gem 'webmock'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Karim Bogtob
+
+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,70 @@
+# Eclaircir
+Eclaircir is a french synonym for 'Clarify' and seemed relevant as a name for the gem.
+
+This gem aims to be a Clarifai APIv2 wrapper that is complete, tested and covered.
+
+[![Build Status](https://travis-ci.org/kbogtob/eclaircir.svg?branch=master)](https://travis-ci.org/kbogtob/eclaircir)
+[![Coverage Status](https://coveralls.io/repos/github/kbogtob/eclaircir/badge.svg?branch=master)](https://coveralls.io/github/kbogtob/eclaircir?branch=master)
+
+## Install
+
+```sh
+gem install eclaircir
+```
+
+## Requirements
+* Ruby 2.0.0 or higher
+* HTTParty
+* Virtus
+
+## Examples
+
+...
+
+## Contributing
+* Fork the project
+* Run `bundle install --path .bundle`
+* Run `bundle exec rake spec`
+* Add tests for your feature (the TDD way!)
+* Implement your feature
+* Run tests again
+* Commit (excluding the `Rakefile` or the `Version.rb` if you want to be merged)
+* Send a pull request
+
+## How can I help?
+
+The Roadmap for V1 is to provide a completely usable API wrapper to do common tasks on Clarifai.
+
+Here's an extract from the TODO:
+
+# V1.0
+- [x] Authentication
+  - [x] API Key Management
+  - [x] Authorization
+- [x] Status Management
+  - [x] Modelization: Response
+  - [x] Modelization: Status
+  - [x] Modelization: Output
+  - [x] General Errors
+  - [x] Specific Errors
+  - [ ] Fully manage statuses using the statuses cheatsheet
+  - [x] Response Parsing
+- [x] Predict
+  - [x] Modelization: Input
+  - [x] Modelization: Data
+  - [x] Modelization: Concept
+  - [x] Modelization: Model
+  - [x] Support URL Requests for Images
+  - [x] Response Parsing
+  - [ ] Support base 64 Requests for Images
+  - [ ] Support of multiple inputs (max 128)
+  - [ ] Modelization: Frame
+  - [ ] Video support
+- [ ] Search
+  - [ ] Add Images to search index
+  - [ ] Search by concept
+  - [ ] Search by image
+- [ ] Train
+  - [ ] Add image with concepts
+  - [ ] Model Creation
+  - [ ] Model Training

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+task default: :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc']
+end

data/TODO.md

@@ -0,0 +1,75 @@
+# V1.0
+- [x] Authentication
+  - [x] API Key Management
+  - [x] Authorization
+- [x] Status Management
+  - [x] Modelization: Response
+  - [x] Modelization: Status
+  - [x] Modelization: Output
+  - [x] General Errors
+  - [x] Specific Errors
+  - [ ] Fully manage statuses using the statuses cheatsheet
+  - [x] Response Parsing
+- [x] Predict
+  - [x] Modelization: Input
+  - [x] Modelization: Data
+  - [x] Modelization: Concept
+  - [x] Modelization: Model
+  - [x] Support URL Requests for Images
+  - [x] Response Parsing
+  - [ ] Support base 64 Requests for Images
+  - [ ] Support of multiple inputs (max 128)
+  - [ ] Modelization: Frame
+  - [ ] Video support
+- [ ] Search
+  - [ ] Add Images to search index
+  - [ ] Search by concept
+  - [ ] Search by image
+- [ ] Train
+  - [ ] Add image with concepts
+  - [ ] Model Creation
+  - [ ] Model Training
+
+# V2.0
+- [ ] Feedback
+  - [ ] Modelization : Feedback Info
+  - [ ] Provide feedback on inputs with concepts
+  - [ ] Provide feedback on inputs with regions
+  - [ ] Provide feedback on searches
+- [ ] Inputs management
+  - [ ] Add input with custom id
+  - [ ] Add input with metadata
+  - [ ] Add input with crop
+  - [ ] Get input by id
+  - [ ] Modelization: Status
+  - [ ] Get input status
+  - [ ] Input: Upsert concepts
+  - [ ] Input: Delete concepts
+  - [ ] Input: Bulk Upsert concepts
+  - [ ] Input: Bulk Delete concepts
+  - [ ] Delete input
+  - [ ] Bulk Delete input
+  - [ ] Clean inputs
+- [ ] Models management
+  - [ ] Create model with concepts
+  - [ ] Model: Upsert concepts
+  - [ ] Model: Delete concepts
+  - [ ] Model: Update concept name
+  - [ ] List models
+  - [ ] Get model by id
+  - [ ] Model: List concepts
+  - [ ] Model: List versions
+  - [ ] Model: Get version by id
+  - [ ] Model: Get training inputs
+  - [ ] Model: Get training inputs by version
+  - [ ] Delete model
+  - [ ] Model: Delete version
+  - [ ] Clean models
+  - [ ] Search model
+
+- [ ] Workflow Predict
+
+# Experimental features
+- [ ] Video splitting using ffmpeg
+  - [ ] For models not supporting videos
+  - [ ] For videos too big

data/bin/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require 'dotenv'
+  Dotenv.load
+rescue LoadError
+end
+
+exec('irb', '-I', 'lib/', '-r', 'eclaircir')

data/bin/test.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'eclaircir'
+require 'byebug'
+
+c = Eclaircir::Client.new(Eclaircir.configuration.api_key)
+
+input = Eclaircir::Input.from_url('https://samples.clarifai.com/metro-north.jpg')
+model = Eclaircir::Model.new(id: 'aaa03c23b3724a16a56b629203edc62c')
+# response = model.predict_outputs(url: 'https://samples.clarifai.com/metro-north.jpg')
+response = model.predict_outputs(input: input)
+
+# response = c.predict_outputs(model, input)
+puts response.inspect

data/eclaircir.gemspec

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# frozen_string_literal: true
+
+require_relative 'lib/eclaircir/version'
+
+Gem::Specification.new do |s|
+  s.name = 'eclaircir'
+  s.version = Eclaircir::VERSION
+  s.summary = 'Clarifai APIv2 Client'
+  s.description = 'Ruby Clarifai API wrapper that aims to be complete, tested and covered'
+  s.authors = ['Karim Bogtob']
+  s.email = 'kabogtob@gmail.com'
+  s.homepage = 'https://github.com/kbogtob/eclaircir'
+  s.license = 'MIT'
+
+  s.files = `git ls-files`.split("\n")
+
+  s.add_dependency 'httparty', ['~> 0.14.0']
+  s.add_dependency 'virtus', ['~> 1.0']
+end

data/lib/eclaircir/api_models/attributes/nullable_date_time.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  module Attributes
+    class NullableDateTime < Virtus::Attribute
+      def coerce(value)
+        if value.nil? || value.is_a?(DateTime)
+          value
+        else
+          DateTime.parse(value)
+        end
+      end
+    end
+  end
+end

data/lib/eclaircir/api_models/attributes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  module Attributes
+  end
+end
+
+require_relative 'attributes/nullable_date_time'

data/lib/eclaircir/api_models/base_model.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  class BaseModel
+    include Virtus.model
+
+    def to_api_hash
+      attributes
+    end
+  end
+end

data/lib/eclaircir/api_models/concept.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Concept < BaseModel
+    attribute :id, String
+    attribute :name, String
+    attribute :app_id, String
+    attribute :value, Float
+  end
+end

data/lib/eclaircir/api_models/data.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Data < BaseModel
+    attribute :image, Media
+    attribute :concepts, Array[Concept]
+
+    def to_api_hash
+      super.tap do |api_hash|
+        api_hash[:image] = image.to_api_hash if image
+        api_hash[:concepts] = concepts.map(&:to_api_hash) if concepts
+      end.compact
+    end
+  end
+end

data/lib/eclaircir/api_models/input.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Input < BaseModel
+    attribute :id, String
+    attribute :data, Data
+
+    class << self
+      def from_url(url)
+        self.new(
+          data: Data.new(
+            image: Media.new(url: url)))
+      end
+    end
+
+    def to_api_hash
+      super.merge(data: data.to_api_hash).compact
+    end
+  end
+end

data/lib/eclaircir/api_models/media.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Media < BaseModel
+    attribute :url, String
+  end
+end

data/lib/eclaircir/api_models/model.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Model < BaseModel
+    attribute :id, String
+    attribute :name, String
+    attribute :created_at, Attributes::NullableDateTime
+    attribute :app_id, String
+    attribute :output_info, Hash
+    attribute :model_version, Hash
+
+    def predict_outputs(url: nil, input: nil)
+      to_predict =  if url
+                      Input.from_url(url)
+                    elsif input
+                      input
+                    end
+
+      if Array(to_predict).empty?
+        raise ArgumentError,
+          'one of the following keyword arguments should be provided [url, input]'
+      end
+
+      Eclaircir.new_client.predict_outputs(self, to_predict)
+    end
+  end
+end

data/lib/eclaircir/api_models/output.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Output < BaseModel
+    attribute :id, String
+    attribute :status, Status
+    attribute :created_at, Attributes::NullableDateTime
+    attribute :model, Model
+    attribute :input, Input
+    attribute :data, Data
+  end
+end

data/lib/eclaircir/api_models/response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Response < BaseModel
+    attribute :status, Status
+    attribute :outputs, Array[Output]
+
+    class << self
+      def parse(raw_response)
+        self.new(raw_response)
+      end
+    end
+  end
+end

data/lib/eclaircir/api_models/status.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module Eclaircir
+  class Status < BaseModel
+    attribute :code, Integer
+    attribute :description, String
+
+    def success?
+      code == SUCCESS
+    end
+
+    def validate!
+      unless success?
+        error_class = ERRORS_MAPPINGS.fetch(code, APIError)
+        raise error_class, description
+      end
+
+      true
+    end
+
+    # statuses
+    SUCCESS = 10_000
+
+    FAILURE = 10_020
+
+    INVALID_AUTH_TOKEN = 11_001
+    API_KEY_NOT_FOUND = 11_009
+
+    BAD_REQUEST_FORMAT = 11_100
+    INVALID_REQUEST = 11_102
+
+    DUPLICATE_URL = 30_100
+    IMAGE_DECODING_FAILED = 30_300
+
+    ERRORS_MAPPINGS = {
+      INVALID_AUTH_TOKEN    => InvalidAuthTokenError,
+      API_KEY_NOT_FOUND     => ApiKeyNotFoundError,
+      BAD_REQUEST_FORMAT    => BadRequestFormatError,
+      INVALID_REQUEST       => InvalidRequestError,
+      DUPLICATE_URL         => DuplicateURLError,
+      IMAGE_DECODING_FAILED => ImageDecodingError,
+    }.freeze
+  end
+end

data/lib/eclaircir/api_models.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Eclaircir
+
+end
+
+require_relative 'api_models/attributes'
+
+require_relative 'api_models/concept'
+require_relative 'api_models/status'
+require_relative 'api_models/media'
+require_relative 'api_models/data'
+require_relative 'api_models/model'
+require_relative 'api_models/input'
+require_relative 'api_models/output'
+require_relative 'api_models/response'

data/lib/eclaircir/client/status_validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  class Client
+    class StatusValidator
+      def initialize(response)
+        @response = response
+      end
+
+      def validate!
+        return true if main_status.success?
+
+        sub_statuses.each(&:validate!)
+
+        main_status.validate!
+      end
+
+      protected
+      attr_reader :response
+
+      def main_status
+        response.status
+      end
+
+      def sub_statuses
+        response.outputs.map(&:status)
+      end
+    end
+  end
+end

data/lib/eclaircir/client.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  class Client
+    include HTTParty
+
+    base_uri(Eclaircir::API_ENDPOINT)
+    format :json
+    headers 'Content-Type' => 'application/json', 'Accept' => 'application/json'
+
+    def initialize(api_key)
+      @api_key = api_key
+    end
+
+    def models(options = {})
+      get('/models', query: options)
+    end
+
+    def predict_outputs(model, inputs)
+      with_response_parsing do
+        validate post("/models/#{model.id}/outputs", body: {
+          inputs: Array(inputs).map(&:to_api_hash)
+        }.to_json)
+      end
+    end
+
+    protected
+    attr_reader :api_key
+
+    def authorization_headers
+      @authorization_headers ||= {
+        'Authorization' => "Key #{api_key}"
+      }
+    end
+
+    def get(path, query: nil)
+      self.class.get(path,
+        headers: authorization_headers,
+        query: query)
+    end
+
+    def post(path, query: nil, body: nil)
+      self.class.post(path,
+        headers: authorization_headers,
+        query: query,
+        body: body)
+    end
+
+    def patch(path, query: nil, body: nil)
+      self.class.patch(path,
+        headers: authorization_headers,
+        query: query,
+        body: body)
+    end
+
+    def delete(path, query: nil, body: nil)
+      self.class.delete(path,
+        headers: authorization_headers,
+        query: query,
+        body: body)
+    end
+
+    def with_response_parsing
+      Eclaircir::Response.parse(yield).tap do |response|
+        StatusValidator.new(response).validate!
+      end
+    end
+
+    def validate(response)
+      case response.code
+      when 200..399
+        response.parsed_response
+      else
+        raise_status_error(response.parsed_response)
+      end
+    end
+
+    def raise_status_error(raw_response)
+      status = raw_response['status']
+      raise APIError, status['description']
+    end
+  end
+end
+
+require_relative 'client/status_validator'

data/lib/eclaircir/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  class Configuration
+    def initialize(
+      env: ENV,
+      api_key: nil)
+      @api_key = api_key || env['CLARIFIER_API_KEY']
+    end
+
+    attr_accessor :api_key
+
+    protected
+    attr_reader :env
+  end
+end

data/lib/eclaircir/constants.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Eclaircir
+  API_ENDPOINT = 'https://api.clarifai.com/v2'
+end