Package: pypolibox
pypoliboxpypoliboxis a database-to-text generation (NLG) software built
on Python 2.7,NLTKand Nicholas FitzGerald’spydocplanner.Using a database of technical books and some user input, pypolibox
generates sentences descriptions. These descriptions are then used by
theOpenCCGsurface realiser to generate written sentences in German.InstallationPrerequisitesIn order to generate sentences (instead of abstract sentence
descriptions), you will need to installOpenCCG(tested with version
0.9.5). Make sure that you can calltccgfrom the command line,
e.g. by adding theopenccg/bindirectory to your$PATH.Under Linux, you’d have to add something like this to your.bashrc:export PATH=/home/username/bin/openccg/bin:$PATH

export OPENCCG_HOME=/home/username/bin/openccg
export JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk-amd64Under Windows, you’ll have toset the environment variablesOPENCCG_HOME,JAVA_HOMEand add the full path of youropenccg/bindirectory to thePATHvariable.pywin32also needs to be installed under Windows.Install from PyPIpip install pypoliboxUnder Linux, you might have to prepend that command withsudoor
execute it as root. Under Windows, you’ll need to run this command in aconsole with administrator rights.Install from sourceYou might also need superuser/admin rights for this (see above).git clone https://github.com/arne-cl/pypolibox.git
cd pypolibox
python setup.py installUsageCommand line usagepypoliboxcan be used from the command line or from within a Python
interpreter. To see all the available options, enter:pypolibox -hTo find books that are written in German and use the
programming language Prolog, type:pypolibox --language German --proglang Prologor, if you prefer short but cryptic commands:pypolibox -l German -p PrologYou can choose between several output formats using the-oor--output-formatargument.openccggenerates sentences using OpenCCG (default option)textplan-xmlgenerates an XML representation of the textplanstextplan-featstructgenerates a feature structure representation (nltk.featstruct)hldsgenerates an HLDS XML representations of all the sentences.The following example query will generate HLDS XML snippets describing books
about Prolog written in German:pypolibox --language German --proglang Prolog --output-format hldsFurther usage examples can be found in thepypolibox.database.Queryclass documentation.Library usageIf you’d like to accesspypoliboxfrom
within a Python interpreter, you can simply use the same arguments.
Instead of a string like-l German -p Prolog, you will have to
provide your arguments as a list of strings:Query(["-l", "German", "-p", "Prolog"])This query would be equivalent to the command line queries above.pypoliboxis built as a pipeline, where each important step is
represented by a class. Each of these classes function as the input
of the next class in the pipeline, e.g.:query = Query(["-l", "German", "-p", "Prolog"])
Results(query)
Books(Results(query))
...
TextPlans(AllMessages(AllPropositions(AllFacts(Books(Results(query))))))If you instanciate a Query with your query arguments, you can use
thisQueryinstance as the input of aResultsinstance
(which contains the data that the database provided for your query),
which in turn can be used as the input of aBooksinstance etc.Of course, you wouldn’t want to chain all those classes just to retrieve
textplans. To do so, simply use one of the functions provided in thedebugmodule, either by running thedebug.pyfile in
the interpreter or by importing it:import debug
debug.gen_textplans(["-l", "German", "-p", "Prolog"])This function call would return the same results as the aforementioned
command line calls. For further testing, trydebug.testqueriesanddebug.error_testqueries, which
basically are lists of predefined valid and invalid query arguments and which
can be used to query the database (and see how errors are handled).DocumentationThe documentation is availableonline,
but you can always get an up-to-date local copy usingSphinx.You can generate an HTML or PDF version by running these commands in
pypolibox’sdocsdirectory:make latexpdfto produce a PDF (docs/_build/latex/pypolibox.pdf) andmake htmlto produce a set of HTML files (docs/_build/html/index.html).Package OverviewThe pypolibox package contains the following modules:Thepypoliboxmodule is the main module, which is invoked from the
command line.Thedatabasemodule handles the user input, queries the database and
returns the results.factsconverts those results into attribute value matrices.Thepropositionsmodule evaluates those facts (positive, negative,
neutral).Thetextplanmodule takes those propositions and turns them into
messages. In contrast to propositions, messages do not contain duplicates
and add comparative information. Rules will be used to combine those
message into constituent sets and ultimately into one text plan. Thetextplanmodule also allows exporting those text plans in XML format.Therulesmodule contains the rules used by be thetextplanmodule
to combine messages into constituent sets and textplans, respectively.Themessagesmodule generates messages from propositions, which will
be used by thetextplanmodule.Thelexicalize_messageblocksis the “main” module of the
lexicalization. For each message block in a textplan, it generates one or
more possible lexicalizations which are then realized by therealizationmodule.Thelexicalizationmodule generates lexicalizations (in HLDS-XML
format) for each message, which are used by thelexicalize_messageblocksmodule to form lexicalizations of complete
message blocks.A note on terminology: A message block inpypoliboxis basically an
instance of theMessageclass, e.g an “id” message block. This
“id” message block in turn consists of several messages, e.g. an
“authors” message and a “title” message.Therealizationmodule takes a lexicalized phrase or sentence (in
HLDS-XML format) and converts it into a surface realization (with the
help of OpenCCGstccgexecutable).Thehldsmodule allows to convert textplans from anltk.featstruct-based format to HLDS-XML and vice versa. In addition, the
module can produce attribute-value matrices of these textplans as
LaTeX/PDF files.LicenceThe code is licensed under GPL Version 3. The grammar fragment is licensed
underCreative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.AuthorArne NeumannAcknowledgementsThis software reimplements parts of the Java-basedJPoliboxtext-generation software written by Alexandra Strelakova, Felix Dombek,
Mathias Langer and Till Kolter. pypolibox also includes a heavily
modified version of Nicholas FitzGerald’spydocplanner, which he
released under a Creative Commons license (not specified further).
The German OpenCCG grammar fragment that comes with pypolibox was written by
Martin Oltmann.News1.0.2 (2014-05-17)Release data: 17-May-2014added Windows-specific requirements to setup.py (winpexpectvs.pexpect)README now covers installation prerequisites1.0.1 (2014-05-13)Release date: 13-May-2014installation viapiporpython setup.py installnow adds two programs
to your path:pypoliboxandhlds-converteradded new output formats (--output-formatparameter):
textplan featstructs, HLDS XMLdocumentation is now hosted atreadthedocs.orgconverted documentation from epydoc to sphinxadded make file, license file1.0.0 (2014-30-04)Release date: 30-Apr-2014pypolibox is now licensed under GPLv3OpenCCG grammar fragment (CC-BY-NC-SA 4.0 licensed) now shipped with codefirst release via PyPIgot rid of configuration filefixed some errors in the documentation