OpenCog Python Client
Defines an interface to allow OpenCog experiments to be written as short Python scripts.
Functionality
- Control an OpenCog server on your local machine or on a Vagrant box
- Control a RelEx server on a Vagrant box (local machine functionality not yet added)
- Start and stop the OpenCog server
- Start and stop the RelEx server
- Interact with the RelEx and RelEx2Logic NLP pipelines with single Python commands
- Control the steps of each mind agent
- Capture the contents of the attentional focus at each step in Scheme format
- Capture the discrete dynamical evolution of the attentional focus
- Capture the discrete dynamical evolution of the STI of each atom in the attentional focus
- Store the captured data as a timeseries in a CSV file for plotting and analysis (using pandas, matplotlib, SciPy, etc.)
- Render the captured data as a sequence of graphical visualizations of the attentional focus
Requirements
-
Requires the REST API to be configured as described here and installation of the requests library
-
For full functionality, you should also install PyMongo, MongoDB and GraphViz
Example usage
IPython Notebook examples
The recommended way to learn how to use python-client is with IPython Notebook. An example demonstration is provided that combines documentation, interactive code execution, and graphical visualizations.
Simple example
A simple example can be viewed online here.
NLP demo
An NLP demo can be viewed online here.
Note that the online versions are not interactive, whereas on your own machine they will be interactive.
To run the example on your machine, you will need to install IPython Notebook first.
Then, run ipython notebook from the command line in this folder, and then open the notebook named example.ipynb
Additional examples
See the usage example in example.py
Also see an example visualization of the attentional focus dynamics as a slideshow of PNG images rendered from DOT representations in graphics.py
Vagrant (optional)
Note: These instructions are optional and only apply if you are planning to use Vagrant.
The Client API can be used with Vagrant. For example, you can run the OpenCog daemon inside a virtual machine, and then do all of your Python development in Mac OS.
To set up OpenCog in this manner, follow these instructions: http://wiki.opencog.org/w/Building_OpenCog_in_a_Linux_Virtual_Machine_on_Mac_OS_X
Then, install the Python packages python-vagrant and fabric.
Then, to use the Client API with Vagrant, open the file configuration.py and set the parameter USE_VAGRANT to True and VAGRANT_ID to the ID of your VM (you can find this using the command vagrant global-status)
OpenCog Python Client API Documentation
The client API has docstrings for each method that describe correct usage. A summary of the available methods is presented below.
Server
Before performing operations with OpenCog, you need to have an instance of a Server object:
import opencog
server = opencog.Server()
server.start()
start()
Bootstraps the OpenCog CogServer daemon so that it will run in the background with the
REST API so that further commands can be issued by sending them to the REST API
stop()
Terminate the OpenCog CogServer daemon
Operations
After you have started a Server, you can perform the following operations.
create_point(timestep, atoms, scheme=None)
Create a PointInTime dictionary from a JSON atom representation
Represents a discrete point in time in a time series from an experiment
with the ECAN attention allocation discrete dynamical system
Each point in time contains:
- a list of "atoms" which consists of a list of objects of type Atom
(Refer to the definition of the Atom object)
- an integer "timestep"
- (optional) A Scheme representation of the point in time
shell(command)
Send a command to the CogServer shell
scheme(command)
Send a Scheme command to the Scheme interpreter
load_scheme_files(files)
Loads a list of Scheme files into the cogserver
load_python_agent(path)
Load an arbitrary Python MindAgent in the CogServer
Parameters:
path (required) Relative path to the agent, including the filename,
without the file extension
Example of 'path':
../opencog/python/pln/examples/tuffy/smokes/smokes_agent
start_python_agent(path, name)
Start a Python MindAgent that has already been loaded
Parameters:
path (required) Relative path to the agent, including the filename,
without the file extension
Example of 'path':
../opencog/python/pln/examples/tuffy/smokes/smokes_agent
name (required) Name of the agent
Example of 'name':
InferenceAgent
step_agent(name)
Run a step of an arbitrary C++ agent in the CogServer
Parameters:
name (required) Name of the agent
Example of 'name':
SimpleImportanceDiffusionAgent
step_python_agent(path, name)
Run a step of an arbitrary Python agent in the CogServer
Parameters:
path (required) Relative path to the agent, including the filename,
without the file extension
name (required) Name of the agent
Example of 'path':
../opencog/python/pln/examples/tuffy/smokes/smokes_agent
Example of 'name':
InferenceAgent
get_attentional_focus(timestep, scheme=False)
Get the atoms in the attentional focus
Parameters:
timestep (required) You should provide a monotonically increasing timestep
value to uniquely identify the timestep of this attentional focus
snapshot.
scheme (optional) If True, the Scheme representation of the attentional
focus will also be captured. Default is False.
get_atomspace(timestep, scheme=False)
Take a snapshot of the atomspace at a given point in time
:param timestep: an integer representing a monotonically increasing
timestep value which identifies the timestep of this atomspace snapshot
:param scheme: If True, the Scheme representation of the atomspace will
also be captured.
:return: a PointInTime dictionary that captures the atomspace at the given
timestep
atomspace()
Retrieves a snapshot of the atomspace. Take note that the snapshot returned
is static, and must be called again when you want it to be updated.
:return: a dictionary of atoms
export_timeseries_csv(timeseries, filename, scheme=False)
Export the timeseries to a CSV file.
Parameters:
timeseries (required) The timeseries that will be exported.
filename (required) The name of the file that will be written to.
scheme (optional) If True, the full Scheme representation of the point in
in time will be included with each row. Defaults to False.
Format:
time, handle, sti
If the timeseries contains a Scheme representation, the format is:
time, handle, sti, scheme
export_timeseries_mongodb(timeseries)
Export the timeseries to a MongoDB database.
Parameters:
timeseries (required) The timeseries that will be exported.
dump_atomspace_scheme()
Returns all atoms in the atomspace in Scheme format
dump_atomspace_dot()
Returns all atoms in the atomspace in DOT graph description language
format
dump_attentional_focus_scheme()
Returns all atoms in the attentional focus in Scheme format
clear_atomspace()
Clear the atomspace
stop_agent_loop()
Stop the automatic stepping of agents in the CogServer, so that agents
can be stepped manually
set_af_boundary(value)
Set the AttentionalFocusBoundary
Parameters:
value The STI value to set the AttentionalFocusBoundary to
importance_diffusion()
Run a step of the simple importance diffusion agent
importance_updating()
Run a step of the importance updating agent
hebbian_updating()
Run a step of the hebbian updating agent
forgetting()
Run a step of the forgetting agent
clear_mongodb()
set_diffusion_percent(value)
Sets the diffusion percentage parameter for the importance diffusion agent
value is a probability value between 0 and 1 representing the percentage
of an atom's STI that should be diffused at each step
set_stimulus_amount(value)
Sets the stimulus amount parameter for the PLN reasoning agent
value is an Integer value representing the amount of stimulus to be assigned to the target
set_rent(value)
Sets the rent parameter for the attention allocation importance updating agent
value is an Integer value representing the amount of stimulus to be assigned to the target
set_wages(value)
Sets the wages parameter for the attention allocation importance updating agent
value is an Integer value representing the amount of stimulus to be assigned to the target
class Atom(object)
Stores an atom handle and an STI value
Represents the STI value of an atom at a particular point in time.
Intended to be contained in a PointInTime object with a timestep value.
RelEx Server
Before performing operations with RelEx, you need to have an instance of a RelExServer object:
import opencog
relex_server = opencog.RelExServer()
relex_server.start()
The following operations are available after starting a RelExServer:
start()
Bootstraps the RelEx server daemon so that it will run in the background with the
socket API so that further commands can be issued by sending them to the socket API
stop()
Terminate the RelEx server daemon
Operations
relex(sentence, display=True, concise=True)
Interface to RelEx. Requires a RelExServer to be running.
:param sentence: The sentence to send to RelEx for parsing
:param display: Whether to print the output (default=True)
:param concise: Whether to strip status messages from the output (default=True)
:return: Human-readable parse of the sentence
to_logic(sentence, clear=True, display=True)
Interface to Relex2Logic. Requires a Server and a RelExServer to be running.
:param sentence: The sentence to send to RelEx2Logic for parsing
:param clear: Whether to clear the atomspace before processing (default=True)
:param display: Whether to print the output (default=True)
:return: Contents of the SetLink representing the parsed sentence
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent