carrot2 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 33734687ea74c1750a823b92eb21648910a7c11c
-  data.tar.gz: 3683ea29b97fa311a23919048d49b2c4c3784701
+SHA256:
+  metadata.gz: e21b80531294f5840aceea2f020c79a6651a02287cd3246d8f7ca493588b1d7e
+  data.tar.gz: a64d7804ed34e9b3fc2ec30eddb54d94b119e9620b0a88afaa8e68ef01b3bf7e
 SHA512:
-  metadata.gz: 8c87a0029e7d304717778fc7fadeee896895cb412524e7fe0d435aec2f84308cbd9d6967481abd8493dff75303024bcdd467b33f7f25947931c8702f261d0f6c
-  data.tar.gz: 5028411dc8eb0bf3a5629824e9fba106846f2759a3c687a43fa5d19636b1cce0bc9b564daf5ab2b0e23ab2a6ca318061345584c0641db0933d7e5b834dc70e39
+  metadata.gz: 72b690c8088d295a3813e6d0a625e4d8972845f533af993c774cc179e1a1c800fe27e8b8c07c62e35f45705111f3053e74c40362ba36412f187aff31d55d50a0
+  data.tar.gz: b0e3e09432846648aebbbd2a599d0a51c1c862bde5074d06b7d29ba0e9e3c199b6e53e1c05eed040d9dbde8f1afdb37e66ad4b1ba3211a2725ea63c5880ac48a

data/CHANGELOG.md

@@ -1,14 +1,27 @@
-## 0.2.0
+## 0.4.0 (2022-08-28)
+
+- Dropped support for Ruby < 2.7
+
+## 0.3.0 (2020-07-29)
+
+- Added support for Carrot2 4
+- Dropped support for Carrot2 < 4
+
+## 0.2.1 (2019-10-28)
+
+- Added `open_timeout` and `read_timeout` options
+
+## 0.2.0 (2017-01-22)
 
 - Added `request` method
 - Removed dependency on `rest-client`
 - Better error messages
 
-## 0.1.0
+## 0.1.0 (2017-01-17)
 
 - Added support for env var
 - Added tests
 
-## 0.0.1
+## 0.0.1 (2012-06-20)
 
 - First version

data/{LICENSE → LICENSE.txt}

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Andrew Kane
+Copyright (c) 2012-2021 Andrew Kane
 
 MIT License
 
@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,12 +1,12 @@
-# Carrot2
+# Carrot2 Ruby
 
-Ruby client for [Carrot2](http://project.carrot2.org/) - the open-source document clustering server
+Ruby client for [Carrot2](https://github.com/carrot2/carrot2) - the open-source document clustering server
 
-## Installation
+[![Build Status](https://github.com/ankane/carrot2-ruby/workflows/build/badge.svg?branch=master)](https://github.com/ankane/carrot2-ruby/actions)
 
-First, [download and run](http://project.carrot2.org/download-dcs.html) the Carrot2 server. It’s the one on [this page](https://github.com/carrot2/carrot2/releases) that begins with `carrot2-dcs`.
+## Installation
 
-With Homebrew, use:
+First, [download and run](https://github.com/carrot2/carrot2#installation) the Carrot2 server. With Homebrew, use:
 
 ```sh
 brew install carrot2
@@ -16,9 +16,11 @@ brew services start carrot2
 Then add this line to your application’s Gemfile:
 
 ```ruby
-gem 'carrot2'
+gem "carrot2"
 ```
 
+The latest version works with Carrot2 4. For Carrot2 3, use version 0.2.1 and [this readme](https://github.com/ankane/carrot2-ruby/blob/v0.2.1/README.md).
+
 ## How to Use
 
 To cluster documents, use:
@@ -31,7 +33,7 @@ documents = [
   "This is completely unrelated to the other documents."
 ]
 
-carrot2 = Carrot2.new
+carrot2 = Carrot2::Client.new
 carrot2.cluster(documents)
 ```
 
@@ -39,79 +41,99 @@ This returns:
 
 ```ruby
 {
-  "processing-time-total"=>1,
-  "clusters"=> [
-    {
-      "id"=>0,
-      "size"=>3,
-      "phrases"=>["Coupon"],
-      "score"=>0.06462323710740674,
-      "documents"=>[0, 1, 2],
-      "attributes"=>{"score"=>0.06462323710740674}
-    },
+  "clusters" => [
     {
-      "id"=>1,
-      "size"=>2,
-      "phrases"=>["Exclusive"],
-      "score"=>0.05873148311034013,
-      "documents"=>[0, 1],
-      "attributes"=>{"score"=>0.05873148311034013}
+      "labels" => ["Coupon"],
+      "documents" => [0, 1, 2],
+      "clusters" => [],
+      "score" => 0.06418006702675011
     },
     {
-      "id"=>2,
-      "size"=>1,
-      "phrases"=>["Other Topics"],
-      "score"=>0.0,
-      "documents"=>[3],
-      "attributes"=>{"other-topics"=>true, "score"=>0.0}
+      "labels" => ["Exclusive"],
+      "documents" => [0, 1],
+      "clusters" => [],
+      "score" => 0.7040290701763807
     }
-  ],
-  "processing-time-algorithm"=>1,
-  "query"=>nil
+  ]
 }
 ```
 
 Documents are numbered in the order provided, starting with 0.
 
-For other requests, use:
+Specify a language with:
 
 ```ruby
-carrot2.request(
-  "dcs.c2stream" => xml_str
-)
+carrot2.cluster(documents, language: "French")
 ```
 
-## Configuration
+Specify an [algorithm](https://carrot2.github.io/release/4.0.0/doc/algorithms/) with:
 
-To specify the Carrot2 server, set `ENV["CARROT2_URL"]` or use:
+```ruby
+carrot2.cluster(documents, algorithm: "Lingo")
+```
+
+Get a list of supported languages and algorithms with:
 
 ```ruby
-Carrot2.new(url: "http://localhost:8080")
+carrot2.list
 ```
 
-## Heroku
+Specify parameters with:
+
+```ruby
+parameters = {
+  preprocessing: {
+    phraseDfThreshold: 1,
+    wordDfThreshold: 1
+  }
+}
+carrot2.cluster(documents, parameters: parameters)
+```
 
-Carrot2 can be easily deployed to Heroku thanks to support for [WAR deployment](https://devcenter.heroku.com/articles/war-deployment).
+See supported parameters for [Lingo](https://carrot2.github.io/release/4.0.0/doc/lingo-attributes/), [STC](https://carrot2.github.io/release/4.0.0/doc/stc-attributes/), and [Bisecting K-Means](https://carrot2.github.io/release/4.0.0/doc/kmeans-attributes/).
 
-You can find the `.war` file in the `war` directory in the dcs download. Then run:
+Specify a [template](https://carrot2.github.io/release/4.0.0/doc/dcs-templates/) with:
 
-```sh
-heroku plugins:install heroku-cli-deploy
-heroku create <app_name>
-heroku war:deploy carrot2-dcs.war --app <app_name>
+```ruby
+carrot2.cluster(documents, template: "lingo")
 ```
 
-And set `ENV["CARROT2_URL"]` in your application.
+## Configuration
+
+To specify the Carrot2 server, set `ENV["CARROT2_URL"]` or use:
+
+```ruby
+Carrot2::Client.new(url: "http://localhost:8080")
+```
+
+Set timeouts
+
+```ruby
+Carrot2::Client.new(open_timeout: 3, read_timeout: 5)
+```
+
+## Resources
+
+- [Carrot2 REST API Basics](https://carrot2.github.io/release/4.0.0/doc/rest-api-basics/)
 
 ## History
 
-View the [changelog](https://github.com/ankane/carrot2/blob/master/CHANGELOG.md)
+View the [changelog](https://github.com/ankane/carrot2-ruby/blob/master/CHANGELOG.md)
 
 ## Contributing
 
 Everyone is encouraged to help improve this project. Here are a few ways you can help:
 
-- [Report bugs](https://github.com/ankane/carrot2/issues)
-- Fix bugs and [submit pull requests](https://github.com/ankane/carrot2/pulls)
+- [Report bugs](https://github.com/ankane/carrot2-ruby/issues)
+- Fix bugs and [submit pull requests](https://github.com/ankane/carrot2-ruby/pulls)
 - Write, clarify, or fix documentation
 - Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/ankane/carrot2-ruby.git
+cd carrot2-ruby
+bundle install
+bundle exec rake test
+```

data/lib/carrot2/client.rb

@@ -0,0 +1,74 @@
+module Carrot2
+  class Client
+    HEADERS = {
+      "Content-Type" => "application/json",
+      "Accept" => "application/json"
+    }
+
+    def initialize(url: nil, open_timeout: 3, read_timeout: nil)
+      url ||= ENV["CARROT2_URL"] || "http://localhost:8080"
+      @uri = URI.parse(url)
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = true if @uri.scheme == "https"
+      @http.open_timeout = open_timeout if open_timeout
+      @http.read_timeout = read_timeout if read_timeout
+    end
+
+    def list
+      get("service/list")
+    end
+
+    def cluster(documents, language: nil, algorithm: nil, parameters: nil, template: nil)
+      # no defaults if template
+      unless template
+        language ||= "English"
+        algorithm ||= "Lingo"
+        parameters ||= {}
+      end
+
+      # data
+      data = {
+        documents: documents.map { |v| v.is_a?(String) ? {field: v} : v }
+      }
+      data[:language] = language if language
+      data[:algorithm] = algorithm if algorithm
+      data[:parameters] = parameters if parameters
+
+      # path
+      path = "service/cluster"
+      path = "#{path}?#{URI.encode_www_form(template: template)}" if template
+
+      post(path, data)
+    end
+
+    private
+
+    def get(path)
+      handle_response do
+        @http.get("#{@uri.request_uri.chomp("/")}/#{path}", HEADERS)
+      end
+    end
+
+    def post(path, data)
+      handle_response do
+        @http.post("#{@uri.request_uri.chomp("/")}/#{path}", data.to_json, HEADERS)
+      end
+    end
+
+    def handle_response
+      begin
+        response = yield
+      rescue Errno::ECONNREFUSED => e
+        raise Carrot2::Error, e.message
+      end
+
+      unless response.kind_of?(Net::HTTPSuccess)
+        body = JSON.parse(response.body) rescue {}
+        message = body["message"] || "Bad response: #{response.code}"
+        raise Carrot2::Error, message
+      end
+
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/carrot2/version.rb

@@ -1,3 +1,3 @@
-class Carrot2
-  VERSION = "0.2.0"
+module Carrot2
+  VERSION = "0.4.0"
 end

data/lib/carrot2.rb

@@ -1,48 +1,15 @@
-require "carrot2/version"
-require "builder"
-require "net/http"
+# dependencies
 require "json"
+require "net/http"
 
-class Carrot2
-  class Error < StandardError; end
-
-  def initialize(url: nil)
-    @url = url || ENV["CARROT2_URL"] || "http://localhost:8080"
-
-    # add dcs/rest
-    @url = "#{@url.sub(/\/\z/, "")}/dcs/rest"
-    @uri = URI.parse(@url)
-  end
-
-  def cluster(documents, language: "ENGLISH")
-    xml = Builder::XmlMarkup.new
-    xml.instruct! :xml, version: "1.0", encoding: "UTF-8"
-    xml.searchresult do |s|
-      documents.each do |document|
-        s.document do |d|
-          d.title document
-        end
-      end
-    end
+# modules
+require "carrot2/client"
+require "carrot2/version"
 
-    request(
-      "dcs.clusters.only" => true,
-      "dcs.c2stream" => xml.target!,
-      "MultilingualClustering.defaultLanguage" => language,
-      multipart: true
-    )
-  end
+module Carrot2
+  class Error < StandardError; end
 
-  def request(params)
-    response = Net::HTTP.post_form(@uri, params.merge("dcs.output.format" => "JSON"))
-    if response.code == "200"
-      JSON.parse(response.body)
-    else
-      body = response.body.to_s
-      # try to get reason from title
-      m = body.match(/<title>(.+)<\/title>/)
-      message = m ? m[1] : body
-      raise Carrot2::Error, message
-    end
+  def self.new(**options)
+    Client.new(**options)
   end
 end

metadata

@@ -1,93 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: carrot2
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andrew Kane
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-01-23 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: builder
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Ruby client for Carrot2
-email:
-- andrew@chartkick.com
+date: 2022-08-29 00:00:00.000000000 Z
+dependencies: []
+description:
+email: andrew@ankane.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
 - CHANGELOG.md
-- Gemfile
-- LICENSE
+- LICENSE.txt
 - README.md
-- Rakefile
-- carrot2.gemspec
 - lib/carrot2.rb
+- lib/carrot2/client.rb
 - lib/carrot2/version.rb
-- test/carrot2_test.rb
-- test/test_helper.rb
-homepage: https://github.com/ankane/carrot2
-licenses: []
+homepage: https://github.com/ankane/carrot2-ruby
+licenses:
+- MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -95,18 +34,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.8
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: Ruby client for Carrot2
-test_files:
-- test/carrot2_test.rb
-- test/test_helper.rb
+test_files: []

data/.gitignore

@@ -1,17 +0,0 @@
-*.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/Gemfile

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

data/Rakefile

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

data/carrot2.gemspec

@@ -1,23 +0,0 @@
-# -*- encoding: utf-8 -*-
-require File.expand_path("../lib/carrot2/version", __FILE__)
-
-Gem::Specification.new do |spec|
-  spec.authors       = ["Andrew Kane"]
-  spec.email         = ["andrew@chartkick.com"]
-  spec.description   = "Ruby client for Carrot2"
-  spec.summary       = "Ruby client for Carrot2"
-  spec.homepage      = "https://github.com/ankane/carrot2"
-
-  spec.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
-  spec.executables   = spec.files.grep(%r{^exe/}).map { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.name          = "carrot2"
-  spec.require_paths = ["lib"]
-  spec.version       = Carrot2::VERSION
-
-  spec.add_dependency "builder"
-
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest"
-end

data/test/carrot2_test.rb

@@ -1,23 +0,0 @@
-require_relative "test_helper"
-
-class Carrot2Test < Minitest::Test
-  def test_cluster
-    documents = [
-      "Sign up for an exclusive coupon.",
-      "Exclusive members get a free coupon.",
-      "Coupons are going fast.",
-      "This is completely unrelated to the other documents."
-    ]
-
-    assert_equal ["Coupon", "Exclusive", "Other Topics"], carrot2.cluster(documents)["clusters"].map { |c| c["phrases"].first }
-  end
-
-  def test_bad_request
-    error = assert_raises(Carrot2::Error) { carrot2.request({}) }
-    assert_includes error.message, "Error 400"
-  end
-
-  def carrot2
-    @carrot2 ||= Carrot2.new
-  end
-end

data/test/test_helper.rb

@@ -1,6 +0,0 @@
-require "bundler/setup"
-Bundler.require(:default)
-require "minitest/autorun"
-require "minitest/pride"
-
-Minitest::Test = Minitest::Unit::TestCase unless defined?(Minitest::Test)