candcapi - HTTP API to access the C&C/Boxer pipeline.
C&C tools is a suite of software for linguistic analysis of the English language, including a tokenizer, several taggers and a parser. Boxer is a tools for deep semantic analysis that takes in input the output of the C&C parser. Together, the C&C tools and Boxer form a pipeline toolchain to perform a complete analysis on English text. Here is an example:
$ curl -d 'John loves Mary.' 'http://127.0.0.1:7778/raw/pipeline'
sem(1,[1001:[tok:'John',pos:'NNP',lemma:'John',namex:'I-PER'],1002:[tok:loves,pos:'VBZ',lemma:love,namex:'O'],1003:[tok:'Mary',pos:'NNP',lemma:'Mary',namex:'I-PER'],1004:[tok:'.',pos:'.',lemma:'.',namex:'O']],merge(drs([[]:B,[]:C],[[1003]:named(B,mary,per,0),[1001]:named(C,john,per,0)]),drs([[]:D],[[]:rel(D,B,patient,0),[]:rel(D,C,agent,0),[1002]:pred(D,love,v,0)]))).
The main entry point to the C&C/Boxer API is
$CANDCAPI/$FORMAT/pipeline
$CANDCAPI is the URL of the API installation. $FORMAT is either raw or json, so possible entry point include:
http://my.installation.of.candcapi.net/raw/pipeline
http://my.installation.of.candcapi.net/json/pipeline
The text to analyze must be passed as POST to the HTTP request. The command line options for Boxer are passed as URL paramerers. Here are listed:
- Option (values (default)) description
- copula (true, false) the copula will introduce an equality condition
- instantiate (true, false) generate Prolog atoms for all discourse referents
- integrate (true, false) produces one DRS for all input sentences
- modal (true, false) modal DRS-conditions are used
- nn (true, false) resolves noun-noun relations
- resolve (true, false) resolve all anaphoric DRSs and perform merge-reduction
- roles (proto, verbnet) role inventory (proto-roles or VerbNet roles
- tense (true, false) tense is represented following Kamp & Reyle
- theory (drt, sdrt) Standard DRSs with drt, Segmented DRSs with sdrt
- semantics (drs,pdrs,fol,drg,tacitus,der] The basic (and default) formalism of semantics is drs, but other formats are also possible: pdrs (DRSs with labels, following Projective DRT); fol (first-order formula syntax); drg (discourse representation graphs); tacitus (Hobbsian semantics); ccg (input CCG derivation, nicely printed).
Here's an example using the option semantics to get a first-order logic formula:
$ curl -d 'Every man loves a woman' 'http://127.0.0.1:7778/raw/pipeline?semantics=fol'
fol(1,not(some(A,and(n1man(A),not(some(B,some(C,and(r1patient(B,C),and(r1agent(B,A),and(v1love(B),n1woman(C))))))))))).
For a more extensive description of the options of Boxer see the
official documentation.
NOTE the link http://svn.ask.it.usyd.edu.au/trac/candc/wiki/BoxerOptions is dead.
Output formats
The API can return either raw text or JSON. The raw text version corresponds to the standard output of the C&C pipeline. The JSON version is a simple JSON structure containing both the standard output and the standard error:
{"err": "standard error", "out": "standard output"}
Other URLs
It is possible to access the single tools separately by using the folliowing URLs:
$CANDCAPI/$FORMAT/t
$CANDCAPI/$FORMAT/candc
$CANDCAPI/$FORMAT/boxer
The tokenizer t takes in input a normal text. The parser candc takes in input a tokenized text, i.e. a list of words separated by whitespace. boxer takes in input the Prolog output of the C&C parser. For convenience, also the combination of intermediate steps of the pipeline are included in the API:
$CANDCAPI/$FORMAT/tcandc
$CANDCAPI/$FORMAT/candcboxer
respectively, the call the combination tokenizer/parser and parser/Boxer.
To see the version af C&C/Boxer used by the API:
$CANDCAPI/$FORMAT/version
Graphical output
Discourse Representation Graph is a semantic formalism described in the paper V. Basile, J. Bos: Towards Generating Text from Discourse Representation Structures. The C&C/Boxer API provides an entry point to generate a PNG image of the DRG of a given text:
$CANDCAPI/drg
The URL accepts the same GET parameter as pipeline and returns a raw PNG file.