Black Box Generation with KPML4

(Last update: black box capabilities provided with KPML4; updated: June 2006. Socket capability, Dec 2007; some extra options, Jan 2016)

Overview and Purpose

The black box generator provides an example of a simple generator for English for Windows. It is called a black box generator because no interaction is allowed with the generator apart from the basic input-output cycle. The input consists of individual semantic specifications, and the generated string is produced as output. There is no debugging, no inspection of the generation process, no interactive inspection of generation results. It should therefore only be used with fully debugged linguistic resources, otherwise errors can arise in generation and there is no possibility of inspecting their cause. It can be used either to give an indication of generation performance from a variety of input specifications, or as a generation server for some application that only needs to produce natural language output without worrying about how it is done. The basic input-output behaviour is managed via files as described below. This means it is trivial to set up an input-output generation demonstration loop from a pair of simple text editors or text editor buffers.

Instructions for installation and basic use

The blackbox generation image should be downloaded and placed somewhere on your computer. It does not matter where. Then, when started the generator just sits and waits for a semantic input. When one comes, it generates a corresponding English sentence. It then waits for a further semantic input, and so on. The input and output is managed via files. Whenever the specified input file contains a semantic specification, it is generated. This input (and the file) is then discarded (i.e., the file is removed). The generated output is written to another file. 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.

Below we will see that the behaviour of the black box generator can be controlled more finely by providing other special commands in the input file; this makes it almost usable for real generation in a number of simple contexts. If none of these control possibilities are used, then the default behaviour is that generation is in English. Moreover:

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". (For information on how to change this, see below.)

Finally, if you are using the Spanish blackbox rather than the English one, please make sure that you only create the SPL input file after starting the blackbox first; this is a minor bug already corrected in the English version. If you do not do this, then the first SPL will not be generated.

Semantic input

The semantic specifications that must be placed in the input file are bare Sentence Plan Language expressions (SPLs). This is the usual form of semantic input used by KPML. 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).

Note: the generation bank contains examples, the input for the blackbox generator is not in the form of examples (which would not in any case be sensible since examples are prestored examples for debugging and maintanance of grammars) but in the form of the bare SPL--this is the information contained as the :logicalform slot in the example definitions. An example of a simple SPL expression is:

(s / sail :actor (p / ship :determiner some :number plural) :tense past)

which, if placed in the SPL input file, would make the black box generator produce the string "Some ships sailed." in the output file.

When the blackbox is switched into HTML or XML mode (by giving an :html or :xml command, see below), then input SPLs may contain annotations involving markup. This markup is then produced in the places in the surface string corresponding to the indicated semantic entity. For example, an SPL input of the form:

(s / sail :actor (p / ship 
    :determiner some :number plural) :tense past
    :temporal-locating 
          (m / day :name Monday 
                   :annotation (:xml emph :style date))
)

will produce something like the string:

Some ships sailed on <EMPH STYLE="DATE">Monday</EMPH> .

(:xml |lowercase-tag| :|complex-attribute:name| value)

Task for the client

Note that a client program using the black box generator as a generation server needs to do the following work:

1. Create an appropriate SPL expression for the meaning to be generated
2. Write the single SPL expression at the beginning of the SPL input file.
3. Wait for and then read the contents of the generation output file.
4. Either stop by writing the single symbol ":stop" (i.e., stop with a colon directly in front of it), or continue to the next SPL to be generated by returning to (1).

It is straightforward to create black box generators of this kind from KPML. The question as to what interaction with an application program makes the most sense will depend on individual applications. As an example of how black box generators of this kind can be created, the additional code used to create a simpler variant of the one that is downloadable is given here (with an extension of .txt so that it does not executed or swallowed by security systems).

More complex control of the black box generator

The introduction above is sufficient in order to generate the first SPLs and to see what kind of interaction is involved. For more serious use, slightly more control is useful. For example, we might want to update the linguistic resources with a more recently released set, or to change the language to generate with a different resource set, or to update the lexicon or domain information that is available to the generator. We have already seen that in fact two types of input can be written to the SPL input file: either an SPL expression as illustrated above, or a command (e.g., ":stop"). The full list of commands that are interpreted by the black box generator is contained in the following table; many of these are toggles, which means that they set a mode alternately ON and OFF on subsequent uses.

In addition, new linguistic resources can be loaded (or reloaded) by giving the name of those resources as a single keyword. Thus, if the input file is given the single command:

:german

then it will try and load the linguistic resources for the language variety German from the appropriate place (see the configuration file descriptions in order to see how to define what the appropriate place is). Of course, if you do not have the necessary linguistic resources loaded on your computer in the defined appropriate place, then this command will simply empty out the black box generator so that it cannot generate anything.

Control of the black box generator from the command line

The easiest way of starting the black box generator is simply by clicking twice on it once it has been downloaded. This starts it up with all of the default settings mentioned above. It is also possible, however, to give it some command line parameters, so that even its default start-up behaviour is different. This is particularly useful, for example, for changing the input and output files that the black box is going to use when looking for its input and writing its output subsequently.

To use command line parameters, you must start the black box generator from a command line--for example, from the DOS interaction window reachable under your Start menu. The parameters are then written following the black box generator's image name. Thus, if you have saved the black box generator with its default name--kpml4-bbox.exe--then it can be started in strictly monolingual and verbose tracing mode by issuing a command such as:

The default input and output files can be changed by using the keywords :in and :out. Thus the following command line call will start up the black box generator as usual, but it will look for the input SPLs in the file "E:\my-input\spls.lisp" and place the outputs in the file "A:\floppy-output.txt".

Particularly useful, if you are developing and adding in new linguistic resources, such as further lexical items, is to reconfigure the blackbox so that it expects the linguistic resources to be in a place that you specify. This can be done loading a specified configuration file in which the *root-of-resources* line is given pointing to the application-specific resources. This must be a folder structured in usual way that KPML expects for linguistic resources, e.g., LANGUAGE\Lexicons\... and so on.

Finally,

starts up the blackbox, pre-loads the user-defined lexicon additions in the specified file, and finally changes to a socket-based interaction across port 10200 on the machine where the black box is running. It is up to the user to provide a client that communicates with the blackbox across this socket.

Full list of the command line options

Remember that all of these command lines have to be written on a single line. The command line parameters can be given in any order. The full list is given in the following table.

The :first parameter is particularly useful for setting up the generator locally so that it is ready to generate with locally prepared resources. For example, the following command line call (which could then of couse itself be placed in a bat file for instant execution), says that input semantic specifications are to be taken from the file "C:\input.lisp", output is to be generated in the file "C:\out.txt", and that before any of that happens the complete locally available linguistic resources for the language variety Greek are to be loaded. Furthermore, since the black box generator cannot know where the Greek resources will have been placed locally, it additionally reads the configuration file beforehand so as to know where local resources are stored. (This means that the configuration file should contain at least a line beginning "*root-of-resources*" that gives this information).

Alternatively, the following command line leaves the input and output files as their default values, and instead before generating anything just loads a locally available lexicon, presumably providing an extension of the default English lexicon that comes with the black box generator when downloaded.

The following does the same, but allows you to specify (via the configuration file) exactly where on your installation the linguistic resources (including the lexicon) are located.

Whereas the above requires that the normal KPML configuration file is in one of the regular spots that KPML looks for such files (see the relevant documentation), the following allows you to specify an arbitrary file to use as the configuration file

And the following allows control of where grammars are to be found and which one is to be loaded all from the command line. Starting the following with the empty blackbox would therefore have the same effect as that of the preloaded Spanish blackbox, as long as the folder given is actually where the resources are to be found of course.

Last update: 8th January 2016

Back to KPML main page