logx-reader

A machine reading system to support the LogX program.

Requirements

sbt
docker
8G of RAM

Testing

You can run all project tests with the following command:

sbt test

We use ScalaTest with FlatSpec and Matchers for BDD-style unit tests.

Entity tests: reader/src/test/scala/org/parsertongue/mr/logx/entities
Event/relation tests: reader/src/test/scala/org/parsertongue/mr/logx/events

Documentation

You can generate API documentation using the following command:

sbt doc

This will generate HTML pages documenting the API for each subproject:

reader: reader/target/scala-2.12/api/index.html
rest: rest/target/scala-2.12/api/index.html

Reader

The core of the LogX machine reading system is defined in the reader subproject. Currently, the reader is powered by a combination of Odin and statistical models for parsing and tagging.

REST API

Releases

We publish releases in the form of docker images:

logx.cloud container registry: gitlab-registry.logx.cloud/team/bbn/logx-reader
~~DockerHub: parsertongue/logx-reader-rest-api~~
- no longer maintained

Build

The project can be built using either docker or sbt; however, the recommended method is to use docker.

Docker

We construct our docker images using the sbt native-packager plugin:

sbt dockerize

For information on additional tasks (generating Dockerfiles, publishing images, etc.), see this section of the native-packager documentation.

`sbt` (Scala)

The REST API server can be launched directly using SBT:

sbt web

Run

After building the docker image, launch a container using the following command:

docker run --name="logx-reader" \
  -it \
  --restart "on-failure" \
  -e "HOME=/app" \
  -p "0.0.0.0:9000:9000" \
  "gitlab-registry.logx.cloud/team/bbn/logx-reader:latest"

Navigate to localhost:9000/api to interactively explore the API through the OpenAPI 3.0 specification.

Examples

See this gist for sample input and output corresponding to the /api/extract endpoint.

Develop

To avoid reloading NLP models during development, point the reader to the external version of the grammar outside of src/main/resources using the RULES_PREFIX environment variable and launch the REST API server in development mode:

# assumes you've cloned to ~/repos/clu-ling/logx-reader
# adjust as needed
RULES_PREFIX=file://$HOME/repos/clu-ling/logx-reader/reader/grammars/logx sbt web

Alter files under reader/grammars/logx

Visualizer

You can use the parsertongue/odin-tutorial:latest docker image for the Odin tutorial to visualize the output of the logx-reader using TAG. See the following docker-compose.yml fragment:

version: "2.3"
services:
  # use localhost:8880/playground for the visualizer
  frontend:
    image: parsertongue/odin-tutorial:local
    restart: always
    ports:
      - "8880:7777"
    environment:
      ODIN_API_BASE_URL: reader:9000/api

Support

For feature requests and bug reports, please open an issue.

Authors

Gus Hahn-Powell

clu-ling/logx-reader