. Panoply/FRDCSA/FLP Introduction/Tutorial

Welcome to the FRDCSA Project Introduction/Tutorial

Table of Contents

Table of Contents
Emacs Refresher
Navigating the FRDCSA using Emacs
The Structure of the MyFRDCSA directories
The Structure of FRDCSA Internal and Minor Codebases
Running UniLang (the Universal Language)
Running FLP (the Free Life Planner)
Running SPSE2 (the Shared Priority System Editor v2)
Running Verber
Running CLEAR (the Computer LEarning ARchitecture)
Running RADAR and Packager
Running Problemspace
Using FreeKBS2
Systems Not Included In This Release
Programming With FRDCSA


The FRDCSA will have been in continual development for 20 years as of August of 2019. Thankfully, we are now able to partially release the system to you! The VM distribution of FRDCSA is called Panoply.

I suppose you are already familiar with what the FRDCSA is, if not see https://frdcsa.org.

There are quite a few FRDCSA systems installed here. They can almost all be found subdirectories of the main project directory in /var/lib/myfrdcsa. Most project codebases are available in either: /var/lib/myfrdcsa/codebases/internal or /var/lib/myfrdcsa/codebases/minor.

However, this represents only a small fraction of what the FRDCSA proper currently can do. It will take time to create the next release of FRDCSA, but this will be a good way to learn the project basics and get in a position to make use of the next major release of Panoply, whenever that should hopefully happen.

The FRDCSA user interface is best run from Emacs. Without using Emacs, it will be impossible at present to make effective use of the system. So if you haven't already, please do the Emacs tutorial at least. It is preferable that you also read the Emacs info page. To access the Emacs Tutorial, run:

Followed by:
C-h t
That is, press Control h, then t. Usually I run emacs in a screen session, but note that the escape character has been changed from C-a to C-]. i.e.
screen -S flpTerm1
emacs -nw	

When running emacs, you will see that a lot of systems are loaded. There are a lot more such systems that we haven't been able to release, but maybe you can help us with that. To ask about helping out, please email Andrew Dougherty at adougher9@gmail.com

Emacs Refresher

Some useful Emacs tips and tricks are, if you get really stuck, try using

To exit Emacs, do
C-x C-c
followed by answering the shutdown questions.
stands for Meta (usually, Alt) simultaneously with x. You can use this followed by entering the in minibuffer (with tab completion) to run interactive Elisp functions.

To get more information, such as the name of the command, press

C-h k
followed by the key sequence. So for instance to learn more about C-x C-c, run
C-h k C-x C-c
If you have a function name under the emacs cursor (a.k.a. the point), press
and it will take you to Emacs Lisp source code for the function.

Navigating the FRDCSA using Emacs

FRDCSA is a large project with probably over 2 million lines of code. As such it has many special navigational features, usually Emacs key bindings. As a rule, most FRDCSA Emacs functions have as a prefix a name refering to the project they're contained in, such as

(here the prefix is "radar-"). To find various FRDCSA Emacs functions, one can do:
M-x apropos
and it will prompt for a search pattern to look up the functions whose names match the search pattern.

The primary method of using FRDCSA from Emacs is a mixture of common key bindings, as well as command line. We prefer the

M-x shell
method of accessing the terminal. We have a shortcut for switching to the current *shell* buffer and/or uniquely renaming the current shell buffer and creating a fresh *shell* buffer:
C-x n s
One can also switch between buffers of the same major mode using
C-x n y

Once a shell has been opened, one can navigate to almost any FRDCSA project using

C-c r r
which will prompt the user for the name of the project (with tab-completion).

There are a couple of other conveniences in the radar- command set, including:

C-c r e e
which will take you to the default Emacs code location of any selected project.
C-c r e t
will take you to the to.do file for any project.

If you are in a shell and there is a command name and you wish to edit the file, simply move the cursor over it and run

C-x C-f
, and it will retrieve the file in the path for it using the `which` command. If you have a Perl module under point, you can use
C-c r l s
to jump to the file if FRDCSA knows where to find it.


The Structure of the MyFRDCSA directories

If one looks at the /var/lib/myfrdcsa directory, one sees among other the following subdirectories:

.	internal (our custom codebase)
.	minor (more of our custom codebases)
.	external (codebases we have collected)
sandbox (external codebases are extracted into and packaged here)
.	external (more of the codebases we have collected)
.		git
.		svn 
.		...

internal and minor are our custom codebases. external and external/git etc are collected codebases. Codebases are extracted into and packaged in sandbox.

The Structure of FRDCSA Internal and Minor Codebases

Many FRDCSA projects have the following files or directories:

scripts (default scripts for the project)
.	FRDCSA.xml (file describing the project)
.	emacs (Emacs source code files for the project)
.	sys
.		flp (files pertaining to the Free Life Planner)
.		cso (files pertaining to the Comprehensive Software Ontology)
sys or systems
Often times, there will be a similar set of files for running the software: So for instance, in the radar project there is:
RADAR.pm (The main Perl Module for the project)
RADAR (a directory containing Perl submodules)
radar (a shell command to invoke RADAR)

Running UniLang (the Universal Language)

Once you loaded Emacs, it is a good idea to start up the UniLang MultiAgent/IPC System. One does this by:

C-c r u
You will see a lot of stuff get launched. When it stops loading, you can go ahead and some things.

If you didn't see

Agent Emacs-Client-XXXX registered
(where XXXX is the PID of the invoking Emacs process) in the *ushell* buffer, try running:
C-c u u c
Alternatively you might see:
Name already taken: <Emacs-Client-XXXX>
bogus message, not processing
This means that Emacs-Client has connected too many times. This may happen occasionally as there are bugs in the Emacs-Client connection code. To return it to normal, enter the *ushell* buffer and type:
UniLang, deregister Emacs-Client-XXXX
followed by pressing enter. Then start it again, with:
C-c u u c

Or, as a temporary work-around (which usually, but not always works), you can run:

C-u C-c r U
and it will attempt to deregister the Emacs-Client agent and reconnect it.

Many FRDCSA programs such as FLP, Clear, SPSE2 and Paperless-Office all depend on UniLang running. There are some init.d scripts for unilang, but we don't really use them as of now. It is easier just to manage it from Emacs for now.

In a moment, we will return to running some of these programs, but for now, I'd like to introduce you further to the FRDCSA Emacs utilities. You can kill Unilang for now with:

C-c r k
You will see the message
Ushell stopped
in the Emacs minibuffer.

Running FLP (the Free Life Planner)

The Free Life Planner (FLP) is the flagshap application of the FRDCSA project. You can read more about it HERE. To summarize, it is a personal AI that attempts to help you effectively adminstrate your life. Not everyone believes they need such a program, so this is written mainly with the people who want such a thing in mind. It is capable of doing a lot of planning, scheduling and execution of plans, tasks, recurrences, reminders, etc.

To get FLP running, once simply has to run:

C-c f f r
You may have to type
into the minibuffer a few times during this process. You will need to wait until you see the created *WSM* buffer say: DONE LOADING FREE-LIFE-PLANNER. If the windows are not displaying correctly you can straighten them out with:
C-u C-c f f w s

The command you used earlier:

C-c f f r
actually *restarts* FLP, but is generally more convenient as it will clean up any residual processes being run from a previous invocation of FLP without the need to restart the containing Emacs process. Note it will not restart your UniLang process if it is already running (since currently UniLang agents cannot automatically reconnect once disconnected, this prevents you from accidentally dropping connections to already running UniLang clients such as SPSE2 and CLEAR). I believe in this version it restarts OpenCYC each time. OpenCYC has been included here for convenience, but the actual FLP currently runs either ResearchCYC and/or LarKC_CL, so OpenCYC does not actually do much here.

From there it is best to point a web browser to, or whatever your correct IP address is.

If you haven't logged into it before or for a while, it will take you to the splash screen, which might say "Welcome to the Free Life Planner: IT'S NICE TO MEET YOU". From there, you should click SIGN IN in the top right. Currently, you will want to use the following credentials:

Username: admin
Password: changeme

This release of Panoply does not include a lot of the functionality behind the site. I am trying to get at least Plans and financial planning working.

Note that, from Emacs, it can take a while to move between windows using

C-x o
so ace-windows is provided and bound to
It will number the buffers starting with 1 and you just press the number of the buffer you want to more quickly navigate.

See how FLP typically starts up HERE (note, noisy).

If everything has loaded you can always jump to (if you're not already at) the *Formalog-REPL* buffer using:

C-c f p r
From there you can enter in Prolog queries. For instance (if Emacs-Client-XXXX is properly connected) you can enter
and it will take a second but it should do tab completion over the constants in the knowledge base. Pressing
again should open the list of commands in a temporary buffer. You can switch over to this buffer with
and the number of the buffer, and then use
to scroll down and
to scroll up.

Another thing you might want to do is jump to a file or see all the files: you can:

C-c f f o p
to do minibuffer ido-completion on the files in the FRDCSA, opening the selected one. If the filename cache is not present, it will force it to regenerate the filename cache. You can force it with
C-c f f o P
You can use
at this point as above to open a temporary buffer with the names of the files. Enter
C-x C-f
over one of the files should open that file, as it's bound to kmax-ffap which is a fancier version of find-file-at-point which will use the `which` command to find the version of the file in the path. (Note as mentioned above you can also run C-x C-f on command names and it will also retrieve them using `which`.)

One thing you might want to do is search within these files, to do that you

C-c f f o G s
and wait for it to retrieve the filename cache, then type in your query. A separate buffer should open called *FLP-Search* with the results.

There are currently a couple of bugs to be aware of. Do not hit enter on any text in the *Formalog-REPL* until *WSM* has finished with "DONE LOADING FREE-LIFE-PLANNER". Otherwise it will cause it to list the contents of the knowledgebase using Data::Dumper in the *WSM* buffer, which takes a long time. Another thing is, if you use a command like

C-c f f o P
, Emacs will block for a little while. If you hit any key during this time, it's possible it will interrupt the QueryAgent Emacs call and never return a value, in which case you have to
and possibly restart.

Running SPSE2 (the Shared Priority System Editor v2)

SPSE2 is documented in this PAPER. SPSE2 is a precursor to the Free Life Planner. To get SPSE2 running, be sure to have UniLang running. Then, from a terminal, do the following:

spse2 -l
This will list the available Contexts. A context is simply a collection of assertions in the Knowledge Base. SPSE2 and FLP use FreeKBS2 Once you have a context in mind, or wish to create a context, run:
spse2 -c CONTEXT
where CONTEXT is the name of the context you wish to open.

To use SPSE2, you can see the keybindings using the same command as in Emacs:

C-h b
Also, adding
to the end of a prefix key is a method of listing available keybindings that start with the prefix key.

SPSE2 Contexts must always have at least one goal in them, so they start out by default containing a goal saying "Remove Me". Before removing it, create a new goal with

C-c n +
and then enter the goal in the Description text entry. Note that return is not bound to 'Create New Node' so that you can enter items with return in them, same with tab. You will want to click on 'Create New Node' when finished.

Once you have created at least two goals, you can mark a dependency between them, and/or any of several other binary relations. To mark a dependency, first make sure no goals are selected, then select the goal that depends on another goal first by clicking on the box of the goal with the

left mouse button
It should make the box appear darker. Then
shift-left mouse button
select the goal which it depends on, so that both of those goals have been selected. Finally, enter
C-c s b d
Here the s stands for modify relation, the b stands for binary, and the d stands for depends. To undo a binary relation, follow the same procedure to create one, but instead enter
C-c s B d
The capitalized B indicicates to remove the binary relation.

One can also create other binary (and unary) relations. To mark a goal or goals complete, ensure they are selected and then enter

C-c s u c
To mark that a goal provides another goal, meaning it is sufficient to achieve the latter by achieving the former, use
C-c s b p
and to say that a goal eases another goal, use
C-c s b e

There are many other features available with SPSE2 which unfortunately we don't have the time to document right now. But we will mention plan generation. Once you have sufficiently created a planning domain (or used the default provided domain), you can generate a plan to achieve it using the following: First select all the goals you want to accomplish (note you don't have to select all the goals depended on by a goal, it will include them automatically). Select from the Menu:

Action -> Domain -> Planning -> Generate Plan -> Selected
If successful, it should generate a PDDL planning domain and problem and pop up a window called "Verber GUI" with a button at the bottom saying "Generate Plan". Click this button and if the plan is successful generated it will pop up another window called "IEM2". You can then walk through the generated temporal plan with the "Next Point" and "Previous Point" buttons.

Note that we haven't gone into the temporal planning capabilities of SPSE2. The SPSE2 toolchain is currently being superseded by the Free Life Planner IEM.

See SPSE2 in action HERE.

Running Verber

Verber is the main planning federated planning system capable of invoking many other planners. Unfortunately several planners have not yet been fully integrated with Verber. One can invoke verber from the command line, Emacs, FLP or SPSE2. We will cover invoking from Emacs.

Verber has helper Emacs functions that allow you to debug planning domains rather quickly, for use in FLP and SPSE2. The main keybinding is:

C-c r v t
which invites you to tab-complete the name of a planning capsule. Although PDDL allows you to specify more than one problem file per domain file, we treat them as pairs for now. So a capsule is the shared prefix of both the domain file and the problem file. For instance if your domain file is "flp/flp.d.pddl", and your problem file is "flp/flp.p.pddl", the capsule is "flp/flp".

Use tab completion to select a domain. You can select "date-20170205" for instance using

C-c r v t
This will load 4 buffer windows, with the domain in the top left, the problem in the top right, the *shell* buffer in the bottom left and the Federated planning code in the bottom right. It also sets in memory that capsule to be planned with. To invoke the planner, first ensure that UniLang is running, then enter
C-c r v r
. The planner with then generate a plan if you were successful. It may take some time before the plan is completed. If you are using LPG-td as your planner, you should see: a few entries like:
TIME: 0.000300
if the plan was successful. To see the plan, use
C-r .sol
to move the cursor over the name of the solution file, and then run
C-x C-f
to open that file. You should see something like this:

; Version LPG-td-1.0
; Seed 14498422
; Command line: /var/lib/myfrdcsa/codebases/internal/verber/data/planner-library/lpg-td-1.0 -o date-20170205.d.pddl -f date-20170205.p.pddl -out /var/lib/myfrdcsa/codebases/internal/verber/data/worldmodel/worlds/date-20170205.p.pddl.LPG.sol -speed 
; Problem date-20170205.p.pddl
; Time 11.56
; Search time 0.22
; Parsing time 10.46
; Mutex time 0.84
; MetricValue 22.25


Verber is a wrapper around other planners, but it also is able to merge different planning domains, and even call code to generate other domains as part of the planning capsule rendering process. Unfortunately it is too lengthy to deal with here, and is still a WIP. It usually pulls in a .verb capsule from:

and outputs the generated capsule to
, before executing the planner on the capsule.

Running CLEAR (the Computer LEarning ARchitecture)

One of the neatest FRDCSA applications is CLEAR, which uses text to speech to read books to you. It is capable of pausing, forwarding and so on. It also records what you have read for your convenience. To invoke clear, ensure UniLang is running and then run:

cla -u -r <FILE>
where <FILE> is the name of a file containing text. CLEAR automatically converts mosts formats to text, so you should be able to use PDFs, HTML etc.

If successful CLEAR will eventually open a Perl/Tk window and then immediately begin reading. You can use PAUSE to pause it, but note, it will continue to read till the end of the current sentence.

Running RADAR and Packager

More recent versions of RADAR and Packager have streamlined the process. For now, you can still use them, but you have to be careful. Also, probably most of the RADAR wrappers besides "git" are probably outdated. To use, you do:

radar https://github.com/TeamSPoon/pfc
or whatever your repo is. It will prompt with (randomized (to prevent changes to the menu from causing the user to accidentally select the wrong item)) menu, enter whatever the number is for "Git" at the prompt and press enter. It will then ask for the name of the codebase. Press the number for pfc (or whatever the name of your repo is). Alternatively, you can select 0 and hit enter and it will allow you to enter the name. It will ask if you want to execute the git clone command, press y and enter. It shold then clone the repository and put it in

To continue on to archiving the software, jump to that directory by using

C-c r r
packager pfc
or whatever your repo is called. Note this version requires you to be in the parent directory of the repo you are packaging. You can package any directory by selecting y when it asks to create a tgz file. (If you run packager on a regular file, it will still allow you to archive it, it just won't ask you to create the compressed file.) Create the compressed file, then select "y" when it asks you to move the file to the

Now you must change directories to some directory *not* containing "pfc" or whatever your archive is called. (This again is a bug that has been fixed in the development codebase). Then run again:

packager pfc
and it will give you a lot of options. Select 1 for "Extract" and press yes to all prompts. It will uncompress the archive in the

Here is a trace of this in action:

andrewdo@panoply:~$ radar https://github.com/TeamSPoon/pfc
Subroutine DoCommand redefined at /usr/share/perl5/Packager/Package.pm line 178.
0) Freshmeat
1) SVN
2) CVS
3) Git
4) Debian Package
5) URL
6) Local File
7) Perl Module
8) SourceForge CVS
9) Google Code
10) SourceForge SVN
11) SourceForge
12) CPAN Module (Experimental)
What is the name of this codebase?
0) Other
1) teamspoon
2) pfc
$VAR1 = 'Structure';
$VAR2 = {
          'Type' => 'Choose',
          'Contents' => [
          'Result' => 'pfc'
$VAR3 = 'Record';
$VAR4 = 1;
cd /var/lib/myfrdcsa/repositories/git && git clone https://github.com/TeamSPoon/pfc
Execute this command?: y
Cloning into 'pfc'...
remote: Enumerating objects: 26, done.
remote: Counting objects: 100% (26/26), done.
remote: Compressing objects: 100% (21/21), done.
remote: Total 2648 (delta 7), reused 9 (delta 5), pack-reused 2622
Receiving objects: 100% (2648/2648), 1.57 MiB | 2.52 MiB/s, done.
Resolving deltas: 100% (2004/2004), done.
andrewdo@panoply:~$ pushd /var/lib/myfrdcsa/repositories/external/git
/var/lib/myfrdcsa/repositories/external/git ~ /var/lib/myfrdcsa/codebases/external /var/lib/myfrdcsa/repositories/external/git ~ ~ ~ ~ ~
andrewdo@panoply:/var/lib/myfrdcsa/repositories/external/git$ packager pfc
Subroutine DoCommand redefined at /usr/share/perl5/Packager/Package.pm line 178.
FIXME: Run this first before packaging a system from any of its dirs: ./softwareindexer  -p
Archive, then index directory <pfc>: y
tar -czf pfc.tgz pfc
Execute these commands?: y
Use < pfc-20190329 > to store < pfc.tgz >?: y
mkdir /var/lib/myfrdcsa/codebases/external/pfc-20190329
mv "pfc.tgz" /var/lib/myfrdcsa/codebases/external/pfc-20190329
Execute these commands?: y
andrewdo@panoply:/var/lib/myfrdcsa/repositories/external/git$ cd
andrewdo@panoply:~$ packager pfc
Subroutine DoCommand redefined at /usr/share/perl5/Packager/Package.pm line 178.
FIXME: Run this first before packaging a system from any of its dirs: ./softwareindexer  -p
Select CodeBase
0) Stash
1) Extract
2) ExtractMultiple
3) Build
4) Rebuild
5) Test
6) Edit
7) DpkgInstall
8) Upload
9) AptGetInstall
10) RemovePackage
11) RemoveSandbox
12) RemoveExternal
Choice: Extract
Checking InstallDir: </var/lib/myfrdcsa/sandbox/pfc-20190329>
mkdir -p /var/lib/myfrdcsa/sandbox/pfc-20190329
Execute this command?: y
cd /var/lib/myfrdcsa/sandbox/pfc-20190329 && tar -xzf "/var/lib/myfrdcsa/codebases/external/pfc-20190329/pfc.tgz"
Execute this command?: y
mv pfc pfc-20190329
Execute this command?: y
andrewdo@panoply:~$ pushd /var/lib/myfrdcsa/sandbox/pfc-20190329
/var/lib/myfrdcsa/sandbox/pfc-20190329 ~ ~ /var/lib/myfrdcsa/codebases/external /var/lib/myfrdcsa/repositories/external/git ~ ~ ~ ~ ~
andrewdo@panoply:/var/lib/myfrdcsa/sandbox/pfc-20190329$ cd pfc-20190329/
andrewdo@panoply:/var/lib/myfrdcsa/sandbox/pfc-20190329/pfc-20190329$ ls
examples  LICENSE.md  man  misc  pack.pl  pfc1.2  pfc2.2  prolog  README.md  t

Running Problemspace

Problemspace is fun little Emacs gimmick, it can be invoked by running:

M-x problemspace
Note it creates something like "The Matrix" but running in Emacs using Cyc assertions. (The current [2019-03-29,08:35:52] development version of FRDCSA is able to post sensor data to Problemspace).

Using FreeKBS2

FreeKBS2 is the Knowledge Based System of FRDCSA. It handles a few things, conversion between different knowledge interchange formats (like KIF, Perl Interlingua, Emacs Strings and Prolog), as well as persistence of assertions and even full reasoning in First-Order Logic with Equality.

Knowledge is partitioned into contexts which are similar to Cyc's concept of Microtheories. These are related assertions that express the truth about the domain in question. To list the Contexts that exist on your system, run

kbs2 -l
To view the contents of a context, move the cursor over the name of the context and press
C-u C-c s X
followed by
This makes that context the default context. Make sure UniLang is running, then press
C-c s k
and wait for a little bit as UniLang queries the FreeKBS2 and renders the output to the window. There are major-modes for both viewing and editing the contents of a viewed context.

Move into the window that says "all-asserted-knowledge for context <CONTEXT>", and press

C-h m
C-h b
to get a listing of the commands that one can use in that major-mode. To visit the Elisp source code for the current major-mode in a buffer, run
C-c C-k C-m

FreeKBS2 has a nifty feature called FreeKBS2-Ring. This is like the Emacs kill ring except FreeKBS2 allows you to do all kinds of things with the contents of the ring. The ring has a stack which is a list of entries. The idea of the stack is to create expressions. For instance you could piece together an assertion like ("loves" "person1" "beer"), and then do things with that. The first element of the stack is called the Top of Stack (TOS), in this case "loves". The ring consisting of this stack and another assertion might look like: (("loves" "person1" "beer") ("loves" "person2" "yogurt")) These are all in Emacs String notation. Most commands have to do with adding elements to the stack, shifting new stacks onto the ring, rotating these stacks and rings, and inserting their contents and popping them. They are similar to an RPN scientific calculator in addition to being similar to the kill-ring. Many FRDCSA Elisp interactive commands use the TOS. For instance, to place the current filename into the TOS, run

C-c k f n
to close the Ring viewer buffer. Then to insert the name of the file into your current buffer, run
C-c s i
Finally, to clear the stack run
C-c s c

You can also load an assertion in Emacs String notation by moving the cursor to the first parens of the any Elisp sexp and pressing

C-c s L

Systems Not Included In This Release

The FRDCSA is a large metaproject containing thousands of systems and due to constraints we have only been able to release several of the core systems. We are working to release all the other systems which gives the system more power. More will hopefully be included in the next release. Please note that very few of the external codebases have been released since we haven't completed vetting their licenses, and also to save space in this educational release of the Panoply VM.

Programming With FRDCSA

There are quite a few tools to help with programming, I will list some now.

	boss -  enables you to create and modify internal codebases
	perllib - a large collection of wrappers for various existing systems

Capability PerlLib System

The Perl modules for FRDCSA are sym-linked from their locations in subdirs of the internal and minor codebase directories to /usr/share/perl5