Overview

This section will lay out the design of the application and what choices were made to get to the final result. These choices are often the question of how to save the data in a way that it can be easily reused and what ontologies to use. The overview in Figure 11 shows all the steps schematically, which are the following:

1. Extract pieces of text from raw files.
2. Split pieces of text into sentences.
3. Parse sentences into constituency trees.
4. Add metadata to the constituency trees using a Solid pod.
5. Reconstruct the original sentences, enriched with metadata.

Each of the following sections will go into more detail on one of these steps.

Extracting Text From Files

The first step in the process is to acquire the text that is contained in the player logs in structured data. As these logs can come in many different formats, it is important to first turn them into a known structure, independently of their original format. There are many ways to store plain text in RDF, but the one used in this thesis uses the definition by IOLite, namely iol:Text.

IOLite[17] (prefix iol), short for “Information Objects ontology lite” is an extension of the DOLCE Ultralite[18] (prefix dul) upper-ontology. DOLCE Ultralite is an upper-ontology that provides concepts that can be reused by other ontologies so there is interoperability among these ontologies. DOLCE Ultralite focuses on physical and social concepts and IOLite is an extension that, as the name implies, allows the representation of information objects. An information object is, according to the definition by DOLCE Ultralite:

A piece of information, such as a musical composition, a text, a word, a picture, independently from how it is concretely realized.

Which corresponds to what is needed to store the texts. To indicate which value the piece of text has, the predicate rdf:value is used. An example is shown in Listing 8.

<http://pantheonparty.com/text/1> a         iol:Text;
                                  rdf:value "Beowulf sees Johan on top of the
                                  hill. He draws his sword and walks closer."@en.

Since each type of data requires a specific approach, this was done manually for each set of logs. Most of the time, an iol:Text was created for each paragraph, but some sources did not have paragraph, so other divisions were made too.

Splitting Text Into Sentences

The second step to analyzing text was to split the text up into sentences that can be analyzed separately. While this step in itself is pretty straight-forward, it is important to split the possibly large pieces of text up into smaller, manageable pieces. The main design consideration was how to model the data in linked data.

As the previous step uses iol:Text to store raw, untreated text, this step uses that format to read in text as well. It uses iol:Sentence for sentences extracted from this text. The value of the iol:Sentences is indicated with the predicate rdf:value and to link the iol:Text and iol:Sentences, the predicate dul:hasComponent is used. The piece of text in Listing 8 from the previous part will turn into the data shown in Listing 9.

<http://pantheonparty.com/sentence/1> a iol:Sentence;
            rdf:value "Beowulf sees Johan on top of the hill.".

<http://pantheonparty.com/sentence/2> a iol:Sentence;
            rdf:value "He draws his sword and walks closer.".

<http://pantheonparty.com/text/1> dul:hasComponent <http://example.com/sent/1>,
                                                   <http://example.com/sent/2>.

Constituency Tree Parsing

The next step in analyzing sentences is parsing the sentences into a constituency tree. Once this constituency tree is constructed, it needs to be converted into RDF, for which a data model needs to be constructed.

The main ontologies for this task are the NLP Interchange Format 2.0 core ontology[19] (prefix nif) and the Ontologies of Linguistic Annotation (OLiA) [20] (prefix olia). Both of these are commonly used when representing NLP data in RDF.

The NLP Interchange Format (NIF) is a format that provides interoperability between different NLP tools, by providing specifications, ontologies and software. For this step, mainly the NIF core ontology will be used, as this provides most of the predicates needed. More specifically the following predicates will be used:

• nif:isString: Indicates the value of a node (and its children).
• nif:posTag: The Part of Speech tag, as an OLiA tag (see below).
• nif:subString and nif:superString: Indicates that the object is a part of the subject and vice versa.
• nif:beginIndex and nif:endIndex: Indicates where a substring starts and ends in the superstring, both zero-based, inclusive indices.

The Ontologies of Linguistic Annotation (OLiA) is a set of definitions for many different types of NLP annotations. In this case, their definitions of the part of speech (POS) tagging of words are used to tag the constituency trees.

One of the sentences from the previous examples “Beowulf sees Johan on top of the hill.”, leads to the constituency tree in Figure 12. Since printing the whole tree in Turtle format would be too long, only two nodes are serialized. The first one is the root node, containing the entire sentence. The second one is the noun phrase “the hill”. Both can be seen in Listing 10. As can be seen, the major difference is the fact that non-root nodes have the predicates nif:beginIndex, nif:endIndex and nif:superString. The latter node has a begin and end index of 3 and 10 respectively, as the parent node represents the value “of the hill”, of which we need to take characters 3 to 10 (inclusive) to get “the hill”.

# Root node
<http://pantheonparty.be/constituency-node/1> a nif:String, iol:Sentence;
            nif:isString "Beowulf sees Johan on top of the hill.";
            nif:posTag olia:Sentence;
            nif:subString <http://pantheonparty.be/constituency-node/2>,
                          <http://pantheonparty.be/constituency-node/3>,
                          <http://pantheonparty.be/constituency-node/4>.

# Noun Phrase node

<http://pantheonparty.be/constituency-node/10> a nif:String;
            nif:isString "the hill";
            nif:beginIndex 3;
            nif:endIndex 10;
            nif:posTag olia:NounPhrase;
            nif:superString <http://pantheonparty.be/constituency-node/9>;
            nif:subString <http://pantheonparty.be/constituency-node/11>,
                          <http://pantheonparty.be/constituency-node/12>.

Recognizing Entities using Solid Data

This step consists of two separate tasks, namely getting the Solid data and extracting the entities. Both will be described below.

Getting Solid Data

The user should be able to store the data of their characters and campaigns in their personal Solid pod. This way, they have control over their own data and can link to other pods to create a decentralized storage of the characters. Before the data can be analyzed, a local copy of this data is needed that can be accessed by the SPARQL engine for easier processing.

The Community Solid Server (CSS) has a functionality that allows the use of client credentials, which removes the need to store the users password to log in, but utilizes a generated key that can be revoked by the user when needed. With these credentials, the application can request a token id and secret that allows it to make request authenticated as the user for a certain period of time.

By starting from a user-provided root and recursively fetching all resources in the pod, all data can be stored to a quad store. A quad store is useful because this data model orders triples using named graphs. By using these named graphs, we can keep track of the source of each triple. By constructing a SPARQL INSERT query, all the data can be added to the central database.

Recognizing Entities

With all the previous steps set up, a basic form of Named Entity Recognition can be performed. In this step, each proper noun or noun phrase in the constituency tree is matched to the names of the characters that are currently known in the database.

Names can consist of one word, such as “Heksina” or “Serafina”, which are just one proper noun. Names can also consist of two words, such as “Lady Ghost”, in which case the full name is a noun phrase and needs to be matched as a whole. Because of this, both proper nouns and noun phrases need to be checked to get all the references.

To link the node in the constituency tree and the character it references, the itsrdf[21] ontology is used, which was made by W3C to allow mapping of the Internationalization Tag Set[22] into RDF data. This step only uses the taIdentRef predicate, which indicates which identifier the subject references to.

In the example sentence “Beowulf sees Johan on top of the hill.”, the nodes representing “Beowulf” and “Johan” will get a itsrdf:taIdentRef link to their respective character. We can see this for the node containing the proper noun “Beowulf” in Listing 11.

# other NIF tags have been removed for brevity
<http://pantheonparty.be/constituency-node/20> a nif:String;
                    nif:isString "Beowulf";
                    itsrdf:taIdentRef <http://pantheonparty.com/beowulf>

Reconstructing Sentences With Metadata

The final step is to produce a result by recombining the different constituency nodes and their links to characters into legible HTML code. This process starts by finding the root node of a sentence and iteratively recombining the child nodes. To get the original sentence, it suffices to concatenate the values of all the leaf nodes into one sentence. The original location of whitespaces can be determined using the begin and end indices of the nodes. The nodes with a link to a character gets a separate <span> that contains RDFa to indicate that it references a ttrpg:Character and a link to which character. We can also add a title attribute that allows the user to hover over the word an get more information. As an example, the sentence from the previous step would become the following HTML:

<p>
    <span typeof="ttrpg:Character"
        resource="http://pantheonparty.com/beowulf"
        title="Beowulf (Pantheon Party)">
        Beowulf
    </span>
    sees
    <span typeof="ttrpg:Character"
        resource="http://pantheonparty.com/johan"
        title="Johan (Pantheon Party)">
        Johan
    </span>
    on top of the hill.
</p>

When rendered this becomes: (hovering over the names of Beowulf and Johan shows a hint box)

Beowulf sees Johan on top of the hill.

Note: In the HTML version, users can hover over the names of the character to get a hint box showing the name of the character and the campaign it originates from. For example, when hovering over Beowulf, the text “Beowulf (Pantheon Party)” shows up. In PDF, this is not available, but a screenshot is shown in Figure 13.

Overview

This section will explain the technical aspect of the application to implement the steps designed in the previous chapter. The first section will show how the data was converted into pieces of iol:Text. The second section will explain the base of the application, namely semantic.works. Section 3 to section 6 will explain four different services that implement a reasoner that perform a part of the analysis, namely sentence-service, constituency-tree-service, solid-sync-service and named-entity-recognition-service.

Data

To test the application, a set of RPG game logs was needed to use as input for the application and check the results. Using existing game logs allows testing how the system would function on real-world data. This set of logs comes from myself, from friends and even some from an RPG IRC channel.

All personally identifiable data of the players playing the character was removed before processing. For the campaigns, permission was asked to use it for data to test the applicaion, but not to republish the data. The examples used in this thesis come from campaigns where explicit permission was asked of all the players to use their character and storyline.

To process the data, different Jupyter[23] notebooks were used for each campaign to easily process the data in steps and perform checks during the process. As this contains links to private data, these scripts are not public, but the general idea of how they were processed will be explained.

In the end, 9 different campaigns were analyzed, with a total of 62 documents containing logs. This resulted in 4138 pieces of text that could be processed by the application.

While processing the data, different challenges came up to get the data from their raw source to the correct RDF format. The rest of this section will highlight three different challenges that came up. Each subsection will cover one of them, namely the format of the logs, the language they are written in and their phrasing.

Format

Almost every GM used a different format to keep logs which made it difficult to find a way to extract pieces of text from each of the different formats. The rest of this subsection will describe the formats and how they were processed.

Markdown

Markdown is a plain-text format that was made to create documents that can easily be turned into HTML documents and are still legible in their source format. In its most basic form, Markdown documents contain normal text where each paragraph will be shown as is. It allows adding markup such as italic or bold by surrounding the word with respectively one or two asterisks, so *this* becomes this. Titles can be inserted, up to 6 levels deep by adding one or more # before the title. The more are added, the lower the title is. For example the title of this subsection is ### Format, as it is 3 levels deep (chapter title, section title and subsection title). Markdown also allows links to be specified by using [text](url), where a link will be shown with “text” as display text and a link to “url”.

To get text from raw Markdown, it suffices to take the text as is and remove all special markup characters such as *. Links can be removed using a regular expression. This cannot be done by removing all brackets, as they may be used in a sentence. Once these are removed, each paragraph, separated by two newlines, can be processed as a piece of text.

The Markdown documents used to analyze came from many different sources, which introduced slight differences in how they were processed. Some came as raw Markdown files which just needed to be opened and read. Others were stored on Hackmd.io[24], which required an HTTP request to get their data, but were otherwise identical to raw files. One campaign used a GitHub wiki to keep track of their campaign, so the repository had to be cloned in a folder to get the raw Markdown files. Finally, one campaign used Obsidian[25], whose format is mostly identical to Markdown, but has some extended syntax that needs to be removed as well.

MediaWiki

MediaWiki[26] is a system that was originally developed for Wikipedia, but is now used in many different places. One of the GMs kept their logs on a self-hosted instance of MediaWiki which also stored information on characters and other related information. This allows the GM to create links to information pages about a specific subject, so they can more easily find extra information if needed.

The format of MediaWiki is, just like Markdown, at its basis a plain-text format. It allows adding links to pages on the same wiki by using [[Subject]], which would link to the page named Subject on this wiki. It also allow markup, italic and bold are done by surrounding the text with respectively two or three backticks. For example: ```text``` becomes text.

To make this into plain text, a similar approach to markdown was followed by removing special characters using regular expressions.

Google Documents

Some campaigns kept their logs in a Google document. To query this, an existing Python library was used that provided helpers for a users login and access to a Google document. This needed a Google application that had OAuth 2.0 set up and kept the tokens for this in a secret file.

The login flow asks the user to log in with a Google account. In this case this should be an account that has access to the document to be analyzed. With a logged in client, the document can be requested. The library returns the document as a Python object which can be queried like any other dictionary. To get all the necessary paragraphs, the application needs to iterate over everything in the content of the body and check if that piece of content contains a paragraph. If it is, it needs to check the parts in that paragraph and combine all text from it.

By using the “textRun” element, the text is retrieved without any markup which removes the need to strip anything from it to get the final texts.

Webblog

One campaign kept a blog online with their campaign logs. This made processing a bit more difficult, as the HTML tags were not always consistent. Using the BeautifulSoup[27] library, the HTML could be parsed and all paragraphs from the page could be extracted. This mostly worked, but it was still required to filter out titles and other interjections that were not part of the storyline.

Language

Some of the campaign logs were written in Dutch as that is the native language of some of the GMs. While it is theoretically possible to use models that support Dutch, this research focuses on English only, as the thesis itself would be written in English. Therefor, the texts needed to be translated into English before they could be stored.

To translate the pieces of text to English, a Python library was used that interfaced with Google Translate. While still imperfect, the translations were good enough to use for further processing. The library was however fairly inconsistent and would often just return the original, Dutch text instead of translating it. It would give no error message, so a manual check was added to see if the texts were translated or not. After some time it turned out that it was due to rate limiting on the Google Translate API. It would only allow a certain amount of requests per hour, so if the application ran into this issue, it waited some time before retrying. This made the translation step take quite some time.

Besides this, the translation library would often translate a sentence incorrectly. It resulted in a significant loss of quality. For example, names would be translated in strange ways, such as the name “Heksina”, that would often be translated into “Weksina”, making it impossible to recognize the original character without manual intervention.

To keep the original text, as well as the translated version, language annotations were used to indicate the language of the string. For English sentences, only the English sentence was saved using the en language tag, but for Dutch sentences, the original sentence was stored as well with the nl language tag.

Phrasing

Keeping logs during a session is an intensive task, especially when combined with playing a character or managing a session as GM. Because of this, GMs and players often choose to not keep logs in as full sentences, but only write some keywords or drop words from the sentence. This makes it easier to write and people can understand it well enough in context, but analyzing this becomes a real challenge. Especially constituency tree parsing becomes difficult when the sentence is not a valid sentence. This can easily result in incorrect parsing and thus produce incorrect results.

Semantic.works

The base of the application is the Semantic.works framework[28], which is a framework that revolves around a system of microservices that interact with a central triple store. Each of the microservices implements a reasoner that processes the data in the knowledge graph. This way, services can be reused easier, as they only communicate through the central database. Semantic.works was formerly named “mu.semte.ch”, so many of the services it uses are still using the mu- prefix in their name.

Semantic.works middleware

The core of Semantic.works are three services: the identifier, the dispatcher and the database. These allow services to communicate and provide a way to process requests from the frontend. An overview can be seen in Figure 14.

Identifier

The entry point to the backend is the identifier, which takes in the request from the frontend and finds out to which session it belongs by sending and reading a cookie which contains a unique URI for each session. In most cases, this session corresponds to a browser-tab from which the user made the request. It attaches the session id to the request using an HTTP header before sending it to the dispatcher.

Dispatcher

The dispatcher takes a request from the identifier and determines which microservice it should be forwarded to for processing. This way, different microservices can define an API endpoint with the same name inside their container, without causing problems. It does so by matching the request URL to a preset list of paths and their respective microservice.

Database

The database consists of an OpenLink Virtuoso triplestore, which allows services to read and write data using a SPARQL endpoint. It also supports the usage of different graphs for storing triples. The database is available to every service and serves as the primary way of communication.

Provided services

Some services are used in many different applications, as they often have similar requirements. Because the Semantic.works stack revolves around reusing services, many common services are available. This application uses three of these, namely mu-authorization, delta-notifier and mu-cl-resources.

Mu-authorization

The mu-authorization service sits between the services and the database and adds authorization to the requests. It checks if the user belonging to the session provided by the identifier has the right to read or write the data requested in the SPARQL query. To allow different users to be able to read and write data, the service makes use of different graphs. When a write occurs, it writes this data to all graphs that correspond to a group that has read access to this data, so that if a read occurs, it can simply read from the right graph to return the data that group is allowed to read. A configuration file defines which users can read and/or write to which graphs.

As this service also provides a SPARQL endpoint at the same endpoint as the database, services can simply be configured to send their requests to the mu-authorization service instead of to the database directly and, given that they have the correct permissions, can simply send requests as if they were talking to the database directly.

Mu-authorization also provides a way to have services get notified when a write-request is made, by sending the changes or deltas to a service that wants to receive those changes.

Delta-notifier

The delta-notifier is a service that takes the deltas from the mu-authorization service and forwards them to the interested services. The delta-notifier also allows each service to specify which deltas they are interested in, so they don’t have to receive all the deltas all the time. This allows the services to know when something has changed without having to query the database continuously.

The deltas are sent in JSON format as a list of objects. Each of these objects represents a change in the data and has two fields, inserts and deletes, which both consist of a list of objects representing triples that are inserted or deleted respectively. These triples have three fields subject, predicate and object with as value another object that follows the specification for how to encode RDF terms from SPARQL[29]. An example is found in Listing 13

[
  {
    "inserts": [
      {
        "subject": {
          "type": "uri",
          "value": "http://pantheonparty.com/sahara"
        },
        "predicate": {
          "type": "uri",
          "value": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
        },
        "object": {
          "type": "uri",
          "value": "http://w3id.org/TTRpg#PlayableCharacter"
        }
      }
    ],
    "deletes": [
      {
        "subject": {
          "type": "uri",
          "value": "http://pantheonparty.com/sahara"
        },
        "predicate": {
          "type": "uri",
          "value": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
        },
        "object": {
          "type": "uri",
          "value": "https://dbpedia.org/ontology/desert"
        }
      }
    ]
  }
]

Mu-cl-resources

To make it easier for existing frontend tools to interact with the Semantic.works framework, mu-cl-resources was created. It provides a way to specify a mapping between the data in the triple store and a JSON:API[30] endpoint. The developer can specify what the different resources in the API look like and how these correspond to triples in the database. Mu-cl-resources will then provide an API that allows all operations to read/write these as objects and automatically map this to changes in the triple store.

Mappings can be defined using a Lisp and/or JSON configuration. While they provide the same functionality, this section will be focusing on the JSON version. This version requires the following fields for each type:

• name: The name of the resource.
• class: A URI describing the type of this resource.
• attributes: The attributes this object has, each consisting of
  • type: The datatype of the attribute, such as string or number.
  • predicate: The URI of the predicate that corresponds to this field.
• relationships: Which links this type has to other objects.
  • target: The name of the type the relationship links to.
  • predicate: The URI of the predicate that corresponds to this relationship.
  • cardinality: The cardinality of the relationship, either one, when there is only one such relationship for each object or many, when there are multiple.
  • inverse: Indicates if this relation corresponds to the inverse of predicate.

For example, a mapping for authors and books can be seen in Listing 14 which will map the data in Listing 15 to Listing 16

{
  "version": "0.1",
  "prefixes": {
    "schema": "http://schema.org/"
  },
  "resources": {
    "book": {
      "name": "book",
      "class": "schema:Book",
      "attributes": {
        "title": { "type": "string", "predicate": "schema:headline" }
      },
      "relationships": {
        "author": {
          "target": "author",
          "predicate": "schema:author",
          "cardinality": "one",
        }
      }
    },
    "author": {
      "name": "author",
      "class": "schema:Person",
      "attributes": {
        "name": { "type": "string", "predicate": "schema:name" }
      }
    }
  }
}

<http://example.com/mybook> rdf:type schema:Book;
                            schema:headline "My Diary";
                            schema:author <http://example.com/robbevanherck>.

<http://example.com/robbevanherck> rdf:type schema:Person;
                                   schema:name "Robbe Van Herck".

{
  "data": {
    "attributes": {
      "title": "My Diary",
    },
    "id": "4263c1e6-beb5-417d-8428-24cb2a2d96f0",
    "type": "book",
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/robbevanherck",
        }
      },
    }
  },
  "links": {
    "self": "http://example.com/mybook"
  }
}

Sentence service

The first service that was implemented for the application was the sentence-service, which has the simple task of waiting for new pieces of text to be added to the database and split them up into separate sentences. The task itself is pretty straight-forward, but it serves as a reminder that reasoners don’t need to be complex to be useful. Also, since it was implemented first, it laid the foundation for how other services would interact with the database, receive deltas, etc.

The service makes use of Semantic.works’ Python template [31], which provides some helpers like a function to easily perform SPARQL queries to the database and a pre-configured Flask app. This way, only a file which contains the implementation of the service needs to be provided and the template will provide the helpers, start up the application, etc.

function handle_delta(delta) {
    text_uris = []
    values = {}
    for each inserted triple in delta {
        if (triple.predicate == "rdf:type" &&
            triple.object == "iol:Text") {
            text_uris.add(triple.subject)
        }
        if (triple.predicate == "rdf:value") {
            values[triple.subject] = triple.object
        }
    }
    
    for each uri in text_uris with a value in values {
        for each sentence in nltk.sent_tokenize(value) {
            store sentence
        }
    }
}

The service consists of one endpoint, namely /.mu/delta, which is the endpoint that most Semantic.works services use for receiving deltas from the delta-notifier. When this endpoint gets a POST request, the service parses the deltas and creates a list of sentences it should analyze. It keeps a list of all the URIs that it knows are of type iol:Text and also keeps a dictionary that maps URIs to their rdf:value, if they have any. We have to keep both separately to later match the URIs that have a rdf:value and are known to have type iol:Text, as these are the texts we will be processing.

We find these by looping over all the inserted triples and checking the predicate. If the predicate is rdf:type, it checks if the object (and thus the type of the subject) is iol:Text and if so, it adds it to a list of iol:Texts. If the predicate is rdf:value, it creates an entry in the dictionary with the URI of the subject as key and the string in the object as value.

The actual separation of sentences is done with the Python library NLTK [32]. More specifically, the sent_tokenize function is used, which splits up the text into sentences. Each of these sentences will then be saved to the database in the correct format. To make it accessible by mu-cl-resources, a mu:uuid needs to be added, which provides a unique identifier.

Constituency Tree Service

The second service in the application is the constituency-tree-service, which takes sentences in the database and performs constituency tree parsing on them.

Like the sentence-service, constituency-tree-service is also based on the mu-python-template and contains one endpoint /.mu/delta to receive delta notifications.

The sentences are analyzed using CoreNLP[33], which is a Java program that can do many NLP tasks, including parts of speech tagging and constituency tree parsing. Because the constituency-tree-service is written in Python and CoreNLP is written in Java, there is no way to directly interface with it. However, NLTK provides a helper class which allows using the CoreNLP tools from within Python using its API.

To make sure the CoreNLP server works on every system, a Docker container running an instance of CoreNLP is added to the system that does not interact with the database or any of the middleware services directly, but services can choose to talk to the server if they need CoreNLP analysis.

function handle_delta(delta) {
    database_graph = connect_to_database()
    sentence_uris = []
    values = {}
    for each inserted triple in delta {
        if (triple.predicate == "rdf:type" &&
            triple.object == "dul:Sentence") {
            sentence_uris.add(triple.subject)
        }
        if (triple.predicate == "rdf:value") {
            values[triple.subject] = triple.object
        }
    }
    
    for each uri in sentence_uris with a value in values {
        tree = corenlp.parse(value)
        store_recursive(database_graph, tree)
    }
}

function store_recursive(database_graph, tree, start_index=0) {
    database_graph.add_triple(tree, "rdf:type", "nif:String")
    if !database_graph.has_uuid(tree) {
        database_graph.add_triple(tree, "mu:uuid", generate_uuid())
    }

    current_character = start_index
    if tree.has_children {
        for child in tree.children {
            while (current_character.is_whitespace()) {
                current_character += 1
            }
            characters_processed = store_recursive(database_graph, tree, current_character)
            current_character += characters_processed
        }
        value = substring of sentence from start_index to current_character
    } else {
        value = tree.value
    }
    
    pos_tag_uri = lookup_pos_tag_uri(tree.pos_tag)
    
    store current node with start, end, pos_tag_uri and value
}

Once the application starts up, it makes a connection to the CoreNLP server and waits for delta notifications. Similar to sentence-service, it finds all URIs that have a rdf:type of dul:Sentence and have a rdf:value. All of these get fed through the parser using NLTKs CoreNLPParser.parse function. This returns the parsing as a dict.

The communication with the database goes through rdflib, which provides a way to use the same functions as for in-memory graphs, but with the data being stored automatically to a SPARQL triplestore. The connection to the store is opened right after analyzing the sentence and passed on to each function call so the calculated data can be saved immediately.

The way the constituency tree is processed uses a recursive approach that starts by processing the root node and process the rest of the tree down from there.

The first thing that needs to be done is adding the type of nif:String to the node, if the node already exists it suffices to add a triple with predicate rdf:type and object nif:String, otherwise a uuid needs to be generated and stored so mu-cl-resources recognizes it. The rdf:type triple gets stored first as this way, mu-authorization knows its type and knows that the permissions for it allow the application to write these triples. Otherwise, all triples before the type would be rejected a it doesn’t know that it is a nif:String, which can be writen to without special authorization.

After that, a check is performed to see if the node has children, if this is the case, the child is processed in the same way. Keeping a running count of how many characters are processed allows determining what the start and end indices are for each child node. It also makes it possible to find out which part of the sentence this node covers. Before processing a child node, white space is skipped, otherwise spaces would be considered part of a word. Using a recursive call, each child node gets processed which returns the number of characters processed and the URI where the child was stored. With this, nif:beginIndex is known to be of characters processed so far and the nif:endIndex is the nif:beginIndex plus the number of characters covered by the child node, minus 1 to be an inclusive index. The nif:superString for each child node is the current node and the child node is a nif:subString of the current node.

Finally, the POS tag is stored using an OLiA tag, using a mapping from CoreNLP labels to OLiA URIs. CoreNLP uses Penn Treebank labels, which OLiA supports. For this, a Python dict with these mappings was set up which contains the 58 entries that occur in the dataset, which should cover the majority of English sentences.

Penn Treebank labels can also contain function tags, for example, a verb might be vocative, which would result in the tag VB-VOC, where VB indicates it is a verb and -VOC that it is vocative. In this application, this function tag is not stored as it not necessary further down the line, so it is stripped from each tag by splitting on the character “-“ and taking the first group. If future applications do want to use this tag, it could be added by checking the other groups after splitting and changing which tag to give depending on all values instead of just the first.

Solid Sync Service

To make processing data from the users Solid pod more easy, solid-sync-service was created. This service allows data to be mirrored from a Solid pod in the database, so it can be queried like data that is already in the database. Right now, it supports mirroring one pod, but it is possible to expand this to include multiple pods and things like per-pod authorization.

The service currently only works with Community Solid Server (CSS) as this version allows the use of client credentials. These allow a user of a Solid pod to create a set of tokens that can authenticate the user without having to store their username and password in the app. This is especially useful for backend applications that don’t have the option to show the user the login prompt in a browser for authentication. These tokens are implemented as a temporary measure to allow clients to connect without needing to know the users plain-text password and might be changed in the future.

The user can request a new token by sending a POST request to the credentials path. This path can be found by interacting with the identity provider (IDP) and looking at the URIs in the response. The user should provide their login details once, as well as the name of the token. As the user can do this manually, the service that uses the token doesn’t need the login credentials of the users account. The user then passes the returned token id and token secret to the application so it can use it. They can also decide to delete the token to revoke access to the application by performing a DELETE request.

Once the token id and secret are known to the application, it can request an access token, which allows the application to perform authenticated requests for a period of time. The service can do this by sending a POST request to the token endpoint with the token id and secret in an Authorization: Basic header and a DPoP[34] key. The token endpoint can be found in /.well-known/openid-configuration.

With this the access token, requests can be made using the same DPoP key as above and the token. The Solid library solid-client-authn-core provides helpers for both DPoP generation and creating functions for authenticated requests.

As the Solid authentication library is written in JavaScript, this service is as well. The Docker image is based on mu-javascript-template, which is similar to mu-python-template, but for JavaScript services instead of Python.

The service has one endpoint /update, which can be POSTed to. If a POST request arrives, the service will recursively query its preconfigured pod and store the data in the database.

The source code of the service is split up across three files

• app.js: Contains the entrypoint code, sets up and checks the environment.
• solid.js: Contains all code for interacting with the Solid pod, exports the function getPod.
• sparql.js: Contains all code for writing data to a SPARQL store, exports the function writeToStore

app.js

function on_start() {
    dotenv.setup()
    if not all required environment vars are set {
        error()
    }
}

function update() {
    pod_data = solid.getPod()
    sparql.writeToStore(pod_data)
}

The first file, app.js initializes the environment using dotenv[35], which allows the creation of a file named .env in the root of the project that contains a set of environment variables for configuring the application. This way, it is also possible to specify the configuration using environment variables for deployment, when there might not be an option to create a .env file.

After configuring the environment variables, a check that all required environment variables are present is performed in the function checkEnv. If any of these variables are not present, it throws an error during startup. The required variables are:

• POD_BASE: The base URI of the Solid pod, also used to find IDP endpoints.
• POD_NAME: The name of the pod to synchronize.
• TOKEN_ID: The id of the client token.
• TOKEN_SECRET: The secret of the client token.

Every time a request on /update comes in, the function update gets called, which constructs the URI of the Solid pod by concatenating the POD_BASE and POD_NAME. It also checks if the POD_BASE ends with a slash and adds a slash if necessary. With this, it gets the data in the pod using getPod and writes it to the database using writeToStore.

solid.js

function getPod() {
    result_graph = rdflib.graph()
    visited_uris = []
    uris_to_visit = []
    
    while uris_to_visit is not empty {
        current_uri = uris_to_visit.remove_one()
        visited_uris.add(current_uri)
        container_data = getContainer(current_uri)
        add container_data to result_graph
        for uri in container_data.find(current_uri, "ldp:contains") {
            if uri not in visited_uris and uri not in uris_to_visit {
                uris_to_visit.add(uri)
            }
        }
    }
    
    return result_graph
}

In solid.js, there is one entry function, namely getPod, which performs a depth-first search through the pod and keeps all the results in an rdflib.graph. It does this by keeping a list of visited URIs and a list of URIs to visit. The former starts empty, the latter contains just the URI of the pod. It then repeatedly takes the first URI of the URIs to visit, adds it to the list of visited URIs and requests its content using getContainer. It then checks the content of the container if it contains more resources by finding all URIs that match (?currentResourceURI, ldp:contains, ?otherResourceURI). It then adds them to the list of URIs to visit if it is not in the list of visited URIs and if it’s not already in the list of URIs to visit. It repeats this until the list of URIs to visit is empty.

The function getContainer takes a URI and requests the data on that URI using an authenticated fetch created by the getAuthenticatedFetch function. If the response is not 200 OK, it throws an error indicating which status code it got and on which URI. This can happen if a user is not authorized to read a resource, in which case the status code would be 401 Unauthorized.

The function getAuthenticatedFetch will perform the steps described in the Design section, by using the helper functions provided by solid-client-authn-core.

sparql.js

function writeToStore(quads) {
    query = "INSERT DATA {"
    for quad in quads {
        query += "GRAPH {} { {} {} {} . }".format(
            sparqlify(quad.graph),
            sparqlify(quad.subject),
            sparqlify(quad.predicate),
            sparqlify(quad.object)
        )
    }
    query += "}"
    query.execute()
}

function sparqlify(node) {
    if node is a named node {
        return helpers.sparqlEscapeUri(node.uri)
    } else {
        if node.type is "string" {
            return helpers.sparqlEscapeString(node.value)
        } else if node.type is "number" {
            return helpers.sparqlEscapeString(node.value)
        }
        ...
    }
}

The sparql.js file contains two functions. The first is sparqlify, which takes one rdflib node and transforms it into a string that can be used in a SPARQL query. For this it first checks if it is a named node, in which case it can simply return it as a URI using sparqlEscapeUri. If it is a Literal, it has to check which type of literal and use the corresponding sparqlEscape function. The second is writeToStore, which takes a list of quads and creates and executes a SPARQL query to insert them.

Using this function, a SPARQL query can be created that iterates over each quad in the graph and create a query from those. This is done by creating a different GRAPH block for each quad following the format GRAPH ?g { ?s ?p ?o. } where ?g is the URI of the graph, ?s the subject, ?p the predicate and ?o the object. This is done for each quad and they are joined using newlines and wrap them with INSERT DATA { and }, resulting in a valid SPARQL query.

While this is not a very efficient approach, the JavaScript implementation of rdflib does not provide an alternative approach so this method was chosen.

Named Entity Recognition Service

The service that performs the actual named entity recognition is the named-entity-recognition-service. This service performs a very basic named entity recognition. If it finds a match, it adds a link from the constituency node to the character to know who it refers to.

This service serves as an example on how complex analyses can be performed in a simple way, once all the required steps are set up. This shown by the fact that the entire service mainly consists of one SPARQL query.

The implementation of this service is very basic. It uses mu-python-template and added an endpoint /annotate that performs the SPARQL query in Listing 22.

PREFIX  ttrpg: <https://w3id.org/TTRpg#>
PREFIX  olia: <http://purl.org/olia/olia.owl#>
PREFIX  itsrdf: <http://www.w3.org/2005/11/its/rdf#>
PREFIX  nif:  <http://persistence.uni-leipzig.org/nlp2rdf/ontologies/nif-core#>
PREFIX  foaf: <http://xmlns.com/foaf/0.1/>

INSERT {
    GRAPH ?g {
        ?node itsrdf:taIdentRef ?character .
    }
}
WHERE {
    GRAPH ?g {
        ?node       nif:posTag   olia:ProperNoun ;
                    nif:isString ?characterName .
        ?character  a            ttrpg:Character ;
                    foaf:name    ?characterName
    }
}

This query first tries to find all the nodes that have the nif:posTag of olia:ProperNoun. Then, it finds out which string they represent using nif:isString. After that, it finds all ttrpg:Characters that have the string as foaf:name. Once these nodes and characters are found, a link between them is added using itsrdf:taIdentRef.

Overview

This section will first explain how the application was set up and configured. After that it will show how each step performed by performing some analyses and timings. All timings were run on a laptop with 8GB RAM, 10GB swap and an Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz

The source and configuration files of all the services and the system as a whole can be found in GitHub repositories under the MIT license. This way, anyone can contribute to the system or run their own instance.

The main repository for the application is on https://github.com/Robbe7730/app-gelinkt-rollenspelen, this contains the docker-compose setup for the entire stack, as well as configuration files for these services. Each service also has its own repository:

• Sentence Service: https://github.com/Robbe7730/sentence-service
• Constituency Tree Service: https://github.com/Robbe7730/constituency-tree-service
• Named Entity Recognition Service: https://github.com/Robbe7730/named-entity-recognition-service
• Solid Sync Service: https://github.com/Robbe7730/solid-sync-service

Configuration

This section will explain the configuration of the services that make up the application. As the entire application is open-source, this section will only give a higher-level overview of each of the configuration parameters.

An overview of all the used services and their interactions can be seen in Figure 15.

The middleware services identifier and dispatcher are in the same place as they are in every Semantic.works stack. To get mu-authorization working, the links to the triplestore have been replaced with links to mu-authorization, which in turn talks to the triplestore. As described earlier, this does not affect the services in any way because mu-authorization uses the same endpoint for SPARQL queries as the triple store. The mu-authorization service also talks to the delta-notifier, who passes its deltas to the sentence-service and the constituency-tree-service. The constituency-tree-service also talks to a separate corenlp container and the solid-sync-service needs access to the Solid pod that it should sync.

The rest of this section will give an overview of how some of the services were configured, more specifically, it will explain the models for mu-cl-resources and the routes for the dispatcher.

Resources

This configuration defines which models exist and how they are stored in as RDF. There are a total of 5 models defined, namely text, sentence, constituency-node, character and campaign.

Text

This model defines a piece of iol:Text, it has one attribute value, which is a language-string-set that uses the rdf:value predicate. This means that there are multiple string values for this attribute, each with a language tag. The text also has a relation to sentence, namely which components it has. This is done with the iol:hasComponent relation.

Sentence

Similar to text, this model defines a iol:Sentence with a single string value named value using the rdf:value predicate. The inverse of the sentence relation in text is represented here under the name text.

Constituency-Node

The most complex model is the constituency-node model. It represents each node in the constituency trees using type nif:String. It has the following attributes:

• begin-index using nif:beginIndex: The start of the string in its super-string.
• end-index using nif:endIndex: The end of the string in its super-string.
• pos-tag using nif:posTag: The part of speech tag for this node.
• is-string using nif:isString: The value this node represents.

It also has three relations, namely:

• sub-string using nif:subString: Relation to zero or more constituency-node that are children of this node.
• super-string using nif:superString: Relation to zero or one constituency-node that are the parent of this node.
• references-character using itsrdf:taIdentRef: Relation to zero or one character that this node references, according to the named entity recognition.

Character

The character model represents a single ttrpg:Character. Currently, it only models the characters name as that is the only value in use. The name of the character is modeled using foaf:name and is a string value. As these resource come from an external source, we also tell mu-cl-resources to include the uri in the response using the include-uri feature. This way, we can link to the character in the Solid pod, even if the data itself comes from the local database.

Campaign

Similar to character, ttrpg:Campaigns are also modeled. Their model is pretty much identical to character, as we only use the name of the campaign.

Dispatcher

The dispatcher has a configuration that specifies which service a request should be forwarded to.

First, the routes that should be forwarded to mu-cl-resources are specified, otherwise a frontend would not be able to request this data. These endpoints are:

• /sentences
• /texts
• /constituency-nodes
• /characters
• /campaigns

After this, every service that has an endpoint that should be public is specified. Each of these routes are forwarded to the corresponding service. These endpoints are:

• /visualize
• /sentence-service
• /constituency-tree-service
• /named-entity-recognition-service
• /solid-sync-service

All other requests will return a 404 Not Found with message “Route not found. See config/dispatcher.ex”.

Results

This section will give an indication how well each step in the process performed. It will give examples of what went well and what went wrong and why.

Extracting text from files

Due to the complexity of this step, this was a very manual task that required a lot of fine-tuning and experimenting. Every format came with its own difficulties. While the plain-text formats such as Markdown were easier to read, stripping the special characters from them was more difficult. On the other hand, the Google Documents were harder to get access to, but once this was done the data was pretty much already in plain-text format without special characters.

The fact that the Python library used was unstable and would often crash without any indication why did not help either. The translations were also not always correct. For example, the sentence “Hij komt wel tot het inzicht dat het geluid een val is” is translated as “He does come to the insight that the sound is a fall”, but it would be more correctly translated as “He realizes that the sound is a trap”. The library would also often add or remove whitespace, which would lead to multiple sentences being combined into one because the space after the period was removed.

The mistake that had the most impact on the results of the application was the fact that it sometimes mistranslated names. For example, it would translate the name “Heksina” as “Weksina” most of the time, which makes recognizing this name nearly impossible.

When manually inspecting 100 texts, all of them had their special characters stripped correctly, 76 of them were translated correctly and 24 were translated incorrectly.

Extracting sentences from text

This step consisted of two SPARQL queries and some Python processing. First, all the iol:Texts were extracted from the database, then their values were analyzed using NLTKs sent_tokenize function and the resulting sentences were stored back in the database.

The main difficulty was ill-formed sentences. For example, when the sentences did not have a space after their final period, it would see them as one long sentence.

Extracting the 8212 sentences from the 4138 pieces of text took about 1 minute. This is an average speed of around 69 texts per second. Manually inspecting 100 texts showed that all of them were split into sentences correctly.

Constituency parsing

Constituency parsing was done with CoreNLP, which is a well-known and often used library for this job. Because of this, most of the sentences were parsed correctly. For example, the sentence “You shake them out” gets parsed to the constituency tree in Figure 16. This constituency tree can be manually verified to be correct, but for larger constituency trees, this process becomes harder as more complex structures can occur.

Where CoreNLP has more trouble is in sentences where punctuation is missing or sentences are ill-formed. For example, the sentence “It’s ice cold.” is mostly correct, but the correct spelling is “ice-cold”, which makes CoreNLP parse that group as a noun phrase instead of an adjective phrase and thus change the interpretation of the sentence. Both constituency trees can be seen in Figure 17.

During testing, the expected time to process all the sentence would be over 5 hours, so a change was made to constituency-tree-service to use 12 threads instead of just 1, which reduced the processing time to 1 hour and 11 minutes and resulted in 228055 nodes. The service failed to process 399 sentences due to various reasons, mainly if they were not sentences at all, such as YouTube links or emoji. This is an average speed of 1.83 sentences and 53.5 nodes per second.

Recognizing entities

For any correctly tagged constituency tree, the named entity recognition service can correctly extract all names of characters that occur. Even when the constituency tree is not entirely correct but the names are recognized as proper nouns or noun phrases it will still correctly tag the character. In the tests, it was able to extract every occurence of a character from the 3 campaigns that had their data in RDF available and tag it correctly, resulting in 1451 tagged nodes. Mirroring the data from a Solid pod took 52 seconds and running the NER took 8 seconds.

Conclusion

This section will draw some conclusions from the results of the steps described above and compare them to what was expected. Finally, it will also evaluate the application as a whole.

Evaluating in Steps

The first step where the text was extracted from existing files and if needed, translated was the step that performed the worst, mainly due to translation errors. As stated in Subsection 7.2.1, about 24% of the sentences that were originally in Dutch were incorrectly translated to the point where the meaning was changed. This makes the rest of the analysis less accurate, so we will evaluate the next steps in a way that makes this inconsistency less relevant. It should also be noted that this step will be irrelevant in the ideal vision of the project, as the texts would be inserted in the system directly.

The sentence extraction-step was also able to process all 4138 texts in less then 1 minute and a manual inspection found no sentences that were split incorrectly.

The constituency parsing was not able to process each sentence, mainly due to unexpected characters in the sentences. Out of the 8212 sentences, only 399 were not able to be processed. Inspecting the failed sentences revealed that the most common culprit was the use of incorrect symbols, such as unicode or invalid punctuation.

Named entity recognition performed its analysis in less then 10 seconds and was able to find 1451 nodes. It did not miss a single occurrence of a characters name in all the texts, which means that both the constituency parsing and the NER work reliably.

All the steps combined result in a system that works very reliably and produces data in a way that future additions can reuse and build on.

Evaluating as a whole

The total runtime of the application was 1 hour and 13 minutes for over 4000 texts, which brings the average to around 1 second per piece of text. In a real application, this is a perfectly reasonable time to wait, especially since the data would be analyzed in the background, causing no delay to the user while typing.

The original goal of the project was to go a step further and use the constituency trees in combination with VerbNet[36] to extract events from them. While researching and implementing however, it became clear that even though the idea had potential, it would be harden than expected to implement in time due to the complexity of the idea. The decision was made to focus on only the NER to prove that the system was viable. The idea is described more in Subsection 8.2.1.

Originally, the proof of concept would include a frontend where the user could enter text in an online editor that would send the texts to the backend for analysis and provide a visual indication of the added semantics. This idea was not realized as using an editor that supports RDFa as well as storing the documents in RDF turned out to be more complex than expected.

Even though some steps were not realized, the system definitely shows potential. Every reasoner adds data that is reliable, which leads to a decent result and shows that providing data in a reusable, open and standardized way can provide major benefits to RPG players.

Future work

This thesis was also meant to provide the basis of a system that can be expanded on, so the rest of this chapter will describe some examples of services that could be implemented or applications that can make use of the data provided by them.

Event Extraction With VerbNet

VerbNet[37] is a lexicon containing descriptions of many English verbs and their relation. It groups verbs into syntactic frames, which are a collection of verbs that share both semantic and syntactic features. Every verb class has so-called surface realizations, that indicate how this verb is used. For each constituency node, it indicates what semantic meaning it has to the verb. For example, the verb “approach” belongs to the frame of “escape”, more specifically, to the subclass “escape-51.1-1-2” which also contains the verb “enter”. It has a surface realization of “NP V NP” where the first noun phrase is the theme and the second noun phrase the destination. For example in the sentence “Ronald and Vincent approach the castle”, the noun phrase “Ronald and Vincent” is the theme of the action, the thing in motion and “the castle” is the destination.

With these abstract representation of the verbs, we can extract events from the logs and automatically create a summary of sessions[38] or combine logs from different players into one shared log. The latter of which was originally intended to be part of this thesis, but was cut due to time constraints and unexpected difficulties.

This service could reuse the constituency trees produced by the constituency tree service and add tags to the nodes, just like the named entity recognition service did. Another service could then perform the combination or summarization.

Live Tagging

In the current state, the applications requires text to be inserted manually before it can be analyzed. In an ideal case, this would be done by having the user type their logs in a tailor-made editor that can talk to the backend automatically. This would allow the user to confirm or deny certain tags, which would reduce the number of incorrect tags significantly.

This editor would also allow the user to store their data as structured documents instead of separate texts. IOLite has classes and predicates that allow the representation of full documents in RDF, which could easily be plugged into the current system. Ideally, the document would be stored in the users Solid pod, to allow them to control who can and cannot access the logs.

Multiple Campaigns in One World

With this technology, it would be possible for two entirely separate campaigns to take place in the same world. The GMs could use data from both campaigns, which would lead to interesting story elements, where one party may help a village where the people are starving to get more food, but when the next party arrives, there has been a revolution and the whole village is now too industrial.

Using a system as proposed in this thesis would allow both campaigns to use their own set of tools, independently of one another but still be able to share the data.