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.
The display for the OpenCyc KB Browser consists of three main frames/areas:
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.
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:
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:
cd OpenCyc-x.x.x/scripts/linux [where x.x.x = current version]
./run-cyc.sh
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?".
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:
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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)
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.