presage Documentation



Presage is an intelligent predictive text entry platform. Presage exploits redundant information embedded in natural languages to generate predictions. Presage's modular and pluggable architecture allows its language model to be extended and customized to utilize statistical, syntactic, and semantic information sources.

A predictive text entry system attempts to improve ease and speed of textual input. Word prediction consists in computing which word tokens or word completions are most likely to be entered next. The system analyses the text already entered and combines the information thus extracted with other information sources to calculate a set of most probable tokens.

A typical presage-based application would display the set of most probable tokens (i.e. a list of suggestions) to the user and automatically enter the desired token after the user selects it. If the list of suggestions does not contain the desired word, the user continues entering text until the correct suggestion is offered or until the user is done entering text.

Presage is fundamentally different from predictive input technologies commonly found on mobile phones, which might more accurately be described as 'disambiguating text entry' rather than 'predictive text entry' systems. Such systems do not try to guess what the user intends to write in the future, only to determine what they most-likely intend to write in the present, given their past input. Presage, on the other hand, actively predicts the what the user intends to write, and only reverts to word completion mode if the prediction did not contain the desired token.

Presage is free software. It is distributed under the term of the General Public License.

Matteo Vescovi

Getting started

Copyright (C) 2008  Matteo Vescovi <>
Getting started with Presage in 5 minutes or less

1) Download, build and install presage

Follow the instructions in the README file to install presage on
your system.

2) Run the demo program and the simulator

Presage is an extensible predictive text entry platform. It
provides a clean, simple application programming interface and a higly
configurable and extensible predictive framework in the form of a

Presage is not an end-user application. However, a number of demo
applications are included:
- presage_demo: ncurses based demonstration program
- presage_demo_text: text based demonstration program
- presage_simulator: simulates predictive process and reports on
  predictive performance

2.a) presage_demo 

This demo displays the text entered so far in the top window that
stretches across the screen.  The current prediction is displayed
immediately underneath the text window, at the leftmost position.
Previous predictions are displayed in cronological order to the right
of the current prediction.  Subsequent predictions are displayed in
the lefmost position, and previous predictions are shifted to the
right, so that the current prediction is always on the left hand side.

Context switches are marked in some way (either a vertical bar or a
box enclosing the other prediction boxes). [not implemented yet]

2.b) presage_demo_text

This demo works similarly to presage_demo, except that it is much
more barebones. It is useful when debugging.

2.c) presage_simulator

This simulator evaluates the performance of the predictive engine on a
given text file.

The simulator requires a text file to be passed as argument. It reads
each character from the input file and sends it to the presage
prediction engine. The simulator counts the number of key presses
required to enter the desired text using the presage prediction
engine and the number of key presses required to enter the same text
with no prediction enabled.

At the end of the simulation, it generates a report on predictive
performance (expressed in terms of Keystrokes Savings Rate) and prints
it to standard out.

3) Tweak presage to your needs

3.a) presage.xml

Presage is extensible and configurable. Presage's extensibility
comes from a range of predictive mechanisms used to generate
predictions. You can decide what plugins to enable and what predictive
resources to tie those plugins to. All configuration variables can be
controlled by editing the XML configuration file (either
~/.presage.xml or presage.xml in the etc/ directory where
Presage was installed - usually /etc -, whichever is found first).

Feel free to experiment with different settings: try enabling
different plugins, or changing individual plugins configuration
values. presage.xml comes with comments describe what each
configuration variable is about.

3.b) text2ngram

If you wish to improve presage's predictive performance, or you
want presage to predict in your native language, you will need to
generate resources required by the predictive plugins. Currently, most
predictive plugins are statistical plugins which require an n-gram

You can easily generate an n-gram database suitable for consumption by
presage's plugin with the included text2ngram tool. Feed your
collection of text in your native language or domain-specific text to
text2ngram and generate customized predictive resources to improve the
quality and accuracy of the predictions.

4) Write a program that uses presage

Below is a simple program that demonstrates how to use the C++
interface to presage.

#include "presage.h"
#include <iostream>

/* Simple example callback that tracks past context with a string.
 * Using a callback object decouples the user application from the
 * chosen text buffer (which could be a simple string, a graphical
 * text widget, a file stream, etc.) and frees the caller from having
 * to explicitly notify of any updates to the context. Presage will
 * invoke on the callback whenever access to contextual data is
 * required.
class ExampleCallback : public PresageCallback
    ExampleCallback(const std::string& _past_context) : past_context(_past_context) { }

    std::string get_past_stream() const { return past_context; }
    std::string get_future_stream() const { return empty; }

    const std::string& past_context;
    const std::string empty;


int main(int argc, char** argv)
    std::string context;
    ExampleCallback callback(context);
    Presage presage(&callback);
    std::string buffer;
    std::vector< std::string > predictions;

    for (;;) {
        // prompt user and append line into context buffer
        std::cout << "> ";
        getline(std::cin, buffer);
        context += buffer;

        // request prediction
        predictions = presage.predict ();

        // print predictions
        for (int i = 0; i < predictions.size(); i++) {
            std::cout << i << ':' << predictions[i] << std::endl;

    return 0;

This program creates an instance of Presage and prints the
predictions generated by presage to screen after each text fragment
input by the user.

The instructions to watch for are on the first line in main() which
initializes presage and on line 21 which tells presage what text
the user entered and asks presage to generate a prediction.

Presage's API includes other methods, all accessible through the
Presage class, defined in presage.h.


Copyright (C) 2008  Matteo Vescovi <>

Presage is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


Generated on 9 Feb 2015 for presage by  doxygen 1.6.1