Skip to content

Dev Instructions

Jump to bottom
Zachary Wellington edited this page Feb 17, 2021 · 12 revisions

Install

Clone the odin-tutorial and logx-reader repositories on your local system. Recommended: clone the repositories under the directory '~/repos/clu-ling'.

Install sdkman, JDK11, and sbt. In a terminal window, switch to the logx-reader repository and run sbt dockerize. You can now run the logx-reader REST API with sbt web, open your browser to localhost:9000.

To run the Odin Playground with the logx-reader API, change docker-compose.yml and run npm run start in a second terminal window under the odin-tutorial repository. Open your browser to localhost:7777/playground.

docker-compose.yml

version: "3.8"
services:
  frontend:
    image: parsertongue/odin-tutorial:local
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "8880:7777"
    env_file:
      - ./.env
    environment:
      ODIN_API_BASE_URL: http://0.0.0.0:9000/api

Develop

To develop the logx-reader live (i.e. run tests as you change rules), open the API and odin-playground. To do this, use two terminal windows. In the first window, under the logx-reader repo, run:

RULES_PREFIX=file://$HOME/repos/clu-ling/logx-reader/reader/grammars/logx sbt web

Note: This assumes the logx-reader repo is under the recommended directory above.

In the second terminal window, run npm run start as above. Using the odin-playground you can visualize the dependency parse and extracted mentions. An example can be seen here:

Note: Prime the API by executing an example data point under the /extract endpoint (e.g. "How many F16 engines are heading to Dubai"). This will take a little time, but only has to be done once.

The developing grammar can be found under /logx-reader/reader/grammars/logx, do not alter the mirror grammar under /logx-reader/reader/src.

In the master.yml scripts, both under entities and events, add a pathPrefix corresponding to your local repository and comment out all others (e.g. pathPrefix: "file:///home/zack/repos/clu-ling/logx-reader/reader/grammars/logx"). If modifying the taxonomy, also add a taxonomy path corresponding to your local repository.

Note: To commit changes through git, comment out your pathPrefix and taxonomy. Make sure the pathPrefix: "org/parsertongue/reader/grammars/logx" and the taxonomy taxonomy: org/parsertongue/reader/grammars/logx/taxonomy.yml are not commented out.

It is highly recommended to add test cases before writing or altering rules (test driven development). The reader test cases can be found under /reader/src/test/scala/org/parsertongue/mr/logx.

There is a scala script for testing both the entities and events rules. To run the tests, run sbt cleanTest in a third terminal window. When changing and adding tests, follow the guidelines in TESTING.md.

After executing the /extract endpoint in the API, to debug which rules found each mention, copy the url under Request URL into a new tab. A JSON file should be visible in the tab. Scroll down to mentions to find which rule found each extracted mention.

Clone this wiki locally