kasabi 0.0.1

data/CHANGES

@@ -0,0 +1,3 @@
+== Version 0.0.1
+
+* Initial project structure and code

data/README.md

@@ -0,0 +1,55 @@
+KASABI.RB
+---------
+
+Kasabi.rb provides a lightweight Ruby client library for interacting with the 
+Kasabi API
+
+[http://kasabi.com][0]
+
+AUTHOR
+------
+
+Leigh Dodds (leigh@kasabi.com)
+
+INSTALLATION
+------------
+
+Kasabi.rb is packaged as a Ruby Gem and can be installed as follows:
+
+	sudo gem install kasabi
+	
+The source for the project is maintained in github at:
+
+http://github.com/kasabi/kasabi.rb
+
+USAGE
+-----
+
+  require 'rubygems'
+  require 'kasabi'
+  
+  client = Kasabi::Sparql::Client.new("http://api.kasabi.com/api/example-api", ENV["KASABI_API_KEY"])
+  results = client.query(...)
+  
+See the examples directory for example scripts.
+  
+LICENSE
+-------
+
+Copyright 2011 Talis Systems Ltd 
+ 
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License. 
+  
+You may obtain a copy of the License at 
+  
+http://www.apache.org/licenses/LICENSE-2.0 
+  
+Unless required by applicable law or agreed to in writing, 
+software distributed under the License is distributed on an "AS IS" BASIS, 
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+  
+See the License for the specific language governing permissions and limitations 
+under the License.
+
+[0]: [http://kasabi.com] 

data/Rakefile

@@ -0,0 +1,76 @@
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'rake/clean'
+
+NAME = "kasabi"
+VER = "0.0.1"
+
+RDOC_OPTS = ['--quiet', '--title', 'Kasabi Ruby Client Documentation']
+
+PKG_FILES = %w( README.md Rakefile CHANGES ) + 
+  Dir.glob("{bin,tests,etc,lib}/**/*")
+
+CLEAN.include ['*.gem', 'pkg']  
+SPEC =
+  Gem::Specification.new do |s|
+    s.name = NAME
+    s.version = VER
+    s.platform = Gem::Platform::RUBY
+    s.required_ruby_version = ">= 1.8.5"    
+    s.has_rdoc = true
+    s.extra_rdoc_files = ["CHANGES"]
+    s.rdoc_options = RDOC_OPTS
+    s.summary = "Ruby Client for Kasabi"
+    s.description = s.summary
+    s.author = "Leigh Dodds"
+    s.email = 'leigh@kasabi.com'
+    s.homepage = 'http://github.com/kasabi/kasabi.rb'
+    s.rubyforge_project = 'kasabi'
+    s.files = PKG_FILES
+    s.require_path = "lib" 
+    s.bindir = "bin"
+    #s.executables = ["..."]
+    s.test_file = "tests/ts_kasabi.rb"
+    s.add_dependency("httpclient", ">= 2.1.3.1")
+    s.add_dependency("json", ">= 1.1.3")
+    s.add_dependency("mocha", ">= 0.9.5")
+    s.add_dependency("mime-types", ">= 1.16")
+    #FIXME versions
+    s.add_dependency("linkeddata")
+  end
+      
+Rake::GemPackageTask.new(SPEC) do |pkg|
+    pkg.need_tar = true
+end
+
+Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = 'doc/rdoc'
+    rdoc.options += RDOC_OPTS
+    rdoc.rdoc_files.include("CHANGES", "lib/**/*.rb")
+    #rdoc.main = "README"    
+end
+
+#desc "Publish rdoc output to rubyforge"
+#task "publish-docs" => ["rdoc"] do 
+#  rubyforge_path = "/var/www/gforge-projects/#{NAME}/" 
+#  sh "scp -r doc/* " + 
+#    "#{ENV["RUBYFORGE_USER"]}@rubyforge.org:#{rubyforge_path}", 
+#    :verbose => true 
+#end 
+
+Rake::TestTask.new do |test|
+  test.test_files = FileList['tests/*/tc_*.rb']
+end
+
+desc "Install from a locally built copy of the gem"
+task :install do
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{NAME}-#{VER}}
+end
+
+desc "Uninstall the gem"
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/lib/kasabi.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'httpclient'
+require 'json'
+require 'linkeddata'
+
+require 'kasabi/api/base_client'
+require 'kasabi/api/lookup'
+require 'kasabi/api/sparql'
+require 'kasabi/api/search'
+require 'kasabi/api/facet'
+require 'kasabi/api/augment'
+require 'kasabi/api/reconcile'

data/lib/kasabi/api/augment.rb

@@ -0,0 +1,40 @@
+module Kasabi
+  
+  module Augment
+    
+    #Client for working with Kasabi Augmentation APIs
+    class Client < BaseClient
+
+      #Initialize the client to work with a specific endpoint
+      #
+      # The _options_ hash can contain the following values:
+      # * *:apikey*: required. apikey authorized to use the API
+      # * *:client*: HTTPClient object instance
+      def initialize(endpoint, options={})
+        super(endpoint, options)
+      end
+
+      # Augment an RSS feed that can be retrieved from the specified URL, against data in this store
+      #
+      # uri:: the URL for the RSS 1.0 feed
+      def augment_uri(uri)
+        response = @client.get(@endpoint, {:apikey=>@apikey, "data-uri" => uri})
+        validate_response(response)
+          
+        return response.content
+      end
+      
+      # Augment data using POSTing it to the API
+      #
+      # Currently this is limited to RSS 1.0 feeds
+      #
+      # data:: a String containing the data to augment
+      def augment(data, content_type="application/rss+xml")
+        response = @client.post("#{@endpoint}?apikey=#{@apikey}", data, {"Content-Type" => "application/rss+xml"})
+        validate_response(response)
+        return response.content
+      end
+      
+    end
+  end
+end

data/lib/kasabi/api/base_client.rb

@@ -0,0 +1,29 @@
+module Kasabi
+  
+  #Base class for API clients
+  class BaseClient
+
+    attr_reader :endpoint
+    attr_reader :client
+    attr_reader :apikey
+    
+    #Initialize the client to work with a specific endpoint
+    #
+    # The _options_ hash can contain the following values:
+    # * *:apikey*: required. apikey authorized to use the API
+    # * *:client*: HTTPClient object instance
+    def initialize(endpoint, options={})
+      @endpoint = endpoint        
+      @client = options[:client] || HTTPClient.new()
+      @apikey = options[:apikey] || nil                    
+    end
+    
+    def validate_response(response)
+      if response.status != 200
+        raise "Unable to perform request. Status: #{response.status}. Message: #{response.content}"
+      end      
+    end
+    
+  end
+  
+end

data/lib/kasabi/api/facet.rb

@@ -0,0 +1,91 @@
+module Kasabi
+  
+  #This module organizes the classes related to the Facet service
+  module Search
+    
+    module Facet 
+      
+      #A term returned in a facet search result
+      #
+      #A term has a number of hits, a reference to a search uri that can 
+      #be used to find all of those hits, and a value
+      class Term
+        attr_reader :hits
+        attr_reader :search_uri
+        attr_reader :value
+        
+        def initialize(hits, search_uri, value)
+          @hits = hits
+          @search_uri = search_uri
+          @value = value
+        end
+        
+      end
+
+      #The results of a facetted search 
+      class Results
+        
+        #The query used to generate the facet results, as echoed in the response
+        attr_reader :query
+        
+        #The fields used to generate the results
+        attr_reader :fields
+        
+        #An array of Term objects
+        attr_reader :facets
+        
+        def initialize(query, fields, facets=Hash.new)
+          @query = query
+          @fields = fields
+          @facets = facets
+        end
+  
+        #Parses the XML format from a successful API response to generate
+        #a Results object instance
+        def Results.parse(data)
+          doc = REXML::Document.new(data)
+          root = doc.root
+          head = root.elements[1]
+  
+          query = ""
+          fields = ""
+          queryEl = head.get_elements("query")[0]
+          if queryEl != nil
+            query = queryEl.text
+          end
+          fieldsEl = head.get_elements("fields")[0]
+          if fieldsEl != nil
+            fields = fieldsEl.text
+          end
+  
+          results = Results.new(query, fields)
+          
+          fields = root.get_elements("fields")[0]
+          if fields == nil
+            raise "No fields in document!"
+          end
+          
+          fields.get_elements("field").each do |field|
+            field_name = field.attribute("name").value
+            results.facets[field_name] = Array.new
+            
+            field.get_elements("term").each do |term|
+              term = Term.new(term.attribute("number").value.to_i, 
+                term.attribute("search-uri").value, 
+                term.text() )
+                
+              results.facets[field_name] << term
+            end
+            
+          end
+          
+          return results          
+        end
+                                
+      end
+        
+    end
+                
+  end
+  
+end

data/lib/kasabi/api/lookup.rb

@@ -0,0 +1,25 @@
+module Kasabi
+  
+  module Lookup
+    
+    class Client < BaseClient
+      
+      #Initialize the client to work with a specific endpoint
+      #
+      # The _options_ hash can contain the following values:
+      # * *:apikey*: required. apikey authorized to use the API
+      # * *:client*: HTTPClient object instance
+      def initialize(endpoint, options={})
+        super(endpoint, options)
+      end
+      
+      def lookup(uri)        
+        response = @client.get(@endpoint, {:about => uri, :apikey=>@apikey, :output=>"json"} )
+        validate_response(response)  
+        return JSON.parse( response.content )     
+      end
+      
+    end
+    
+  end
+end

data/lib/kasabi/api/reconcile.rb

@@ -0,0 +1,124 @@
+module Kasabi
+  
+  module Reconcile
+    
+    class Client < BaseClient
+
+      #Initialize the client to work with a specific endpoint
+      #
+      # The _options_ hash can contain the following values:
+      # * *:apikey*: required. apikey authorized to use the API
+      # * *:client*: HTTPClient object instance
+      def initialize(endpoint, options={})
+        super(endpoint, options)
+      end
+      
+      #Simple reconciliation request
+      def reconcile_label(label, &block)
+        return reconcile( Client.make_query(label), &block )
+      end
+      
+      #Full reconciliation request, allows specifying of additional parameters
+      #
+      #Returns the array of results from the reconciliation request
+      #
+      #Accepts a block to support iteration through the results. Method will yield
+      #each result and its index.
+      def reconcile(query, &block)
+        response = @client.get( @endpoint, {"query" => query.to_json, :apikey=>@apikey } )
+        validate_response(response)
+        results = JSON.parse( response.content )
+        if results["result"] && block_given?
+          results["result"].each_with_index do |r, i|
+            yield r, i
+          end
+        end
+        return results["result"]        
+      end
+      
+      #Perform a number of reconciliation queries
+      #Submits a single request with a number of queries
+      #
+      #Accepts a block to support iteration through the results. Method will yield
+      #each result, its index, and the query      
+      def reconcile_all(queries, &block)        
+        #TODO add batching
+        #TODO make parallel?
+        json = {}
+        queries.each_with_index do |query, i|
+          json["q#{i}"] = query
+        end
+        response = @client.get( @endpoint, {"queries" => json.to_json, :apikey=>@apikey } )
+        validate_response(response)
+        results = JSON.parse( response.content )
+        if block_given?
+          queries.each_with_index do |query, i|
+            if results["q#{i}"]
+              yield results["q#{i}"]["result"], i, query
+            end
+          end
+        end
+        return results         
+      end
+      
+      #Make an array of reconciliation queries using a standard set of options for limiting,
+      #type matching and property filtering
+      #
+      # label:: text to reconcile on
+      # limit:: limit number of results, default is 3
+      # type_strict:: how to perform type matching, legal values are :any (default), :all, :should
+      # type:: string identifier of type, or array of string identifiers
+      # properties:: property filters, see make_property_filter      
+      def Client.make_queries(labels, limit=3, type_strict=:any, type=nil, properties=nil)
+        queries = []
+        labels.each do |label|
+          queries << Client.make_query(label, limit, type_strict, type, properties)
+        end
+        return queries
+      end
+      
+      #Make a reconciliation query
+      #
+      # label:: text to reconcile on
+      # limit:: limit number of results, default is 3
+      # type_strict:: how to perform type matching, legal values are :any (default), :all, :should
+      # type:: string identifier of type, or array of string identifiers
+      # properties:: property filters, see make_property_filter
+      def Client.make_query(label, limit=3, type_strict=:any, type=nil, properties=nil)
+        query = Hash.new
+        query[:query] = label
+        query[:limit] = limit
+        query[:type_strict] = type_strict
+                  
+        query[:type] = type if type != nil
+        query[:properties] = properties if properties != nil
+        
+        return query
+      end
+      
+      #Construct a property filter
+      #
+      #A property name or identifier must be specified. Both are legal but it is up to the 
+      #service to decide which one it uses. Some services may have restrictions on whether 
+      #they support names or identifiers.
+      #
+      #  value:: a single value, or an array of string or number or object literal, e.g., "Japan"
+      #  name::  string, property name, e.g., "country"
+      #  id:: string, property ID, e.g., "/people/person/nationality" in the Freebase ID space
+      def Client.make_property_filter(value, name=nil, id=nil)
+        if name == nil and id == nil
+          raise "Must specify at least a property name or property identifier"
+        end
+        
+        filter = Hash.new
+        filter[:v] = value
+        filter[:p] = name if name != nil
+        filter[:pid] = id if id != nil
+          
+        return filter
+      end
+      
+                  
+    end
+  end
+end