• Ergo Studio:  an Integrated Development Environment (IDE) component, with tools for knowledge editing, querying, explaining, and debugging, plus execution monitoring of reasoning.   
    • Ergo Reasoner: the component that performs the actual reasoning tasks.  Reasoning is primarily query-oriented but also does smart cacheing of its work.     
    • XSB Prolog: a low-level reasoning component that supports Ergo Reasoner.
    • APIs, mainly in Java, for the above components' functionality.   Ergo 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 (a.k.a. "declarative"in the sense of AI) and implements reasoning for the logic Rulelog.  Rulelog is a significant expansion of Datalog and declarative logic programs, the logics for which databases and most "business rule" systems implement reasoning.  


The History of Ergo Suite

  • Ergo Suite 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.
  • Ergo Suite 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 Ergo Suite

The following manuals are available via the Help menu of the Ergo Listener window after you start Ergo Studio and on the Coherent Knowledge website :
  • Ergo Reasoner User's Manual:  a comprehensive reference to Ergo Reasoner.
  • Ergo Packages Manual:  covers connectors to external information sources and systems, such as Java, SQL, SPARQL, RDF/OWL, tabular data, JSON, etc.
  • Ergo 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.


Ergo Suite Installation

Windows

    • Download the file  Ergosuite.exe  from the Google Drive folder location you received from Coherent customer support.
    • Double clicking on  Ergosuite.exe  will open the Coherent Ergo Suite Setup Wizard.  Follow the prompts to install Ergo Suite.
      • 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 Ergo Suite shortcuts. One icon is for starting Ergo 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 Ergo 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 runErgoSuite.exe file in your Ergo Suite installation, which is typically located at C:\Users\YourUsername\Coherent\ErgoSuite\runErgoSuite.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 ergosuite.run from the Google Drive folder location you received from Coherent customer support.
    • Move it to the installation directory of your choice.
    • Type
sh ergosuite.run
    • Answer the prompts. At the end of the process, you will be given the path names to use in order to run Ergo Studio as well as the command line version of Ergo. These path names have the following structure:
                            the-folder-in-which-you-ran-the-sh-ergosuite.run-command/Coherent/runErgoSuite.sh
                            the-folder-in-which-you-ran-the-sh-ergosuite.run-command/Coherent/Ergo/runergo

        The first is to be used for running the Ergo Suite GUI, while the latter is for running Ergo Engine on command line.
    • Desktop icons:  Two desktop icons (Ergo Engine and Ergo Suite) will be normally installed unless:
      • Linux:  the user has a desktop environment that is not LSB (Linux standard) compliant.
      • Mac:  Mac Developer Tools are not installed (see below).
On the Mac, one might have to reboot in order for the Ergo icons to display the correct 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, MySQL-devel, mysql-connector-odbcor similar. Use your system's package manager to find if these are installed and install them if not.
      • The package pcre-devel, libpcre-devel, or a similarly named package -- needed if one wants to use Perl-style regular expressions.
      • The package curl-devel, libcurl-devel, or similar -- install if fetching remote Web pages is going to be needed.
      • The package rlwrap is useful for the overall experience with Ergo Engine in a non-Studio 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 Ergo Suite can be installed via Homebrew. All the commands below must be typed into a terminal window:
  • brew install rlwrap   -  provides command history for Ergo Engine in the non-Studio 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 odbc  -  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

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

For Windows, the Ergo Suite 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 ergosuite.run (optional, Mac/Linux only)

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


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

One might also want to optionally and additionally verify that the checksum in ergosuite.run.sha256.sum was really generated by Coherent Knowledge. To this end, download the file ergosuite.run.sha256.sig that was linked from the email message you received together with the link to ergosuite.run. It has the same content as  ergosuite.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  ergosuite.run.sha256.sig  ergosuite.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 ....."


Starting the Ergo System

The Ergo system can be started in two ways: as part of the Studio IDE or as a command-line application

Ergo can start either in the studio mode as part of the Ergo Studio IDE (suitable for development) or as a command line application. The latter is preferable for already finished Ergo programs and 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 Ergo Suite 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 Ergo

Free trial copies of Ergo Suite 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 Ergo Suite will work on the same computer unless the trial is extended or a commercial license is purchased.

To activate a purchased copy of Ergo Suite, 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 Ergo 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 Ergo Studio Manual has more details on that.


Ergo Studio IDE

The Ergo Studio 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 Ergo Studio IDE, see the Ergo 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 Ergo Reasoner Users 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.


Ergo Studio IDE:  Querying and Explanations

  • 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 are immediately displayed in a table in the query window below.
  • 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.
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. 


Errors and Warnings

Studio preprocesses the Ergo file 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 the warnings. Most likely they point to potential problems. Even if they do not, they might mask real problems that may develop in later stages of the development of the Ergo knowledge base.

Ergo Studio Customization

Use the Tools > 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.
  • 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