Getting Started with ErgoAI




What is the ErgoAI platform?

A uniquely advanced knowledge management system for representing and reasoning with knowledge that is logical, object based, linguistic (e.g., English text), or otherwise structured.  
  • Ergo includes:  
    • ErgoAI Studio:  an Integrated Development Environment (IDE) component, with tools for knowledge editing, querying, explaining, and debugging, plus execution monitoring of reasoning.   
    • Ergo Reasoner (or ErgoAI Reasoner or just Ergo): the component that performs the actual reasoning tasks.  Reasoning is primarily query-oriented but it also does smart caching of previous work.     
    • XSB: a low-level reasoning component that supports Ergo Reasoner.
    • APIs: interfacing to other systems (e.g., databases), formats (e.g., JSON, XML, OWL), and languages (Java, Python).   ErgoAI is built in Java, C, and itself. 
    • See Platform Architecture and Technical Approach for more details and an architecture diagram.
  • Ergo provides:
    • Very high logical expressiveness, including higher-order, defeasibility, quantifiers, head disjunction, probabilistic uncertainty, bounded rationality, provenance, and other strong meta. 
    • Efficient dynamic automated reasoning capabilities.  Reasoning is fundamentally computationally scalable despite the very high expressiveness, similar qualitatively to database querying. 
    • Fully detailed user-navigable explanations in English.
  • Ergo is fully semantic (or "declarative"in the sense of AI) and implements reasoning for the logic Rulelog -- a significant expansion of Datalog and declarative logic programs, the logics for which databases and most "business rule" systems implement reasoning.  


The History of ErgoAI

  • ErgoAI is a commercial product that originates in the open source Flora-2 research system, created originally by Guizhen Yang and Michael Kifer at Stony Brook University.
  • Many features were subsequently added by Michael Kifer's students.  Full acknowledgements can be found in the Flora-2 manual available at flora.sourceforge.net.
  • Further contributions were made by the team of researchers in the SILK research program funded by Vulcan Inc. during 2008--2013, led by Benjamin Grosof.
  • ErgoAI is Coherent's greatly enhanced and commercially supported product.


Bug Reporting

To set up a Bugzilla account, please contact  info@coherentknowledge.com.
One needs a https://bitbucket.org/  account to report issues there.  We will try to address these issues in new releases of Ergo.


Manuals for ErgoAI

The following manuals are available via the Help menu of the Ergo Listener window after you start ErgoAI Studio and on the Coherent Knowledge website :
  • A Guide to ErgoAI Packages:  covers connectors to external information sources and systems, such as Java, SQL, SPARQL, RDF/OWL, tabular data, JSON, etc.
  • ErgoAI Studio Manual:  Explains how to use the graphical UI and the Integrated Development Environment (IDE).
  • Also relevant is the XSB User Manual, which is recommended for experts only.


ErgoAI Installation

ErgoAI comes in three main flavors:

  • Regular
Can be installed only on physical machines. Once installed and activated, the software is locked to that particular machine.  Trial versions are regular versions that can be used for free for three months without activation. After that, the copy must be activated with a valid license key or else it will refuse to work.
  • VM
A VM version can be installed on a regular or a virtual machine. No trial versions are available with this option. Like the regular copy, a VM version is locked to a particular virtual machine and will not work on the cloud (e.g., Amazon's AWS, Microsoft's Azure, Google Cloud) or in containers (e.g., Docker). For this, one needs the cloud version of Ergo.  (Note: the VM version will install and activate on the cloud, but the next time you log into the cloud the activation will be gone and -- worse -- you will not be able to deactivate the copy to reuse the license key.)
  • Cloud
A cloud version can be installed on a cloud, in a container, or on a regular or virtual machine. Not trials are available for this option. The installation is slightly more complex, as it requires first installing a license server on a separate physical machine (which can be any old machine that is accessible from the client machine).

The instructions below apply to regular and VM copies. Cloud version installation is describes on this page.


Windows

    • Download the file  ErgoAI.exe  from the location you received from Coherent customer support.
    • Close any other running copy of ErgoAI (or of Ergo Suite -- the previous incarnation of he system).
    • Double clicking on  ErgoAI.exe  will open the Coherent ErgoAI Setup Wizard.  Follow the prompts to install ErgoAI.
Note: During the installation you will be asked to choose a folder in which to install Ergo. It is required to choose a directory for which you have both read and write privileges.  Therefore, it is recommended to choose a directory owned by your account. If you choose  Program Files  or some other system directory, your account would need to have administrative privileges not just during the installation but also each time you use Ergo.
    • Your desktop will now have two icons for two ErgoAI shortcuts. One icon is for starting ErgoAI Studio, the graphical IDE for Ergo; the other (that has a small black DOS window in it) is for starting Ergo on command line in a DOS window.
    • A note on anti-virus software:  During installation, your anti-virus software may ask you to 'Trust' the file. Please follow instructions to do so.  If at any time after installation ErgoAI Studio fails to start, the anti-virus software may again be involved. It may be necessary to 'Trust' the file again even if it had been previously trusted by the user.
We have heard reports of this problem with Norton Anti-virus products in particular.  To fix this, navigate to the runErgoAI.exe file in your ErgoAI installation, which is typically located at C:\Users\YourUsername\Coherent\ErgoAI\runErgoAI.exe
If you are using a Norton anti-virus product, right-click on the file and select ‘File Insight’ then ‘Trust’ the file. 
    • A note on the .jar-to-Java association: Check that .jar files are associated with Java, so that double-clicking on such files opens them with Java (Java must be already installed). If this is not the case, change the association (right-click on a .jar file and select "Open With").
In 99.9% of the cases the association is already correct, but if double-clicking on the Ergo icon opens something other than Ergo then fixing the .jar-to-Java association will solve that problem.

Linux and Mac OS X

    • Download the file ergoAI.run from the location you received from Coherent customer support.
    • Move it to the installation directory of your choice.
    • Type
sh ergoAI.run
    • Answer the prompts. At the end of the process, you will be given the path names to use in order to run ErgoAI Studio as well as the command line version of Ergo. These path names have the following structure:
                            the folder where you ran the "sh ergoAI.run" command/Coherent/runErgoAI.sh
                            the folder where you ran the "sh ergoAI.run" command/Coherent/Ergo/runergo

        The first is to be used for running the ErgoAI Studio GUI, while the latter is for running Ergo engine on command line (in a terminal).

Note 1:  ErgoAI requires read, write, and execute permissions on all sub directories of  the folder where you ran the "sh ergoAI.run" command/Coherent/ for all users who are going to be using ErgoAI. If you are installing ErgoAI in your home directory then the permissions will be set automatically. However, if you are installing it elsewhere, like in /opt/, then these permissions might have to be set manually after the installation. For instance:

chmod -R g+rwX   /opt/Coherent/

will set the right permissions for all users who are in the same user group as the  .../Coherent/  folder.  (One can also use a+rwX instead of g+rwX, but this will give the permissions to everybody, which may not be a good idea.)

Note 2: Normally, Ergo creates a directory called
.xsb in the user's home directory: $HOME/.xsb. If you are using Ergo via the account that was also used to install ErgoAI, nothing needs to be done. However, if the usage account differs from the installation account (which is often the case with servlets and other nologin usage accounts) then it is necessary to tell Ergo where it can create the .xsb directory via the environment variable XSB_USER_AUXDIR. The location must have the rwx permissions for the usage account. For instance, 

export XSB_USER_AUXDIR=/opt/Coherent/ErgoAI/.xsb

    • Desktop icons:  Two desktop icons (ErgoAI IDE and ErgoAI Terminal) are normally installed if:
      • Linux:  the user has a desktop environment that is LSB (Linux standard) compliant.
      • Mac:  Mac Developer Tools are installed (see below).
On the Mac, one might have to reboot in order for the Ergo icons to display the right pictures.


Prerequisites for Linux/Mac installation
:

Linux systems: Ubuntu, Mint, Fedora, SUSE, etc., are likely to be ready for installation out of the box unless they are configured in unusual ways.  Verify that the utility make and the gcc compiler are installed (using the system's package manager).

Also check these optional items. 
      • MySQL, UnixODBC and MyODBC developer's packages. These are required for database connectivity. Note that here we need developer's packages. These packages usually have names like unixODBC-devel, unixodbc-devMySQL-devel, mysql-clientmysql-connector-odbcor similar.  Use your system's package manager to find if these packages are installed (and the packages' exact names) and install them if not.
      • The package pcre-devel, libpcre-devel, libpcre++-dev or a similarly named package -- needed if one wants to use Perl-style regular expressions.
      • The package curl-devel, libcurl-devel, libcurl4-openssl-devor similar -- install if fetching remote Web pages is going to be needed.
      • The package rlwrap is useful for the overall experience with the Ergo engine in a non-Studio (terminal) mode. This package provides command history, which can be browsed via the Up/Down arrows on the keyboard.

                 Macs:  Ergo under MacOS requires Xcode to be installed. This can be done as follows:

      • Go to the Mac Apps store, find Xcode, click "Get" then "Install App" (Xcode is free and is an optional part of MacOS).
      • After Xcode please also install the Xcode command line tools:
        • Open Terminal (in  the /Macintosh HD/Applications/Utilities  folder)
        • Type  xcode-select --install  then hit <Enter>
(Note: if you upgrade MacOS,  Xcode must also be updated by re-running the above command.)

A number of optional Ergo packages need additional software to be installed through a package manager called Homebrew. To install Homebrew, perform the following steps:
  • Open the Terminal application
  • Type  ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"   then hit <Enter>
  • Type brew doctor to verify that the installation was successful.
The following optional packages used by ErgoAI can be installed via Homebrew. All the commands below must be typed into a terminal window:
  • brew install rlwrap   -  provides command history for the Ergo engine in the non-Studio (terminal) mode; the history can be browsed using the Up/Down arrows on the keyboard.
  • brew install pcre  -  used by the Ergo pattern matching package.
  • brew install curl  -  used for the Web access.
  • brew install unixodbc  -  used for database connectivity.
The MySQL ODBC driver has a number of problems interfacing with MySQL 5.7 on Linux and MacOS, so  MySQL 5.6 is recommended instead.

Security Issues (optional)

Before installing any software downloaded from the Internet, it is generally advisable to verify the integrity of the downloaded software.

For Windows, the ErgoAI installer is signed with a Coherent Knowledge certificate, which you should see at the beginning of the installation.

For Linux and Mac, a common method is to provide a cryptographically signed checksum of the downloaded file. Verifying the checksum ensures that the file was not tempered with and that is comes from Coherent Knowledge. The first step of this optional procedure is very simple. The second step is also optional and simple, but it may require preliminary set up the first time.

Step 1: Verifying the checksum of ergoAI.run (optional, Mac/Linux only)

Download the file ergoAI.run.sha256.sum, which was linked from the email message that you received together with the link to ergoAI.run and put it in the same folder as ergoAI.run. This file contains the SHA256 checksum of your ErgoAI download.
Next, open a terminal window, change to the aforesaid folder, and run this command:
shasum -c ergoAI.run.sha256.sum
You should see:
ergoAI.run: OK
The shasum command is available both in Linux and Mac OS X.


Step 2: Verifying the signature of ergoAI.run.sha256.sum (optional, Mac/Linux only)

One might also want to optionally and additionally verify that the checksum in ergoAI.run.sha256.sum was really generated by Coherent Knowledge. To this end, download the file ergoAI.run.sha256.sig that was linked from the email message you received together with the link to ergoAI.run. It has the same content as  ergoAI.run.sha256.sum  but it is signed by Coherent Knowledge Systems using Coherent's secret key for Gnu Privacy Guard (GPG).

For that, you need GPG installed and you also need to download our GPG public key from public keyservers such as

and others. To install GPG, use your package manager in Linux and Homebrew on the Mac. To find Coherent's GPG public key on a public keyserver, search for "Coherent Knowledge Systems" in the provided search field.

Next import this key using this command (assuming that you placed the Coherent's public key in the file CoherentPublic.asc in the same folder as the other two files):

    gpg  --import  CoherentPublic.asc

Downloading the Coherent's key and its import is to be done only once: next time you download Ergo, you can skip the above steps.

Now, you are ready to verify that the checksum was really created by Coherent:

    gpg  --default-key  "Coherent Knowledge"  --verify  ergoAI.run.sha256.sig  ergoAI.run.sha256.sum

You should see something like this:

    gpg: Signature made ..... using RSA key ID 12650718

    gpg: Good signature from "Coherent Knowledge Systems, LLC ....."


Uninstallation

Windows: When a new version of ErgoAI is installed, the old version is normally uninstalled. If this does not happen or if one needs to remove the system from a computer, uninstallation can be done via the Windows Control Panel.

Linux/Mac:  On these systems, an old version of ErgoAI would also be uninstalled automatically, but only if the new version is installed in the same location.   If the new version is installed in a different location, removing an old installation is done by navigating to the old installation folder and removing the folder  Coherent/ErgoAI/.

Uninstalling Ergo Suite: If you are switching from Ergo Suite to ErgoAI, the old system (Ergo Suite) will not be uninstalled automatically and one must do it manually. In Windows: use the Control Panel. In Linux or Mac, navigate to the installation directory and (a) remove the folder Coherent/ErgoSuite/;  (b) in Linux, also remove the desktop icons of the old system (in Mac, they should disappear once (a) is done).

Starting the ErgoAI System

Ergo can start either in the studio mode, as part of the ErgoAI Studio IDE (suitable for development), or as a command line application. The latter is preferable for already finished Ergo applications. We explain both methods here. In Windows, there would be two icons on your desktop -- one for the studio and one for the command line. In Linux and Mac, as already mentioned, such shortcuts can be easily created manually or one can run the two versions of Ergo via the commands shown after the installation.

  • To start as part of the IDE:  Double-click on the desktop ErgoAI icon or start menu to open Studio in Windows. In Linux and Mac, use either the icons or the file name for the studio, which was given to you after the installation. This will open up the Ergo Listener window, which can be used to type in command or start other activities, like creating and editing Ergo files.
  • To start as a command line application: Use the appropriate desktop icons or use the commands shown at the end of the installation.
There is a slight delay when Ergo starts the first time after installation, as it performs the necessary configuration tasks. There is also a slight (1-3 second) delay the first time some features of Ergo are used (after installation). The delay goes away on subsequent uses.

Activating your Copy of ErgoAI

Free trial copies of ErgoAI are valid from the moment of first use for a period of 90 days. They do not require activation and when the trial expires the copy is disabled. Once a trial expires, neither this nor any other copy of ErgoAI will work on the same computer unless the trial is extended or a commercial license is purchased.

To activate a purchased copy of ErgoAI, you must have a valid license key obtained from Coherent.  An unactivated copy will not allow the user to use most of the functions after a short while. To activate:

  • Start Ergo -- on command line or in ErgoAI Studio.
  • In the studio:  select the Help > Activate Ergo license menu or type activate{}. into the listener input area. Then enter your license key into a dialog box.
  • On command line: type activate{}.  at the prompt, hit <Enter>, and then enter your license key.  
  • Note that in the  activate{} command one must:
    • use curly braces, not parentheses
    • terminate the command with a period, then hit <Enter>.
An activated copy of Ergo can be deactivated with the  deactivate{}.  command.  This is useful if one wants to transfer the license from one machine to another. The ErgoAI Studio Manual has more details on that.


ErgoAI Studio's IDE

The ErgoAI Studio's IDE is normally used for development of Ergo knowledge bases, as it provides extensive support for that. However, it also has the "Listener" window, which can be used to enter Ergo commands and queries similarly to what one would do when Ergo runs as a command line application.  For more details on using the ErgoAI Studio's IDE, see the ErgoAI Studio Manual.  A short description of how to do some of the more common tasks is given below.

  • To edit a new file, from the Ergo listener window, File > New > Ergo File, creates a new Ergo or Prolog file in the Editor window (or Alt-F  Ctrl-N).
    • Use  File > Save As … to name the new file.  You must include the ‘.ergo’ extension for Ergo files.
  • To open an existing file, use File > Open (or Alt-F Ctrl-O)
  • To load a file into the engine, use File > Load, from either the Listener or Editor window. 
    • The file is loaded by default to the ‘main’ module.  
    • The editor window will indicate which module the file is loaded into.
    • When a file is loaded, it automatically clears previous files in the module (if the module is not specified, the default is main).
    • Modules can be used to organize large sets of rules.  For more on modules, see section 16 in the ErgoAI Reasoner User's Manual.
  • To add a file to a module, use File > Add, from either the Listener or Editor window.  Note: loading is destructive, i.e., it wipes out the data and rules that were previously put into the corresponding module. Adding is cumulative: the data and rules are added to the module without destroying the existing contents.
  • When a file has been successfully loaded (or added), a message will appear on the Listener.  Errors and warnings during loading can also be found here.
  • To see a list of loaded files, use File > Loaded Ergo Files, from either the Listener or Editor window.
More information about the difference between loading, adding, and the purpose of modularization of knowledge bases appears in the section on multifile knowledge bases of this tutorial.


Querying and Explanations in ErgoAI Studio

To ask a query, open the Query window from the Listener, Tools > Query (or Ctrl-U), and type in the query window. Remember to end all queries with a period. Alternatively, select a query from the file in the Editor window by highlighting the text and using Edit > Use Current Selection as Query (or Ctrl-U).  Results will be displayed in a table in the query window below.

To obtain explanations:
  • Right-click a result and select "Why?" to open an interactive justification window to see the explanation (logical chain of reasoning) for the result.
  • To find out why a query fails (does not return any answers) right-click the  No Answers Found  result that appears when there are no answers and select Why Not?
    For more options use the Explain menu in the query window: Explain > Why Not  explanation will include only calls that failed (no answers). Explain > Why Not (extended justification) will include all relevant calls, including those that succeeded and produced some answer.

  • Queries can also be entered in the Listener window (the input area at the bottom) with results appearing above the input area. If explanations to query answers are desired for a query entered through Listener, this can be achieved by typing   why{query}.    in the Listener's input area instead of just  query. 
Note: generating explanations is a computationally intensive process, which may take a few seconds. How many depends on the complexity of the query and on your computer’s speed.


Errors and Warnings

Studio preprocesses  Ergo files and provides error and warnings in the sidebar (red X for errors, yellow triangle for warnings) and also shows them in a separate window after the file is loaded. Note that the file will not load if errors are present but will load if warnings are present. It is a very bad idea to ignore these warnings since in many cases they point to potential problems. Even if they do not, they might mask real problems that could develop in later stages of the development of ErgoAI knowledge bases.

ErgoAI Studio Customization

Use the File > Preferences menu to:
  • change font size,
  • change input background color
  • save Text editor, query and listener windows positions and opened files between sessions
    • check Reopen last windows configuration on startup checkbox.


Running Ergo on Command Line

  • Start Ergo as a command line application.
  • Load an Ergo program by enclosing the program name in single quotes and square brackets, ending with a period   E.g., [‘test.ergo’].
    • The .ergo suffix is not really necessary -- it will be assumed by default.
    • If the file name is alphanumeric (i.e., has only letters, the underscore, and digits and starts with a letter or an underscore)  then the quotes are not necessary, i.e., just [test]. will work.
    • If the file is located in another directory then type the full path name to the file: ['\\foo\\bar\\test'].  Forward slashes will be understood as well: ['/foo/bar/test'].
      • Note: in Linux and Mac always use forward slashes, and they are recommended in Windows as well.
  • To add another file use [+’test2.ergo’] (or just [+test2]).  Note: adding a file is cumulative, it adds the contents of the file to the module. Loading is destructive: it wipes out all the data and rules previously loaded or added to the module.
  • The above shows how to load/add files into the default module main. To load/add to a different module, use the following commands corresponding to the above examples:  ['test.ergo' >> foobar].  or  [test >> foobar].  -- for loading into the module foobar;  [+ 'test.ergo' >> foobar].  or  [+ test >> foobar]. -- for adding to the module foobar.
  • End the Ergo session using the command: \halt .



Showing 0 items
Sort 
 
Showing 0 items