inci_score 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7e4bae1a80f16b3684a4d38be2455c737d0fa58a
+  data.tar.gz: e1b1bc6d078e85953e14c071bdd82f678a87cf99
+SHA512:
+  metadata.gz: a1234e75bf300c6de9de417f133d858876cebcaf90abac76b803ac242b5a88f8a36eea1e99badbb56ca7ef317d269de2dadaaa6502703cce05afa66ff829bdbc
+  data.tar.gz: e566482ae9a45829b5bbbe1c2431f35cfb72a68ba6e9eafbb2a32a75e9559a74c8d25819c520d05708f6c82691de1f139bf8628acf665f0b30a52730c4e7552a

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/**/.DS_Store
+*.gem

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.8
+  - 2.2.1
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

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

data/README.md

@@ -0,0 +1,117 @@
+## Table of Contents
+
+* [Scope](#scope)
+* [INCI catalog](#inci-catalog)
+* [Computation](#computation)
+  * [Component matching](#component-matching)
+  * [Sources](#sources)
+* [API](#api)
+  * [Unrecognized components](#unrecognized-components)
+* [Web API](#web-api)
+  * [Starting Puma](#starting-puma)
+  * [Triggering a request](#triggering-a-request)
+* [CLI API](#cli-api)
+* [Performance](#performance)
+  * [Levenshtein in C](#levenshtein-in-c)
+  * [Records](#records)
+
+## Scope
+This gem computes the score of cosmetic components basing on the information provided by the [Biodizionario site](http://www.biodizionario.it/) by Fabrizio Zago.
+
+## INCI catalog
+[INCI](https://en.wikipedia.org/wiki/International_Nomenclature_of_Cosmetic_Ingredients) catalog is fetched directly by the bidizionario site and kept in memory.  
+Currently there are more than 5000 components with a hazard score that ranges from 0 (safe) to 4 (dangerous).
+
+## Computation
+The computation takes care to score each component of the cosmetic basing on:
+* its hazard basing on the biodizionario score
+* its position on the list of ingredients
+
+The total score is then calculated on a percent basis.
+
+### Component matching
+Since the ingredients list could come from an unreliable source (e.g. data scanned from a captured image), the gem tries to fuzzy match the ingredients by using different algorithms:
+* exact matching
+* [edit distance](https://en.wikipedia.org/wiki/Levenshtein_distance) behind a specified tolerance
+* first relevant matching digits 
+* matching splitted tokens
+
+### Sources
+The library accepts the list of ingredients as a single string of text. Since this source could come from an OCR program, the library performs a normalization by stripping invalid characters and removing the unimportant parts.  
+The ingredients are typically separated by comma, although normalizer will detect the most appropriate separator:
+
+```
+"Ingredients: Aqua, Disodium Laureth Sulfosuccinate, Cocamidopropiyl\nBetaine"
+```
+
+## API
+The API of the gem is pretty simple, you can open irb by *bundle console* and start computing the INCI score:
+
+```ruby
+inci = InciScore::Computer.new(src: 'aqua, dimethicone').call
+=> #<InciScore::Response:0x000000029f8100 @components={"aqua"=>0, "dimethicone"=>4}, @score=53.762874945799766, @unrecognized=[], @valid=true>
+inci.score
+=> 53.762874945799766
+```
+
+As you see the results are wrapped by an *InciScore::Response* object, this is useful when dealing with the Web API (read below) and when printing them to standard output.
+
+### Unrecognized components
+The API treats unrecognized components as a common case by just marking the object as non valid and raise a warning in case more than 30% of the ingredients are not found.  
+In such case the score is computed anyway by considering only recognized components.  
+Is still possible to query the object for its state:
+
+```ruby
+inci = InciScore::Computer.new(src: 'ingredients:aqua,noent1,noent2').call
+=> #<InciScore::Response:0x000000030c16d0 @components={"aqua"=>0}, @score=100.0, @unrecognized=["noent1", "noent2"], @valid=false>
+inci.valid
+=> false
+inci.unrecognized
+=> ["noent1", "noent2"]
+```
+
+## Web API
+The Web API exposes the *InciScore* library over HTTP via the [Puma](http://puma.io/) application server.
+
+### Starting Puma
+Simply start Puma via the *config.ru* file included in the repository by spawning how many workers as your current workstation supports:
+```
+bundle exec puma -w 8 -t 16:32 --preload
+```
+
+### Triggering a request
+The Web API responds with a JSON object representing the original *InciScore::Response* one.  
+
+You can pass the source string directly as a HTTP parameter:
+
+```
+curl http://127.0.0.1:9292?src=aqua,dimethicone
+=> {"components":{"aqua":0,"dimethicone":4},"unrecognized":[],"score":53.762874945799766,"valid":true}
+```
+
+## CLI API
+You can collect INCI data by using the available binary:
+
+```
+bin/inci_score "aqua,dimethicone,pej-10,noent"
+
+TOTAL SCORE:
+        47.18034913243358
+VALID STATE:
+        true
+COMPONENTS (hazard - name): 
+        0 - aqua
+        4 - dimethicone
+        3 - peg-10
+UNRECOGNIZED:
+        noent
+```
+
+## Performance
+I noticed the APIs slows down dramatically when dealing with unrecognized components to fuzzy match on.  
+I profiled the code by using the [benchmark-ips](https://github.com/evanphx/benchmark-ips) gem, finding the bottleneck was the pure Ruby implementation of the Levenshtein distance algorithm.  
+After some pointless optimization, i replaced this routine with a C implementation: i opted for the straightforward [Ruby Inline](https://github.com/seattlerb/rubyinline) library to call the C code straight from Ruby.  
+As a result i've got a 10x increment of the throughput, all without scarifying code readability.
+
+### Numbers
+I moved the benchmark numbers to the [Crystal porting](https://github.com/costajob/inci_score.cr) of the InciScore library, please look there.

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+namespace :spec do
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << 'spec'
+    t.libs << 'lib'
+    t.test_files = FileList['spec/unit/*_spec.rb']
+  end
+
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'spec'
+    t.libs << 'lib'
+    t.test_files = FileList['spec/integration/*_spec.rb']
+  end
+end
+
+task :default => :"spec:unit"

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'inci_score'
+require 'irb'
+require 'irb/completion'
+IRB.start

data/bin/inci_score

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'inci_score'
+
+fail ArgumentError, "please specify at least a src argument" if ARGV.empty?
+puts InciScore::Computer.new(ARGV[0], InciScore::Catalog.fetch).call

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install