OpenCog shell

From OpenCog
Jump to: navigation, search

This page describes how to run the OpenCog shell. Examples on how to use subsystems, including the scheme shell, and a python shell, can be found in their respective pages.

Configuration file

The /lib/opencog.conf is loaded by default when you start the cogserver. For development purposes, that is when running from the build directory without installing, /lib/development.conf file is prefered. There might be other additional sections or some of the sections below may be missing depending on the type of configuration file being used.

The long-term plan is to avoid the use of the configuration file, and possibly remove it completely, one day. Maybe. Configuration files have multiple problems:

  • The are ignored, if you don't run the CogServer, and many important subsystems in OpenCog do not use the CogServer. The CogServer itself is likely to go away or be replaced.
  • The configuration file can only be loaded once, on cogserver startup; there is no way to reload it.
  • There is no way to change the values of configured parameters. For example, one might want to change, during run-time, most or all of the ECAN parameters below. One might be able to do this by providing scheme or python bindings for them. Putting them in the config file means that you have to stop everything to change them. Sometimes, this is inconvenient. More often, this is a fatal design flaw.
  • The config file is a key-value store. The AtomSpace is a key-value store. Do we really need two different types of key-value stores?

Thus, for this reason, system developers are strongly discouraged from adding new config parameters. If you've got a parameter, write a scheme or python API for it.

More generally, OpenCog has an unsolved system management problem. We want to provide users with some way of starting and stopping various different subsystems, possibly on a distributed network of machines. We want to be able to easily find and load the correct dataset or datasets (the "memories" and "knowledge" of the system), to checkpoint the system, in case it crashes, and to save partial or final results. We want to manage the configuration of the system. We want to allow the user to make sure that the appropriate systems are not starved for CPU time, and to monitor overall system performance. Finally, large parts of this need to be automated and automatable, so that the attention allocation subsystem can control overall resource scheduling. The config file is one small piece of this more general problem: a need for managing and controlling the system.

Default contents

The default contents are as follows:

  • The section below specifies the default port that the Cogserver will be running on and where it will write log entries to.
#
# This file provides an example configuration for a production OpenCog
# server. Particularly noteworthy is the list of automatically loaded
# modules.
#
SERVER_PORT           = 17001
LOG_FILE              = /tmp/cogserver.log
  • The logging section allows you to change the granularity of logging. You will be using the 5 variations here when you write logging code. For most purposes, 'debug' or 'info' should suffice. You can use SERVER_CYCLE_DURATION to give agents more time to complete their work. The IDLE_CYCLES_PER_TICK setting is used to change the frequency with which an agent's Run() function is called.
# Other possible log levels are "error", "warn", "info", "debug" and "fine"
# LOG_LEVEL             = debug
LOG_LEVEL             = info
LOG_TO_STDOUT         = false
SERVER_CYCLE_DURATION = 100
IDLE_CYCLES_PER_TICK  = 3
  • Command prompt settings
# Use the commented PROMPT instead if telnet/terminal doesn't support ANSI
PROMPT                = "opencog> "
# Prompt with ANSI color codes
ANSI_PROMPT           = "�[0;32mopencog�[1;32m> �[0m"
# Global option so that modules know whether they should output ANSI color
# codes
ANSI_ENABLED	      = true
  • This section loads a number of modules which add extra features to the OpenCog shell environment. If you find that the command list that is shown from the Opencog shell when you type 'help' is shorter than normal you may have commented some of them out.
# Cogserver in OSX will automatically change .so extension to .dylib
# if .so exists.
MODULES               = opencog/cogserver/server/libbuiltinreqs.so,
                        opencog/cogserver/shell/libscheme-shell.so,
                        opencog/cogserver/shell/libpy-shell.so
  • The following are the settings for economic attention allocation(ECAN). This is used to distribute attention (processor time) between the various agents that may be running simultaneously.
# Economic Attention Allocation parameters
STARTING_STI_FUNDS    = 10000
STARTING_LTI_FUNDS    = 10000
STI_FUNDS_BUFFER      = 10000
LTI_FUNDS_BUFFER      = 10000
MIN_STI               = -400

ECAN_MAX_ATOM_STI_RENT      = 15
ECAN_STARTING_ATOM_STI_RENT = 10
ECAN_STARTING_ATOM_LTI_RENT = 0
ECAN_STARTING_ATOM_STI_WAGE = 2
ECAN_STARTING_ATOM_LTI_WAGE = 2

#Used by ImportanceDiffusionAgent class
#0 => flat rent, 1 => exp rent, 2 => log rent, 3 => linear rent
ECAN_RENT_TYPE              = 0
ECAN_RENT_AMNESTY           = 5
ECAN_RENT_EQUATION_PARAMETER_0 = 0.05
ECAN_RENT_EQUATION_PARAMETER_1 = 0.0

#End of ImportanceDiffusionAgent class

#Used by SimpleImportanceDiffusionAgent class
#Maximum percentage of STI that is spread from an atom
ECAN_MAX_SPREAD_PERCENTAGE = 0.6

# If false, will diffuse along hebbian links only. If true,
# will also diffuse to all non-hebbian incident atoms in the
# incoming and outgoing sets
ECAN_SPREAD_HEBBIAN_ONLY = false

# Maximum percentage that will be available for diffusion to hebbian links
HEBBIAN_MAX_ALLOCATION_PERCENTAGE = 0.5
ECAN_CONVERT_LINKS = false
ECAN_CONVERSION_THRESHOLD = 15

# spread deciding function type (HPERBOLIC = 0 and STEP = 1 )
SPREAD_DECIDER_TYPE = 1
#END of SimpleImportanceDiffusionAgent params

#ForgettingAgent params
ECAN_FORGET_PERCENTAGE = 0.001

#END of Economic Attention Allocation parameters
  • The rest of the section deals with various configurations for different modules.
#
# The sense-similarity tables hold precomputed values or the similarity
# of word WordNet-3.0 senses. These tables are referenced in
# nlp/wsd/SenseSimilaritySQL.cc  These will *eventually* be replaced by
# a persistent opencog table of sense similarities. For now, they remain
# in use.
#
SENSE_SIMILARITY_DB_NAME          = "lexat"
SENSE_SIMILARITY_DB_USERNAME      = "linas"
SENSE_SIMILARITY_DB_PASSWD        = "asdf"

# Parameters for ZeroMQ AtomSpace Event Publisher
ZMQ_EVENT_USE_PUBLIC_IP = TRUE
ZMQ_EVENT_PORT = 5563

# Parameters for RuleEngine
# RULE_ENGINE_TRIGGERED_ON = [1 ,2 ,3]
# 1-when atom added 2-when atom enters to AF 3-both on 1 and 2
RULE_ENGINE_TRIGGERED_ON = 1

Starting Cogserver

Assuming you have cloned OpenCog repository in the ~/src/opencog folder of your home directory, and that you have successfully built it inside ~/src/opencog/build, in a new terminal window run

cd ~/src/opencog/build
./opencog/cogserver/server/cogserver -c ../lib/development.conf

This loads the CogServer with the development configuration file development.conf.

You should see the following output by default

Listening on port 17001
...
...

Connecting to Cogserver

The CogServer, by default, listens for telnet connections on port 17001. After Starting cogserver, to connect to it run from a separate terminal window

telnet localhost 17001

Optionally to enable readline, which enables you to edit the shell's history run:

rlwrap telnet localhost 17001

which assumes that rlwrap is installed on your machine.

You should be presented with:

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
opencog>

Run "help"<enter> to get a list of commands. If the list of commands is shorter than the one shown below, some of the modules may not have been loaded due to changes in opencog-configuration-file or the modules may have been deprecated.

Available commands:                                                                             
  agents-active:      List running agents                                                       
  agents-list:        List available agents                                                     
  agents-start:       Start some agents                                                         
  agents-start-loop:  Start the agent loop                                                      
  agents-step:        Run a single cycle of an agent(s)                                         
  agents-stop:        Stop some agents running                                                  
  agents-stop-loop:   Stop the agent loop                                                       
  help:               List the available commands or print the help for a specific command      
  list:               List atoms in the atomtable                                               
  listmodules:        List the currently loaded modules                                         
  loadmodule:         Load an opencog module                                                    
  loadpy:             Load commands and MindAgents from a python module                         
  py:                 Enter the python shell                                                    
  py-eval:            Run some python code                                                      
  pyshell.shell:      OpenCog IPython Shell                                                     
  quit:               Close the shell connection                                                
  scm:                Enter the scheme shell                                                    
  shutdown:           Shut down the cogserver                                                   
  sleep:              Sleep for the number of given seconds (default: 5 seconds)                
  sql-close:          Close the SQL database                                                    
  sql-load:           Load contents of SQL database                                             
  sql-open:           Open connection to SQL storage                                            
  sql-store:          Save the atomtable on the SQL database                                    
  unloadmodule:       Unload an opencog module                                                  
  zmq-close:          Close the ZeroMQ persistence                                              
  zmq-load:           Load contents of ZeroMQ persistence                                       
  zmq-open:           Open connection to ZeroMQ persistence                                     
  zmq-store:          Save the atomtable on the ZeroMQ persistence                              

To get information about any of the commands, use "help <name of command>". For examples

opencog> help scm                                                              
Usage: scm [hush|quiet|sync]                                                   
                                                                               
Enter the scheme interpreter shell. This shell provides a rich                 
and easy-to-use environment for creating, deleting and manipulating            
OpenCog atoms and truth values. It provides a full R5RS-compliant              
interactive scheme shell, based on the GNU Guile extension language.           
                                                                               
If 'hush' or 'quiet' is specified after the command, then the prompt           
will not be returned.  This is nice when catting large scripts using           
netcat, as it avoids printing garbage when the scripts work well.              
If 'sync' is specified after the command, then the output is sync,             
instead of async.                                                              

Monitoring Cogserver

By default, the Cogserver will write log entries from the different running cogosever-modules to the file /tmp/cogserver.log. Some of the running modules may have their own log files, refer to their respective documentations for details.


To keep an eye on the log file, start a new Terminal window and run Then navigate to the /tmp folder

 
tail -f /tmp/cogserver.log

You should see some output similar to the following:

opencog@f9dccac8949a:/opencog/build$ tail /tmp/cogserver.log 
[2016-02-23 09:16:27:289] [INFO] Loaded /usr/local/share/opencog/scm/utilities.scm
[2016-02-23 09:16:27:295] [INFO] Loaded /usr/local/share/opencog/scm/apply.scm
[2016-02-23 09:16:27:300] [INFO] Loaded /usr/local/share/opencog/scm/file-utils.scm
[2016-02-23 09:16:27:300] [WARN] Failed to load file scm/persistence.scm: 2 No such file or directory
[2016-02-23 09:16:27:305] [INFO] Loaded /usr/local/share/opencog/scm/config.scm
[2016-02-23 09:16:27:317] [INFO] Loaded /usr/local/share/opencog/scm/repl-shell.scm
[2016-02-23 09:16:27:323] [INFO] Loaded /usr/local/share/opencog/scm/av-tv.scm
[2016-02-23 09:16:27:329] [INFO] Loaded /usr/local/share/opencog/scm/rule-engine-utils.scm
[2016-02-23 09:16:27:335] [INFO] Loaded ..//opencog/cogserver/scm/config.scm
[2016-02-23 09:16:27:336] [INFO] Starting CogServer loop.