cycr¶ ↑

github.com/apohllo/cycr - code
rubydoc.info/gems/cycr/frames - documentation

DESCRIPTION¶ ↑

cycr is a Ruby client for the (Open)Cyc server www.opencyc.org.

FEATURES¶ ↑

The text protocol is used to talk with Cyc
Ruby symbols are converted to Cyc terms
Ruby arrays are converted to SubL arrays
Ruby calls on the client are transparently translated to SubL
Support for subcalls (like with-any-mt)
connection drivers: regular socket and synchrony based communication
auto reconnecting the client after server downtime
thread safe client as an option

PROBLEMS¶ ↑

Support for NARTs might not be fully functional (works only with ResearchCyc)
Support for CycL queries not implemented yet!

SYNOPSIS¶ ↑

cycr is a Ruby client for the (Open)Cyc server. It is designed as a substitution for the original Java client. It allows for conversation with the ontology with regular Ruby objects (like symbols, arrays) and also exposes a raw text protocol.

If you use this library you might be intereste in:

github.com/apohllo/cyc-console - replacement for Cyc console
github.com/apohllo/navicyc - Rails and ExtJS replacement for Cyc browser

REQUIREMENTS¶ ↑

(Open)Cyc server with TCP communication enabled.

INSTALL¶ ↑

The gem is available at rubygems.org, so you can install it with:

$ sudo gem install cycr

In case of problems just make sure that you have RubyGems v.1.3.5 at least:

$ gem -v
1.2.0 # => not OK
$ gem update --system
...
$ gem -v 
1.3.7 # => OK

BASIC USAGE¶ ↑

Prerequisites:

running Cyc server - you can download it from www.opencyc.org
Telnet connection is turned on. Type +(enable-tcp-server :cyc-api 3601)+ in the cyc console or Cyc Browser -> Tools -> Interactor

Then you can start irb session to see it in action.

Include the cycr gem first

require 'cycr'

Create a cyc client object, default host: localhost, port: 3601

cyc = Cyc::Client.new

Check if Dog generalizes to Animal

cyc.genls? :Dog, :Animal # => true

Check if Animal generalizes to Dog

cyc.genls? :Animal, :Dog # => nil

Check the minimal generalizations of Animal

genls = cyc.min_genls :Animal
# => [:"Organism-Whole", :"PerceptualAgent-Embodied",
#  :"Agent-NonArtifactual", :SolidTangibleThing, [:CollectionUnionFn,
#  [:TheSet, :Animal, [:GroupFn, :Animal]]],...

Check the maximal specializations of the first of the above results

cyc.max_specs genls.first
# => [:Microorganism, :EukaryoticOrganism, :"Unvaccinated-Generic",
#  :"Vaccinated-Generic", :MulticellularOrganism, :Heterotroph, :Autotroph,
#  :Lichen, :TerrestrialOrganism, :Animal, :AquaticOrganism, :Mutant,
#  :Carnivore, :Extraterrestrial, :"Exotic-Foreign",...

It works with NARTs (but I didn’t tested this functionality extensively, so this might cause some problems - beware):

genls[4]
# => [:CollectionUnionFn, [:TheSet, :Animal, [:GroupFn, :Animal]]]

cyc.max_specs genls[4]
# => [:Animal, [:GroupFn, :Animal]]

What is more, you might even build complex subcalls, such as:

cyc.genls? :Person, :HomoSapiens # => nil
cyc.with_any_mt{|cyc| cyc.genls? :Person, :HomoSapiens} # => true

The assertions are parsed, as well as Cyc symbols and variables

keys = cyc.key_predicate_rule_index :isa
# => [:POS, :NEG]
keys[0].class
# => Cyc::Symbol
cyc.symbolp keys[0]
# => true

keys1 = cyc.key_predicate_rule_index :isa, keys[0]
# => [:ComputerRunningMt, :HumanManipulationMt, :BuyingMt, ...
keys2 = cyc.key_predicate_rule_index :isa, keys[0], keys1[2]
# => [:BACKWARD]
rules = cyc.gather_predicate_rule_index :isa, keys[0], keys1[2], keys2[0]
# => [[:implies, [:and, [:objectOfPossessionTransfer, :TheBuying, ?OBJ],
#     [:activityObjectType, :TheSelectingAProduct, ?PREFERED]],
#     [:isa, ?OBJ, ?PREFERED]] : BuyingMt]
cyc.assertion_p rules[0]
# => true

rules[0].formula[1][1][2]
# => ?OBJ
rules[0].formula[1][1][2].class
# => Cyc::Variable

The variable cannot be checked for type, since it won’t be bound.

If you want to see the query which is send to Cyc, just turn on debugging:

cyc.debug = true
cyc.genls? :Dog, :Animal
# Send: (genls? #$Dog #$Animal)
# Recv: 200 T
# => true

The same way, you can turn it off:

cyc.debug = false

Remember to close the client on exit

cyc.close

By default a Cyc client uses regular TCP socket communication and is not thread safe. To turn-on thread-safety pass a thread_safe option to the constructor:

cyc = Cyc::Client.new(:thread_safe => true)

Alternatively you can use a client with fibers and Event Machine synchrony To set-up event machine driver before requiring cycr:

require 'cyc/connection/synchrony'
require 'cycr'

Make sure that you have ‘em-synchrony’ gem installed. A sample code looks as follows:

EM.synchrony do
  cyc = EM::Synchrony::ConnectionPool.new(size => 5) do
    Cyc::Client.new :url => 'cyc://localhost:3601', :debug => true
  end
  Fiber.new do
    puts "Ani", cyc.fi_complete("Ani").inspect
  end.resume
  puts "Mi", cyc.talk('(fi-complete "Mi")').inspect
  EM.stop
end

‘Mi` will arrive before `Ani`

Warning: always use EM::Synchrony::ConnectionPool to handle Fiber concurrency race conditions.

LICENSE:¶ ↑

(The MIT/X11 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.

FEEDBACK¶ ↑

apohllo@o2.pl

apohllo/cycr