LLpro – A Literary Language Processing Pipeline for German Narrative Texts

An NLP Pipeline for German literary texts implemented in Python and Spacy (v3.5.2). Work in progress.

This pipeline implements several custom pipeline components using the Spacy API. Currently the components perform * Tokenization and Sentence Splitting via SoMaJo (Proisl, Uhrig 2016). Version 2.4. * POS tagging via SoMeWeTa (Proisl 2018). Version 1.8.1. * Lemmatization and Morphological Analysis via RNNTagger (Schmid 2019). Version 1.4.1. * Dependency Parsing via ParZu (Sennrich, Schneider, Volk, Warin 2009; Sennrich, Volk, Schneider 2013; Sennrich, Kunz 2014). Commit a15ae7f. * Named Entity Recognition via FLERT (Schweter, Akbik 2021). Version 0.12.2. * Recognition of References to literary Characters (proper nouns and common nouns, i.e. “Appelative”, cf. Krug et al., 2017) via a custom fine-tuned FLERT model aehrm/droc-character-recognizer. * Tagging of German speech, thought and writing representation (STWR) via custom fine-tuned BERT embeddings, similar to Brunner, Tu, Weimer, Jannidis (2020); model aehrm/modernbert-redewiedergabe. * Segmentation into Scenes via BERT Embeddings via a custom fine-tuned re-implementation of a model by Kurfalı and Wirén (2021); model aehrm/stss-scene-segmenter. * Coreference Resolution via BERT Embeddings (Schröder, Hatzel, Biemann 2021). Commit f34a99e. * Annotating Event Types to verbal phrases via BERT Embeddings (Vauth, Hatzel, Gius, Biemann 2021) Version 0.2, Commit 25fdf7e.

See also the section about the Output Format for a description of the tabular output format.

Usage

```text usage: llpro_cli.py [-h] [-v] [--version] [-X OPT] [--stdout | --writefiles DIR] --infiles FILE [FILE ...]

NLP Pipeline for literary texts written in German.

optional arguments: -h, --help show this help message and exit -v, --verbose --version show program's version number and exit -X OPT, --component-config OPT Component parameters of the form component_name.opt=value --stdout Write all processed tokens to stdout. --writefiles DIR For each input file, write processed tokens to a separate file in DIR. --infiles FILE [FILE ...] Input files, or directories. ```

Note: you can specify the resources directory (containing ParZu etc.) with the environment variable LLPRO_RESOURCES_ROOT, and the temporary workdir with the environment variable LLPRO_TEMPDIR.

Component options

Several components can be configured with the -X key. Notably:

• -X somajo_tokenizer.is_pretokenized=True skips tokenization, and assumes tokens separated by whitespace.
• -X somajo_tokenizer.is_presentencized=True skips sentence splitting, and assumes sentences separated by newlines.
• -X somajo_tokenizer.normalize_tokens=False does not normalize tokens. Incompatible with is_pretokenized=False.
• -X somajo_tokenizer.paragraph_separator='PAT' sets the paragraph separator pattern. Input text is split into paragraph at pattern occurences, and sentences always terminate on paragraph boundaries. Like Python's re.split, if capturing parentheses are used in PAT, then the text of each group in the pattern is also returned as paragraph. Performed before tokenization/sentence splitting.
• -X somajo_tokenizer.section_pattern='PAT' sets the sectioning paragraph pattern. Paragraphs fully matching the pattern are removed, except any group captured by parentheses used in PAT. Performed before tokenization/sentence splitting.
• -X coref_uhhlt.split_method='section' performs coreference only on section-level.
• -X <component_name>.disable=True disables the specific component

Installation

The LLpro pipeline can be run either locally or as a Docker container. Running the pipeline using Docker is strongly recommended.

WINDOWS USERS: For building the Docker image, clone using shell git clone https://github.com/aehrm/LLpro --config core.autocrlf=input to preserve line endings.

Building and running the Docker image

We strongly recommend using Docker to run the pipeline. With the provided Dockerfile, all dependencies and prerequisites are downloaded automatically.

```shell cd LLpro docker build --tag cophiwue/llpro .

or, if you want experimental features enabled

docker build --build-arg LLPRO_EXPERIMENTAL=1 --tag cophiwue/llpro-experimental .

```

After building, the Docker image can be run like this:

```shell mkdir -p files/in files/out chmod a+w files/out # make directory writeable from the Docker container

copy files into ./files/in to be processed

docker run \ --rm \ -e OMPNUMTHREADS=4 \ --gpus all \ # alternatively, e.g., --gpus "device=0" --interactive \ --tty \ -a stdout \ -a stderr \ -v "$(pwd)/files:/files" \ cophiwue/llpro -v --writefiles /files/out --infiles /files/in

processed files are located in ./files/out

```

Installing locally

Verify that the following dependencies are installed:

• Python (tested on version 3.7)
• For RNNTagger
  • CUDA (tested on version 11.4)
• For Parzu:
  • SWI-Prolog >= 5.6
  • SFST >= 1.4

Execute poetry install and ./prepare.sh. The script downloads all remaining prerequisites. Example usage:

```shell poetry install ./prepare.sh

NOTICE: use the prepared poetry venv!

poetry run python ./bin/llpro_cli.py -v --writefiles files/out files/in

if desired, run tests

poetry run pytest -vv ```

Developer Guide

See the separate Developer Guide about the implemented Spacy components and how to access the assigned attributes.

See also the separate document about the tabular Output Format for a description of the output format and a reference of the used tagsets.

See the folder ./contrib for scripts to reproduce the fine-tuning of the custom models.

Citing

If you use the LLpro software for academic research, please consider citing the accompanying publication:

Ehrmanntraut, Anton, Leonard Konle, and Fotis Jannidis. 2023. „LLpro: A Literary Language Processing Pipeline for German Narrative Text.“ In Proceedings of the 19th Conference on Natural Language Processing (KONVENS 2023), ed. Munir Georges, Aaricia Herygers, Annemarie Friedrich and Benjamin Roth, pp. 28–39. Ingolstadt, Germany: Association for Computational Linguistics. https://aclanthology.org/2023.konvens-main.3/

bibtex @inproceedings{ehrmanntraut-etal-2023-llpro, title = "{LL}pro: A Literary Language Processing Pipeline for {G}erman Narrative Texts", author = "Ehrmanntraut, Anton and Konle, Leonard and Jannidis, Fotis", editor = "Georges, Munir and Herygers, Aaricia and Friedrich, Annemarie and Roth, Benjamin", booktitle = "Proceedings of the 19th Conference on Natural Language Processing (KONVENS 2023)", date = "2023-09-18", address = "Ingolstadt, Germany", publisher = "Association for Computational Lingustics", url = "https://aclanthology.org/2023.konvens-main.3/", pages = "28--39" }

License

In accordance with the license terms of ParZu+Zmorge (GPL v2), and of SoMeWeTa (GPL v3) the LLpro pipeline is licensed under the terms of GPL v3. See LICENSE.

NOTICE: The code of the ParZu parser located in resources/ParZu has been modified to be compatible with LLpro. See git log -p df1e91a.. -- resources/ParZu for a summary of these changes.

NOTICE: Some subsystems and resources used by the LLpro pipeline have additional license terms:

• RNNTagger: see https://www.cis.uni-muenchen.de/~schmid/tools/RNNTagger/Tagger-Licence
• SoMeWeTa model german_web_social_media_2020-05-28.model: derived from the TIGER corpus; see https://www.ims.uni-stuttgart.de/documents/ressourcen/korpora/tiger-corpus/license/htmlicense.html

This program 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 3 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 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

References