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.  

• ErgoAI includes:  

  • ErgoAI Studio:  an Integrated Development Environment (IDE) component, with tools for knowledge editing, querying, explaining, and debugging, plus execution monitoring of reasoning.   

  • 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 ErgoAI Reasoner.

  • APIs: interfacing to other systems (e.g., databases), formats (e.g., JSON, XML, OWL), and languages (Java, Python, C/C++).   ErgoAI is built in Java, C, and itself. 

  • See Platform Architecture and Technical Approach for more details and an architecture diagram.

  • ErgoAI 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.

• ErgoAI 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.  

• Technical questions? We have a user forum!

A Brief History of ErgoAI

• ErgoAI is a commercially supported 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 was subsequently greatly enhanced by Coherent Knowledge Systems; it has been open sourced under the Apache 2.0 license in Spring 2023.

Bug Reporting

• Github's issue tracker:

  • ErgoAI Engine issues

  • ErgoAI Studio issues

• Paid support:

  • Please contact  info@coherentknowledge.com.

Manuals for ErgoAI

The following manuals are available via the Help menu of the ErgoAI Listener window after you start ErgoAI Studio and on the Coherent Knowledge website :

• ErgoAI Reasoner User's Manual:  a comprehensive reference to ErgoAI Reasoner.

• 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

General Prerequisites

• Main memory.  First thing first: the computer must have at least 8GB of main memory, but 16GB is strongly recommended.

• OS.  A 64-bit Windows, Linux, or Mac OSX is required.

• Java 8 is preferred, if one is planning to use ErgoAI Studio.  Some features in the Ergo-Java interface might not work with Java 9 and later versions.

Windows

• • Download the file ergoAI_XXXXX.exe from the latest release on  github.com.

  • Close any other running copy of ErgoAI.

  • 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 Command window in it) is for starting Ergo on command line in a Command 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 about 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 ErgoAI icon opens something other than Ergo then fixing the .jar-to-Java association will solve that problem.

• • Windows misconfiguration.  A not uncommon problem with Windows is that it gets misconfigured from time to time after upgrades. One of these unfortunate misconfigurations affects Ergo, so you might get the following cryptic message during the installation: "Missing VCRUNTIME140.DLL" .   This is usually the result of a Windows misconfiguration caused by a failed upgrade or a failed program install (of something other than ErgoAI).

Make sure you don't rush to download this DLL from a random place on the Internet, but follow the steps prescribed by Microsoft. An installer for the missing DLL can be downloaded from Microsoft at  https://www.microsoft.com/en-us/download/details.aspx?id=52685. Install both the x64 and the x32 bit versions of the DLL.

After this update you will need to restart your PC.

Linux and Mac OS

• • Read "Prerequisites for Linux/Mac installation" below.

  • Download the file ergoAI_xxxxx.run from the latest release on  github.com.

  • Move it to the installation directory of your choice.

  • Type

sh ergoAI_xxxxx.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/ERGOAI/runErgoAI.sh

                            the-folder-where-you-ran-the-"sh ergoAI.run"-command/Coherent/ERGOAI/ErgoAI/runergo

        The first can be used for starting the ErgoAI Studio IDE, while the latter is for running the ErgoAI inference 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 command "sh ergoAI.run"  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 ErgoAI 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

Note 3: On MacOS, if you upgrade the OS, ErgoAI must be reinstalled.   The old version of ErgoAI must be deactivated (deactivate{} command) and the new one must be activated with the same activation key.

• • Desktop icons:  Two desktop icons (ErgoAI IDE and ErgoAI Engine) are normally installed if:

    • Linux:  the user has a desktop environment that is LSB (Linux standard) compliant.

    • Mac:  Mac command line tools are installed (see below).

On the Mac, one might have to reboot in order for the ErgoAI icons to display the right pictures.

If the icons do not get installed for some reason (which is more likely to happen with the latest versions of MacOS X), use command line invocation mentioned above, i.e.,

                            the folder where you ran the "sh ergoAI.run" command/Coherent/ERGOAI/runErgoAI.sh

                            the folder where you ran the "sh ergoAI.run" command/Coherent/ERGOAI/ErgoAI/runergo

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).

• • • A possible Java  issue on Linux.   If your installation of Java  JDK is headless, you might see this error when starting ErgoAI:

Exception in thread "main" java.awt.AWTError: Assistive Technology not found: org.GNOME.Accessibility.AtkWrapperat 

To avoid this, you can install a package with the full JDK or locate the file accessibility.properties (which could be in /etc/java-8-openjdk/accessibility.properties or similar) and comment out the line  #assistive_technologies=org.GNOME.Accessibility.AtkWrapper (i.e., add #, as shown).

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-dev, MySQL-devel, mysql-client, mysql-connector-odbc, or 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-dev, or similar -- install if fetching remote Web pages is going to be needed.

    • The package rlwrap is useful for the overall experience with the ErgoAI engine in a non-Studio (terminal) mode. This package provides command history, which can be browsed via the Up/Down arrows on the keyboard.

Mac systems:  Under MacOS, ErgoAI requires Xcode to be installed and be up-to-date. This package contains a C compiler and other utilities needed during ErgoAI installation. 

• • • Go to the Mac Apps store, find Xcode, click "Get" then "Install App" (Xcode is free and is an optional part of MacOS).

    • After installing 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 and the above xcode-select command be rerun.

A number of optional ErgoAI 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 g++   -  if clang is not installed, then install g++; needed for compilation.

    • brew install autoconf   -  configuration system; needed for compilation.

    • brew install rlwrap   -  provides command history for the ErgoAI 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 Ergo's 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

    http://pgp.mit.edu/

    http://keyserver.ubuntu.com/

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/ErgoAI/;  (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

ErgoAI reasoner 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 ErgoAI 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 ErgoAI 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.

ErgoAI Studio's IDE

The ErgoAI Studio's IDE is normally used for development of ErgoAI knowledge bases, as it provides extensive support for that. However, it also has a "Listener" window, which can be used to enter Ergo commands and queries similarly to what one would do when ErgoAI 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.

Creating, Opening, Editing, and Loading Files

• To customize font size and other features, refer to ErgoAI Customization

• To run ErgoAI from the command line, refer to Running from the command line

• To edit a new file, from the ErgoAI listener window, select the menu item  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 the menu item  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 the menu item 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 the menu  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,  select the menu item 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 the menu  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 ErgoAI on Command Line

• Start ErgoAI as a command line application.

• Load an ErgoAI knowledge base 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  and the file extension  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, e.g.,  ['\\foo\\bar\\test'].  Note that each backslash must be escaped with another \.  Forward slashes are understood as well (and don't need to be escaped):  ['/foo/bar/test'].  For that reason, forward slashes are preferred to backslashes in file names.

    • Note: in Linux and Mac always use forward slashes, and, as we just said, 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, on the other hand, 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 ErgoAI session using the command: \halt.