mindtrick 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 35514c456a9f75e1cde8529243ede1c9c04281db
+  data.tar.gz: 2f8d34721606d5abdc48804ca87137e2a40fd835
+SHA512:
+  metadata.gz: 5ba82350e58c9bfa47dd2131bc225c19d566fbaeef87664f2b4b41cf3d9ccee46075b5b7827a4a62c0e000a09aae241c423a2b64f5e2e360ade54a44da0bed0d
+  data.tar.gz: 50289e71b97fb2f349481f5daf0ab78ab3db5ee3e2d2d1b1fa191dc3359f5a43dcfcea067a3f11b2458a477cf3e74e7185f0200809ac3cc829049b33c343f41a

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Josh Lewis
+
+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,103 @@
+# Mindtrick
+
+Mindtrick is a Ruby library for search suggestion completion.
+
+Mindtrick uses Redis's sorted sets to store and track popularity of completed
+terms relative to incomplete search terms. As more users search, the more
+helpful the suggestions become.
+
+## Usage
+
+Require Mindtrick and setup a new instance:
+```ruby
+require 'mindtrick'
+mt = Mindtrick.new
+```
+
+Each time a user submits a search, add the query:
+```ruby
+mt.add('these are not the droids you are looking for')
+```
+
+When the user inputs a few letters, get a list of suggestions:
+```ruby
+mt.suggest('T')
+# => ['these are not the droids you are looking for']
+```
+
+Terms are scored, so that the most frequently searched terms are suggested:
+```ruby
+['foo', 'foobar', 'foobar', 'foosball', 'foosball', 'foosball'].each do |term|
+  mt.add(term)
+end
+
+mt.suggest('foo', 2)
+# => ['foosball', 'foobar']
+```
+
+## Options
+
+### redis
+
+You can tell Mindtrick what redis instance you want to connect to. By default,
+Mindtrick assumes Redis is on localhost with default credentials.
+
+```ruby
+Mindtrick.new(redis: Redis.new(url: "redis://..."))
+```
+
+### prefix
+
+By default, all sets created by Mindtrick are prefixed with 'mndtrk'.
+You can change this if you don't like it, or if you have multiple suggestion
+contexts:
+
+```ruby
+Mindtrick.new(prefix: 'searchbox1')
+```
+
+### max_terms
+
+To prevent balooning of your Redis instance, we prune unpopular terms so that
+there are only 250 terms per prefix. This number can be tweaked to your liking.
+
+```ruby
+Mindtrick.new(max_terms: 100)
+```
+
+### max_length
+
+Again, to prevent balooning of your Redis instance, Mindtrick doesn't keep
+suggestions over 15 characters in length. You can tweak this as needed:
+
+```ruby
+Mindtrick.new(max_length: 20)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mindtrick'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install mindtrick
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/mindtrick/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test
+

data/lib/mindtrick/set.rb

@@ -0,0 +1,40 @@
+module Mindtrick
+  class Set
+
+    attr_reader :redis, :prefix, :max_terms, :max_length
+    def initialize(opts = {})
+      @redis      = opts[:redis]      || Redis.new
+      @prefix     = opts[:prefix]     || 'mndtrk'
+      @max_terms  = opts[:max_terms]  || 250
+      @max_length = opts[:max_length] || 15
+    end
+
+    def add(term)
+      term = Text.new(term)
+      term.each_fragment do |f|
+        if f.length <= max_length
+          k = f.prefixed(prefix)
+          redis.zincrby(k, 1, term)
+          enforce_term_limit(k)
+        end
+      end
+      term
+    end
+
+    def suggest(partial, count = 10)
+      key = Text.new(partial).prefixed(prefix)
+      redis.zrevrange key, 0, count
+    end
+
+    private
+
+    def enforce_term_limit(key)
+      if (over = redis.zcount(key, 0, '+inf') - max_terms) > 0
+        partials = redis.zrange(key, 0, over * 3).sample(over)
+        redis.zrem(key, partials)
+      end
+    end
+
+
+  end
+end

data/lib/mindtrick/text.rb

@@ -0,0 +1,19 @@
+module Mindtrick
+  class Text < String
+    def each_fragment
+      return to_enum(:each_fragment) unless block_given?
+      (0..term.length).each do |i|
+        yield term[0...i]
+      end
+    end
+
+    def term
+      strip.gsub(/\s+/,' ')
+    end
+
+    def prefixed(prefix)
+      "#{ prefix }:#{ downcase }"
+    end
+
+  end
+end

data/lib/mindtrick/version.rb

@@ -0,0 +1,3 @@
+module Mindtrick
+  VERSION = "0.0.2"
+end

data/lib/mindtrick.rb

@@ -0,0 +1,8 @@
+require 'redis'
+
+require 'mindtrick/version'
+require 'mindtrick/text'
+require 'mindtrick/set'
+
+module Mindtrick
+end

data/mindtrick.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mindtrick/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mindtrick"
+  spec.version       = Mindtrick::VERSION
+  spec.authors       = ["Josh Lewis"]
+  spec.email         = ["josh.w.lewis@gmail.com"]
+  spec.summary       = %q{Search completion suggestions using Redis's sorted sets.}
+  spec.description   = %q{Search completion suggestions using Redis's sorted sets.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency             'redis',    '~> 3.0'
+
+  spec.add_development_dependency 'bundler',  '~> 1.6'
+  spec.add_development_dependency 'rake',     '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+end

data/test/set_test.rb

@@ -0,0 +1,83 @@
+require 'test_helper'
+
+class SetTest < Minitest::Test
+
+  attr_accessor :max_length, :max_terms
+  def set
+    Mindtrick::Set.new(redis: redis, prefix: prefix, max_length: max_length,
+                       max_terms: max_terms)
+  end
+
+  def prefix
+    @prefix ||= 'mndtrk-tst'
+  end
+
+  def redis
+    @redis ||= Redis.new
+  end
+
+  def build_samples
+    %w{fo foo foobar foobar foosball foosball foosball }.each do |term|
+      set.add(term)
+    end
+  end
+
+
+  def test_add
+    set.add('qux')
+    assert_includes set.suggest('q'), 'qux'
+  end
+
+  def test_suggest
+    build_samples
+    results = set.suggest "foo"
+    assert_equal    results.first, 'foosball'
+    assert_equal    results.last,  'foo'
+    refute_includes results,       'fo'
+  end
+
+  def test_max_length_default
+    self.max_length = nil
+    assert stores_length(15)
+    refute stores_length(16)
+  end
+
+  def test_max_length_option
+    self.max_length = 4
+    assert stores_length(4)
+    refute stores_length(5)
+  end
+
+  def stores_length(l)
+    phrase = random_string(l * 2)
+    set.add(phrase)
+    0 < redis.zcard("#{ prefix }:#{ phrase[0...l] }")
+  end
+
+  def test_max_terms_default
+    self.max_terms = nil
+    assert_max_terms(250)
+  end
+
+  def test_max_terms_option
+    self.max_terms = 40
+    assert_max_terms(40)
+  end
+
+  def assert_max_terms(max)
+    (max + 25).times do
+      set.add("foo#{ random_string(8) }")
+    end
+    assert_equal max, redis.zcount("#{ prefix }:foo", '-inf', '+inf')
+  end
+
+  def random_string(chars)
+    (0...chars).map { (97 + rand(26)).chr }.join
+  end
+
+  def teardown
+    keys = redis.keys("#{ prefix }:*")
+    redis.del keys
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'minitest/autorun'
+require 'minitest/pride'
+
+require 'mindtrick'

data/test/text_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class TextTest < Minitest::Test
+  def test_each_fragment_enumerator
+    text = Mindtrick::Text.new("abcd")
+    assert_kind_of Enumerator, text.each_fragment
+  end
+
+  def test_each_fragment_map
+    text = Mindtrick::Text.new(" abc de")
+    expected = ['', 'a', 'ab', 'abc', 'abc ', 'abc d', 'abc de']
+    result = text.each_fragment.map(&:to_s)
+    assert_equal expected, result
+  end
+
+  def test_term
+    text = Mindtrick::Text.new(" the dude \t abides. ")
+    assert_equal text.term, "the dude abides."
+  end
+
+  def test_prefix
+    text = Mindtrick::Text.new("bar")
+    assert_equal text.prefixed('foo'), "foo:bar"
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: mindtrick
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Josh Lewis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Search completion suggestions using Redis's sorted sets.
+email:
+- josh.w.lewis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mindtrick.rb
+- lib/mindtrick/set.rb
+- lib/mindtrick/text.rb
+- lib/mindtrick/version.rb
+- mindtrick.gemspec
+- test/set_test.rb
+- test/test_helper.rb
+- test/text_test.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Search completion suggestions using Redis's sorted sets.
+test_files:
+- test/set_test.rb
+- test/test_helper.rb
+- test/text_test.rb
+has_rdoc: