Black Box Generation with KPML

Stopping generation
Black box creation


The black box generator provides an example of a very simple generator for English for Windows. It is called a "black box" generator because you cannot see inside it: it simply takes as input a semantic specification and produces as output the corresponding English sentence.

Input and output is done via files: i.e., when started the generator sits and waits for a file containing semantic input. When one comes, it generates a corresponding English sentence to an output file. The input (and the file) is then discarded and the generator waits for a further file containing semantic input to appear. And so on. Each newly generated sentence replaces the previous sentence in the output file. In order to stop the entire process, the single item ":stop" must be placed in the input file.

Since this is intended for illustrative purposes only, there is very little that the user can do with the generator apart from just generate from semantic specifications.


The single file (11.7Mb) must be downloaded and unzipped. This will produce a file kpml3-bbox.exe (31.6Mb). No further installation is necessary. Clicking twice on the exe-file will start the black box generator; this will bring up a DOS window which simply reports what it is doing--this will mostly consist of waiting for input and not finding any. It will then continue to wait for a file containing semantic input to be created.

Input and testing

The default settings contained in the black box generator are that both the input file and the output file reside in the folder C:\tmp. The input file is called "spls-in.lisp"; the output file is called "kpml-out.txt". If the folder C:\tmp does not exist on your system, you will need to create it.

To generate, and to test installation, click twice on the exe file. Then create a file containing a single SPL (see below) semantic specification called spls-in.lisp in the C:\tmp folder. An example spls-in.lisp file is given here. Note that the file is a lisp file: it must have the single extension ".lisp".

If you download this file to the C:\tmp folder while the black box generator is running, the generator should create (almost) immediately the corresponding output file, called kpml-out.txt, also in C:\tmp. This is the result of generation. Creating an input file (of the same name) with a different semantic specification, or writing a different semantic specification to the front of the file, will then create a new version of the output file with a newly generated sentence. One can then create a simple input-generate-edit-regenerate loop by using a text editor such as Emacs with auto-revert-mode in the buffer looking at the output file.

If you use the example input file provided, then the file kpml-out.txt should be created containing the single string: "In spite of the bad weather , we will go to the lake ." If this works, then the blackbox generator is installed and running correctly.

The form of the semantic input is the usual (for KPML) sentence plan language (SPL). Numerous examples of SPL for a variety of languages are given in the example sets of the generation bank (but see here for the English examples: the example spls-in.lisp file above takes its SPL from the Concessions example set). The input for the generator must consist of the bare semantics--which is the information found under the :logicalform slot of the examples.


If you follow the above instructions and the DOS window does not show any semantic input file being found, then the most likely cause is that you have not managed to create a file with exactly the required name in exactly the required folder. Check that your version of Windows is not hiding spurious extension information from you (i.e., that the file is really called "spls-in.lisp" and not "spls-in.lisp.txt").

A syntactically ill-formed semantic input will simply be rejected with the message "SPL read error".

In cases where you give untested semantic input to the generator, you may force the generator into a state where it does not know how to continue. When this happens, it will stop and ask you to make a manual choice of grammatical feature in the DOS window. This is done by typing a number from a multiple choice list. Since it it not possible to debug the grammar using the blackbox generator, it is a good idea to use the blackbox either only with tested semantic inputs or with automatically created semantic inputs that can then be guaranteed to lie within the generation competence of the generator.

Stopping generation

The generator will continue to wait for new semantic input files to appear until explicitly stopped. To do this, a new spls-in.lisp input file must be written out which contains just the single word :stop (i.e., "colon-s-t-o-p"). The file here can be used for this function if saved to the C:\tmp folder. When a file containing :stop is present, the generator exits.

Creation of Black Box Generators

It is straightforward to create such black box generators from KPML. The question as to what interaction with an application program makes the most sense will depend on individual applications. It is therefore left very simple in this example. More sophisticated uses could involve socket, dde, or ddl-guided interactions, etc. The generated output is also simple in that is a simple string; more sophisticated use of KPML could select to produce markup or more ambitious structures.

As an example of how this black box generator was created, the additional code used to create it is given here (with an extension of .txt so that it does not executed or swallowed by security systems).

A somewhat more flexible blackbox generator is available here. This allows selection of other linguistic resources and various user control options. If you need a version of the simple blackbox generator for another of the languages supported by KPML, let me know.

Back to KPML main page