MG Parser Server

MG (Minimalist Grammar) Parser Server is a Flask-based webserver that provides a RESTful API for parsing English sentences using the minimalist_parser library developed by dr. Meaghan Fowlie at Utrecht University. This server is part of the ParsePort project, as currently developed at the Utrecht University Centre for Digital Humanities. It can be run both as a standalone server or as part of the ParsePort Docker Compose network.

The minimalist_parser library is part of a larger repository mg_algebras_parser, maintained by dr. Fowlie. Look there for more information about this parser and other tools related to Minimalist Grammar.

Contents

The main entry point is a Dockerfile that creates a container (based on python:3.9.20-bookworm) with the necessary dependencies installed.

Prerequisites

To start this server, you need to have a host machine with Docker installed and internet access. You will also need a file with the weights for the parser model. It should be named model.tar.gz and placed in the root directory of the repository. The model file is not included in this repository, but can be obtained here: insert Yoda link here.

If you want to run this server on a standalone Docker container, you will need to generate a secret key and put it in a file called .env in the root directory of this project. This file should contain at least the following line. (Consult the .env.example file for an example.)

MG_PARSER_SECRET_KEY='your-secret-key-here'

If you wish, you may add:

# Starts the server in debug mode.
FLASK_DEBUG=1

# Specifies the port on which the application will run (default is 32770).
MG_PARSER_PORT=your-port-here

If you intend to run this server as part of the ParsePort network, adding an .env file is not needed, as these variables will be taken in the main ParsePort environment. Please consult the ParsePort documentation for more information.

Setup

To start the server in a standalone container, follow these steps.

1. Clone this repository to your local machine.
2. Navigate to the repository's root directory.
3. Add the model.tar.gz file.
4. Create an .env file as outlined above.
5. Build the Docker image as follows:

docker build . -t mg-parser-server

6. Run the Docker container by minimally running the following command.

docker run -p 5000:32770 --env-file .env --name mg-parser-server mg-parser-server

If you specified a different port in the .env file, replace 32770 with that port.

Tip: Add -d to run the container in detached mode and keep your terminal clean.

Tip: If you are running the Flask server in debug mode (with live reloading), adding -v .:/app:rw to the docker run command in Step 6 will mount the current directory to the container. Upon making changes to the code, the server will automatically reload.

The server should now be running and reachable on http://localhost:5000.

Usage

The server currently provides two endpoints:

• /status/: returns a JSON object of the shape {"ok": "true"} to indicate that the server is running, or {"ok": "false"} if the server is not running.
• /parse: accepts a POST request with a JSON object of the shape {"input": "The quick brown fox jumps over the lazy dog."}. The server will return a JSON object with the results of the parse, which can be used for further processing or passed to a visualisation tool such as Vulcan, developed by dr. Jonas Groschwitz.

Licence

MG Parser Server is shared under a BSD 3-Clause licence. See LICENSE for more information.

Citation

If you wish to cite this repository, please use the metadata provided in our CITATION.cff file.

Contact

For questions, small feature suggestions, and bug reports, feel free to create an issue. If you do not have a GitHub account, you can also contact the Centre for Digital Humanities.