## The OpenCyc KB Browser

E-Mail Comments to: opencyc-doc@cyc.com
Last Update: 3/29/2002
Copyright© 1997-2002 Cycorp. All rights reserved.

Return to Table of Contents

This document describes how to use the Cyc KB Browser and related tools. The OpenCyc KB Browser includes a subset of the functionality of the Cyc KB Browser. The content can be used both as an introductory document for beginners, and as a reference document for more experienced users.

### Contents

- Introduction to the OpenCyc KB Browser
  - Layout of the OpenCyc KB Browser
  - Note about Frames and JavaScript
- What To Know Before You Begin
  - How to Start a New OpenCyc image
  - How to Get to the KB Browser (and other places)
  - Getting Help Using the KB Browser
  - Key for Icons Used in the KB Browser
- Setting Up Your New Image
  - Logging In
  - Starting the Cyc Agenda
  - Changing Error Handling Modes
  - Changing Communication Modes
  - Updating the Toolbar (Gaining Access to Tools)
  - Setting Other Options
- Viewing and Modifying the OpenCyc KB
  - Searching for Constants
  - Viewing Constants
  - Creating and Performing Operations on Constants
  - Searching for Assertions in the KB
  - Viewing Assertions
  - Performing Operations on Assertions
  - Adding New Assertions to the OpenCyc KB
  - Loading a Transcript File
- Troubleshooting
  - Restarting Your OpenCyc image
  - Your OpenCyc image is Not Responding
  - You're Unable to Get an OpenCyc image to Start Up
- Finishing Touches
  - How to Safely Halt Your OpenCyc image

### Introduction to the OpenCyc KB Browser

The OpenCyc KB Browser is the main interface tool for accessing the Cyc Knowledge Base (Cyc KB). It provides a means for browsing the KB in a number of different ways, a means for querying the KB, and (for registered users) a means for modifying or adding to the KB itself.

The OpenCyc KB Browser can also be viewed as one of several "launching points" into the Cyc System. From the KB Browser, it is possible to reach virtually all other areas of the Cyc System simply by following HTML links. One of the chief access points is the Cyc Navigator, but there are many other routes that can be followed. More information on navigating around is provided farther down in this document, as well as in the help documentation that can be accessed from the KB Browser itself. Before you try to do anything else with the KB, it is recommended that you read the relevant sections of this document. It will tell you how to start an OpenCyc image, log into the system, view and modify the KB, and use the various options provided with the browser.

A useful companion document to this one is a tutorial entitled "Using the Cyc Web Interface". The tutorial provides a handy walk-through of many of the facilities of the Cyc System. If available, it is located in the "Cyc Course Materials" section of the Cyc Documentation: Table of Contents.

#### Layout of the OpenCyc KB Browser

The display for the OpenCyc KB Browser consists of three main frames/areas:

- Top Frame: the top frame is the Toolbar Frame. It is used for searching for constants in the Cyc Knowledge Base (KB), navigating around the KB Browser via various tools, and logging in. The Toolbar Frame is always present in the KB Browser. If frames are turned off, the Toolbar will appear at the top of each page.
- Middle Frame: the middle frame is the Main Display Frame. It is used to display constants, assertions, help documentation, and various KB Browser tools. There is no standard display for the Main display frame; rather, the display changes when various links are clicked in any of the three main frames. If frames are turned off, this part of the display will appear under both the Toolbar and the Agenda Status Bar.
- Bottom Frame: the bottom frame is the Agenda Status Bar. It provides information about the Cyc Agenda and the local OpenCyc image, and also provides means for controlling the behaviour of the Cyc Agenda. If frames are turned off, the Agenda Status Bar will appear immediately below the Toolbar, at the top of each page.

The OpenCyc KB Browser offers essentially the same interface for all different platforms. Not all versions of the Cyc System have the same exact features, however, and so there will be a few visible differences between versions. For example, the C version may have different options than the LISP version, or an extra diagnostic tool may be available in the Cycorp internal version that is not available in a released version. When possible, these minor discrepancies have been pointed out in the help documentation, though it is not always possible to describe differences in detail; simply be aware that such differences do exist.

#### Note about Frames and JavaScript

The enabling or disabling of frames and JavaScript will have an effect on the display features and capabilities of the KB Browser. These differences will be described in the help documentation when they are relevant to that particular section of the KB Browser.

However, there are a couple of things to keep in mind as you use the Browser:

- Constant completion requires that JavaScript be enabled. If it is turned off, no [Complete] buttons will appear, and completion will not be possible.
- Turning frames off will change the overall layout as mentioned above, plus all references to frames in the documentation will be irrelevant; however, the names of the tools (e.g., Agenda Status Bar) will still be applicable. Also, though "Update" and "Refresh" links throughout the Browser are designed to affect only a single frame, when frames are turned off they will refresh the entire HTML page.

### What To Know Before You Begin

#### How to Start a New OpenCyc image

A "Cyc Image" is simply a version of Cyc running on an individual computer. Before you can use the browser in order to look at the KB, you must get a new image running on your computer. The steps for doing so differ by platform:

- NT image:
  - (not yet available)
- C image for Unix (LINUX):
  - Connect to the directory with the Cyc executable:

    cd OpenCyc-x.x.x/scripts/linux [where x.x.x = current version]

  - Launch the Cyc server:

    ./run-cyc.sh

#### How to Get to the KB Browser (and other places)

To get to the KB browser, first start up Netscape Navigator. Then, you can access the following useful URLs for navigating around:

The OpenCyc KB Browser (http://<hostname>/cgi-bin/cyccgi/cg?cb-start): the main tool for accessing the Cyc Knowledge Base (KB). If you've just started up your image for the first time, this should probably be the URL to go to.

The Cyc Navigator (http://<hostname>/cgi-bin/cyccgi/cg?cyc-navigator): a suite of tools for the Cyc System.

The Cyc Documentation Table of Contents (http://<hostname>/cycdoc/toc.html): documentation for anything and everything in the Cyc System.

Note: With all of these URLs, please replace the string "<hostname>" with the name of your webserver. If your webserver is running under NT, you'll need to replace the "cg?" with "cg.exe?".

#### Getting Help Using the KB Browser

Each of the pages in the KB Browser has its own help page. This can be accessed by clicking on the red question mark .

A complete listing of the help pages is available here for your convenience:

Advanced Inference Settings Help Agenda Process Control Help Agenda Status Bar Help Alphabetical Search Help Applicable Relations Help Arguments Help Argument Source Help Ask a Query Help Assertion Diagnostics Help Assertion Display Frame Help Assertion Justification Help Assert Simlar Formula Help Auxiliary Indices Help Browser History Help Browser Options Help Browser Tools Help Change Assertion Direction Help Change Assertion Mt Help Change Assertion Strength Help Communication Status Area Help Confirm Constant Kill Help Confirm Constant TMS Page Help Constant Diagnostics Help Constant Information Display Help Create Constant Help Create Similar Constant Help | Dependents Help Display by Date Help Edit Assertion Help Halt OpenCyc image Help Hierarchy Browser Help Hierarchy Browser Parameters Help Hypothesize Help Index Overlap Help Inference Resource Constraints Help Inference Tree Examiner Help Literal Query Help Load API Help Local Operations Help Login Area Help Public Assertions Help Rename Constant Help Restore Interface State Help Save Interface State Help SubLisp Interactor Help System Area Help Term Index Help Toolbar Help Transcript File Help Transcript Viewing Area Help View Mt Help

#### Key for Icons Used in the Browser

A link to the icon legend for the KB Browser can be found at the top of the Term Index help page. Click here to go directly to the Key for Icons Used in the Browser.

### Setting Up Your New Image

#### Logging In

NOTE: On a newly installed copy of OpenCyc, you need to log in first as CycAdministrator. Then, while logged in, you can go back to the login screen and enter a new name to log in as. A new contstant will be created using the new name, and it will be asserted to be an instance of HumanCyclist.

The first thing to do when you've started up a new OpenCyc image is to log in. To do this, click on the "Login" link in the Toolbar (the top frame of the KB Browser). In the window, enter the Cyc constant that refers to you (e.g., #$Fred). This is not (necessarily) the same as any site login (e.g., LINUX filesystem) that may be implemented. If the appropriate Cyc constant does not yet exist, you'll be asked if you want Cyc to create one for you.

For more detailed information on logging in, see the Login Help.

#### Starting the Cyc Agenda

The "Cyc Agenda" handles operations to the KB. When you first start up Cyc, the agenda will be halted. After logging in, the next thing to do is to start up the Cyc Agenda. To do this, click on the "Agenda" link in the Agenda Status Bar (the bottom frame of the KB Browser), which will bring up the Agenda Process Control. Press the [Start Agenda] button to start the Cyc Agenda.

For more detailed information on starting the Agenda, see the Agenda Process Control Help
For detailed help on the Cyc Agenda, read the Cyc Agenda Documentation

#### Changing Error Handling Modes

Now that the Cyc Agenda is running, you should tell it how to handle any errors it may encounter. The default error handling mode is to Halt and Display Reason, which means that errors will cause the Agenda to halt, and will be displayed on the Agenda Process Control page. If this is the desired behavior, ignore this section and continue on. To change to a different mode, click on the "Agenda" link in the Agenda Status Bar (the bottom frame of the KB Browser), which will bring up the Agenda Process Control. Click on a new error handling mode and press the [Submit New Mode] button.

For more detailed information on setting a new error handling mode, see the Agenda Process Control Help. For detailed help on the Cyc Agenda, read the Cyc Agenda Documentation.

#### Changing Communication Status

NOTE: There is no Master Transcript Server with OpenCyc. Synching knowledge with remote OpenCyc installations will be a challenging undertaking that will require several partial solutions. Several partial-solution candidates exist and will be discussed on the OpenCyc forums.

Even though the Cyc Agenda is running, it will not receive or send any operations perfomed on the KB (like creating constants, asserting or unasserting, etc.) unless the communication status is set so as to allow this. The default setting is "Storing Only", which means that operations performed locally will be stored for possible sending to the Master Transcript later, but no operations are read from the Master Transcript. If this is the desired behavior, ignore this section and continue on. To change the communication status, click on the "Comm" link in the Agenda Status Bar (the bottom frame of the KB Browser), which will bring up the Communication Status Area. Make changes to the settings press the relevant [Submit] button.

For more detailed information on setting the communication status, see the Communication Status Area Help. For detailed help on Communication Status, read the Cyc Communication Status Documentation.

#### Updating the Toolbar (Gaining Access to Tools)

The OpenCyc KB Browser includes a number of tools to assist with knowledge entry and browsing. To see a list of these tools, click on the "Tools" link in the Toolbar (the top frame of the KB Browser). Clicking on the name of a tool will take you there. However, it's often useful to have frequently used tools just a single click away. To this end, it's possible to add desired tools to the Toolbar. Simply click on the "Tools" link as before, but instead of clicking on the tool name, click the box to the left of the name, and then press the [Update Toolbar] button. Any tools you have selected will now appear as links in the Toolbar.

For more detailed information on various tools, see the Browser Tools Help.

#### Setting Other Options

In addition to customizing your Toolbar, there may be other options that you wish to set initially. To do this, go to the Browser Options tool by clicking on the "Options" link on either the Browser Tools page, or in the Toolbar (if you've added it there). If you can't find the link, look in the section above, Updating the Toolbar (Gaining Access to Tools). The options on this page are set to defaults that are figured to be most useful to the common user, and therefore won't usually need to be modified. However, there may be one or two options which you'll want to change before you start browsing the KB:

Server Update Interval: Look at the Agenda Status Bar. When the communication mode is set, the Agenda is started or halts, or the Agenda processes operations, the Agenda Status Bar is not automatically updated. Instead, you'll need to click on the "Update" link. To have everything updated automatically, enter a number into the Server Update Interval window of the Browser Options Page, press the [Change Options] button, and click on the "Update" link one final time. Every X seconds, the information will be updated. A recommended interval is 15 seconds.
For more detailed information on the Agenda Status Bar, see the Agenda Status Bar Help.

Default Content: When you display a constant in the KB Browser, a certain set of assertions comes up automatically. This is the Default Content. The default setting for this is to display up to 30 assertions. If you would prefer to see a different kind of information initially displayed with the constant, choose one of the other 3 options in the Default Content section of the Browser Option page, and then press the [Change Options] button. You can also increase or decrease the number of assertions displayed if you choose to keep the default option.
For more detailed information about the kinds of assertions, see the Index Categories section of the Term Index Help.

Wrap Assertions: When you display assertions in the KB Browser, the default is for each assertion to be allotted a single line in the KB. This maximizes the number of assertions that can be displayed at any one time. However, a few very long axioms may go off the edge of the screen as a result. While it's still possible to view the assertion by enlarging the window or displaying the assertion in detail by clicking on the colored ball, many users prefer to set the Wrap Assertions option. Setting this option causes assertions to be displayed entirely on the screen, though it allows for fewer assertions to be seen at any given time.

For more detailed information about the different browser options, see the Browser Options Help.

### Viewing and Modifying the OpenCyc KB

The OpenCyc KB is essentially a sea of constants and a sea of assertions. There are many different ways to locate and view both constants and assertions, as well as many different operations that can be performed on them. This section describes how to view and make modifications to the KB.

For each of the sections/tools below, there is most likely a corresponding section/reference in the "Using the Cyc Web Interface" tutorial mentioned earlier.

#### Searching for Constants

NOTE: The GREP facility is not currently available in OpenCyc, but it will be made available as soon as a programmer has the time to migrate it from the full Cyc version.

The easiest way to search for constants in the KB is to use the search facility located in the Toolbar Frame. Simply enter in a constant name (without the "#$") and click the [Show] button. It is also possible in this window to use strings (via wildcards or unix GREP) to search for constant names. For details on all of these options, see the Toolbar Help.

A second way to find constant names is to use the [Complete] button next to many of the input windows throughout the Browser. Simply enter the first part of a constant name and press the [Complete] button. Possible completions will be displayed in a separate completion window which will be reused for future completions. Completion is case sensitive, and requires that JavaScript is enabled in your browser.

One final way to search for constants is to use the Alphabetical Search, which provides an alphabetical listing of constant names. The Alphabetical Search can be reached via the "A" link in the Browser, and will appear automatically if Cyc is unable to find a matching constant when using the search facility in the Toolbar. For details, see the Alphabetical Search Help.

#### Viewing Constants

To view a constant that appears anywhere in the KB Browser, such as in an assertion, in a constant completion list, or in the Browser History, simply click on the highlighted constant name. The one exception to this is in the left-hand frame of the Term Index, where constant names are actually assertion categories. For details, see the Term Index Help.

One other method of viewing constants is the Hierarchy Browser, which provides a hierarchical listing of constants. The Hierarchy Browser can be reached by clicking on the "Hier" link in the Toolbar or Browser Tools pages, via the red diamond link in the Browser, or as a link in the Cyc Navigator. For details on the Hierarchy Browser, see the Hierarchy Browser Help.

#### Creating Constants and Performing Operations on Constants

There are several ways to create new Cyc constants. Perhaps the easiest way is to use the Create tool, which allows the user to create a new constant as an individual operation. The Create tool can be reached by clicking on the "Create" link in the Toolbar or Browser Tools pages, as well as through the Cyc Navigator. Details on using this tool are provided in the Constant Creation Help.

Operations such as renaming and killing constants are relatively easy to do in Cyc (though they should be done sparingly). Simply display the constant in the KB Browser (see above for how to do this). Under the constant name in the Term Index will be links titled "Rename" and "Kill". Clicking on these will take the user to the Rename and Kill facilities, respectively. Be sure to read the help documentation linked to those pages, as well as the document Renaming and Killing Constants.

#### Searching for Assertions in the KB

As mentioned above, the KB is a sea of assertions. How to find the one you want?

If you know one of the terms involved in the assertion you're looking for, the easiest way to find the assertion is to display that constant in the KB. You can then choose one of the categories in the left-hand frame of the Term Index to display a desired subset of the assertions involving that constant. Clicking on "All Assertions" will display all the assertions for that constant. You can use the search facility of your HTML browser (Netscape, Explorer) to scan through the assertions for the desired one. See the Term Index Help for descriptions of the Term Index categories.

If you know more than one involved term, there are several options. You can display one of the constants, and then use the second one as a Term Index category (if applicable) or as a search term in the HTML browser search. Better yet, the Index Overlap tool compiles a list of all assertions involving two or more specified constants. Simply use this tool to narrow down choice of assertions to those involving all of the terms specified. When you use the Overlap tool, it is necessary to include the "#$" in the constant names. See the Index Overlap Help for further details.

#### Viewing Assertions

There are several ways to view sets of assertions in the KB Browser. The standard way is to display a constant, and then use the categories in the Term Index to view the desired set of assertions for that constant, as described above. The second way is to use the Index Overlap tool, also described above. One final way is to use the Literal Query tool to display more assertions of a certain type. This can be done by clicking on the "+" icons next to category names in the Term Index. See the Literal Query Help for details.

To view a single assertion in more detail, click on the colored ball in front of the desired assertion. See the Key for Icons in the Browser for descriptions of the meanings of the different balls (and other icons).

#### Performing Operations on Assertions

Operations such as editing, deleting, and copying (asserting similar) assertions are fairly straightforward in the KB Browser. First, locate the target assertion and display it in detail by clicking on the colored ball next to it. You'll see a list of operations that can be performed. Here are a few:

Edit: allows the user to edit the assertion.

Unassert: deletes the assertion from the KB (for locally asserted axioms).

Blast: deletes the assertion from the KB (for deduced assertions).

Assert Similar: makes a copy of the assertion, allowing the user to edit the new version, while the original is retained in the KB.

See the Assertion Display Frame Help for a complete list of operations and more detailed descriptions. Also see the Assert Formula Help for help with the Edit Formula and Assert Similar Formula tools.

#### Adding New Assertions to the OpenCyc KB

There are several methods for adding new knowledge (assertions) to the KB. For single assertions, it's fastest to use the Assert Formula tool in the Browser; just click on the "Assert" link in the Toolbar or Browser Tools page, or access it via the "Browsing and Editing" menu of the Cyc Navigator. This tool allows the user to add one assertion to the KB. See the Assert Formula Help for details.

### Loading a Transcript File

NOTE: There is no Master Transcript Server with OpenCyc. Synching knowledge with remote OpenCyc installations will be a challenging undertaking that will require several partial solutions. Several partial-solution candidates exist and will be discussed on the OpenCyc forums.

Operations in the current local transcript can be sent to the Master Transcript simply by sending stored operations from the Communication Status Area. However, it is sometimes desirable to load a transcript manually. (Examples of transcripts to be loaded manually include: transcripts from a previous OpenCyc image,, transcripts containing operations that were cleared instead of being sent to the Master Transcript, or transcripts from other OpenCyc images whose operations have never been sent to the Master Transcript, but it's desireable to have them included in the current local image. Manually loaded transcripts can be loaded up on the local machine and sent (or not) at a later time; the user is never committed to sending operations unless the communication status is set to "Send Immediately".

To manually load a transcript file, select the "Navigator" link from the Toolbar Frame or the Browser Tools page. Click on "Load Transcript File" in the "File Handling" section and follow the instructions there.

To view the current local transcript (or the Master Transcript), click on the "System" link in the Agenda Status Bar, and then click on the relevant highlighted transcript name. It is also possible to view all local transcripts for the current OpenCyc image in the Transcript Viewing Area. To get there, click on the "Viewer" link in the Browser Tools.

For more help with transcripts, see the Cyc Transcript Documentation, as well as the System Area Help, the Transcript Viewing Area Help, and the Transcript File Help.

### Troubleshooting

Unfortunately, even the most experienced users of the perfect program run into trouble at times. Here is an extremely short section (to be expanded over time) to assist during those times.

#### Restarting Your OpenCyc image

Occasionally, it will be necessary to restart your local OpenCyc image. To restart your image, follow the instructions in the next section for halting an OpenCyc image (How to Safely Halt Your OpenCyc image), then go to the top of this document and follow the instructions for starting up a new image in the How to Start a New OpenCyc image section.

#### Your OpenCyc image is Not Responding

If your OpenCyc image doesn't seem to be responding, do not despair. There are several possible reasons for this:

The Cyc Agenda is processing a long operation: Certain operations, most notably unasserts or edits which involve deeply embedded knowledge, may take some time to process. This is normal. Remember that when an assertion is removed from the KB (and edit operations involve an unassert), the TMS (Truth Maintenance System) must look at all of that assertion's dependents and reevaluate if they should remain in the KB. For each of those that is subsequently removed, the procedure must be repeated. Eventually, the Agenda will finish with the operation, and the OpenCyc image will free up. See the Cyc Agenda Documentation for details on how the Cyc Agenda works.

The Cyc Agenda is stuck in an error break: If the error handling mode is set to "Enter the Debugger", an error in the Cyc Agenda will freeze up the OpenCyc image until the error is dealt with. To avoid having your OpenCyc image freeze up when the agenda runs across an error, set the error handling mode to "Halt and Display Reason". The Agenda will still halt, but the OpenCyc image itself will still be usable, even if the error is not dealt with right away. For help with the error handling modes, see the Agenda Process Control Help.

#### You're Unable to Get an OpenCyc image to Start Up

If your OpenCyc image is not starting up, and you see a message like:

      Loading init file: init/opencyc-init.lisp
      Error: Can't bind port XXXX.

This almost always means you already have a version of Cyc running. You must quit this version to start up a new one.

If you are unable to connect to the image and unable to find the emacs buffer it is running in, you can kill the image manually, using something like the following in a Unix/xterm window:

      ps auxww | grep cyc  (to find the process id of cyc)
      kill -9 process_id   (use that process id to kill cyc)

### Finishing Touches

#### How to Safely Halt Your OpenCyc image

There are many ways to halt an OpenCyc image. However, there is one easy way which will ensure that the image is halted safely, and that no sub-processes that it created remain in the system. Failing to safely halt an image may create problems when trying to start up a new OpenCyc image in the future.

Note that users logged in as #$Guest will be unable to halt an OpenCyc image since it may disrupt others' work.

To safely halt an OpenCyc image:

Click on the "System" link in the Agenda Status Bar (the bottom frame of the KB Browser), which will bring up the System Area page. Click on the "here" link in the phrase "Click here to halt this OpenCyc image." You'll be asked to confirm that you really do want to halt the image. Once an image is halted, there is no way to restart it, except to start up an entirely new image. Remember that halting the Cyc Agenda and halting an OpenCyc image are two completely different things. To truly halt the image, click on the "Yes" link; to abort the halt and return to the KB Browser, click on the "No" link. If you clicked "Yes", you should see a message confirming your decision to halt the image.
For more detailed information about halting the OpenCyc image, see the Halt OpenCyc image Help.

To start up a new OpenCyc image, follow the instructions in the How to Start a New OpenCyc image (LINUX/C) section.

Go to Top