<commit_before>[![Build Status](https://travis-ci.org/myedibleenso/processors-server.svg?branch=master)](https://travis-ci.org/myedibleenso/processors-server)

# processors-server

## What is it?

A [`spray`](spray.io) server exposing a REST API for text annotation via the [`processors`](https://github.com/clulab/processors) library

## Requirements
1. [Java 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)
2. [`sbt`](http://www.scala-sbt.org/download.html)

## How is this useful?
This might be useful to people wanting to do NLP in a non-`JVM` language without a good existing parser.  Currently there are services for using `processors`' `FastNLPProcessor` (a wrapper for `CoreNLP`) and `BioNLPProcessor`.

## Running `processors-server`

```bash
git clone https://github.com/myedibleenso/processors-server.git
```

Fire up the server.  This may take a minute or so to load the large model files.

```bash
cd processors-server
sbt "runMain NLPServer"
```

By default, the server will run on port `8888`, though you can start the server using a different port:

```bash
sbt "runMain NLPServer <your favorite port here>"
```

# Communicating with the server

## Annotating text

The following services are available:

1. Text annotation (open-domain or biomedical) involving:
  - sentence splitting
  - tokenization
  - lemmatization
  - PoS tagging
  - NER
  - dependency parsing
2. Sentiment analysis
3. Rule-based IE using `Odin`

#### `FastNLPProcessor`

Text can be annotated by sending a POST request containing `json` with a `"text"` field to one of the following endpoints (see [example](src/main/resources/json/examples/message.json)):

- `http://localhost:<your port here>/annotate`
- `http://localhost:<your port here>/fastnlp/annotate`

#### `BioNLPProcessor`

Text can be annotated by sending a POST request containing `json` with a `"text"` field to the following endpoint (see [example](src/main/resources/json/examples/message.json)):

- `http://localhost:<your port here>/bionlp/annotate`

### Sentiment analysis with `CoreNLP`

- `http://localhost:<your port here>/corenlp/sentiment`
  - Requires one of the following`json` POST requests:
    - [`Document`](src/main/resources/json/schema/document.json) (see [example](src/main/resources/json/examples/document.json))
    - [`Sentence`](src/main/resources/json/schema/sentence.json) (see [example](src/main/resources/json/examples/sentence.json))
    - [`Message`](src/main/resources/json/schema/message.json) (see [example](src/main/resources/json/examples/message.json))

### Rule-based IE with `Odin`

- `http://localhost:<your port here>/odin/extract`
  - Requires one of the following`json` POST requests:
    - [text with rules](src/main/resources/json/schema/text-with-rules.json) (see [example](src/main/resources/json/examples/text-with-rules.json))
    - [text with rules url](src/main/resources/json/schema/text-with-rules-url.json) (see [example](src/main/resources/json/examples/text-with-rules-url.json))
    - [document with rules](src/main/resources/json/schema/document-with-rules.json) (see [example](src/main/resources/json/examples/document-with-rules.json))
    - [document with rules url](src/main/resources/json/schema/document-with-rules-url.json) (see [example](src/main/resources/json/examples/document-with-rules-url.json))

For more info on `Odin`, see [the manual](http://arxiv.org/pdf/1509.07513v1.pdf)
# Responses

A `POST` to an `/annotate` endpoint will return a `Document` of the form specified in [`document.json`](src/main/resources/json/schema/document.json).

### An example using `cURL`

To see it in action, you can try to `POST` `json` using `cuRL`.  The text to parse should be given as the value of the `json`'s `text` field:   
```bash
curl -H "Content-Type: application/json" -X POST -d '{"text": "My name is <NAME>. You killed my father. Prepare to die."}' http://localhost:8888/annotate<commit_msg>Updates to README<commit_after>[![Build Status](https://travis-ci.org/myedibleenso/processors-server.svg?branch=master)](https://travis-ci.org/myedibleenso/processors-server)

# processors-server

## What is it?

A [`spray`](spray.io) server exposing a REST API for text annotation via the [`processors`](https://github.com/clulab/processors) library

## Requirements
1. [Java 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)
2. [`sbt`](http://www.scala-sbt.org/download.html)

## How is this useful?
This might be useful to people wanting to do NLP in a non-`JVM` language without a good existing parser.  Currently there are services for using `processors`' `FastNLPProcessor` (a wrapper for `CoreNLP`) and `BioNLPProcessor`.

## Running `processors-server`

```bash
git clone https://github.com/myedibleenso/processors-server.git
```

Fire up the server.  This may take a minute or so to load the large model files.

```bash
cd processors-server
sbt "runMain NLPServer"
```

By default, the server will run on port `8888`, though you can start the server using a different port:

```bash
sbt "runMain NLPServer <your favorite port here>"
```

# Communicating with the server

## Annotating text

The following services are available:

1. Text annotation (open-domain or biomedical) involving:
  - sentence splitting
  - tokenization
  - lemmatization
  - PoS tagging
  - NER
  - dependency parsing
2. Sentiment analysis
3. Rule-based IE using `Odin`

Text can be annotated by sending a POST request containing `json` with a `"text"` field to one of the following `annotate` endpoints (see [example](src/main/resources/json/examples/message.json)).

You may also send text already segmented into sentences by posting a [`SentencesMessage`](src/main/resources/json/schema/sentences-message.json) (see [example](src/main/resources/json/examples/sentences-message.json)) to the same `annotate` endpoint.  This is just a `json` frame with a `"sentences"` field pointing to an array of strings.

#### `FastNLPProcessor`

- `http://localhost:<your port here>/annotate`
- `http://localhost:<your port here>/fastnlp/annotate`

#### `BioNLPProcessor`

Text can be annotated by sending a POST request containing `json` with a `"text"` field to the following endpoint (see [example](src/main/resources/json/examples/message.json)):

- `http://localhost:<your port here>/bionlp/annotate`

### Sentiment analysis with `CoreNLP`

- `http://localhost:<your port here>/corenlp/sentiment/score`
  - Requires one of the following`json` POST requests:
    - [`Document`](src/main/resources/json/schema/document.json) (see [example](src/main/resources/json/examples/document.json))
    - [`Sentence`](src/main/resources/json/schema/sentence.json) (see [example](src/main/resources/json/examples/sentence.json))
    - [`Message`](src/main/resources/json/schema/message.json) (see [example](src/main/resources/json/examples/message.json))

You can also send text that has already been segmented into sentences:
  - post a [`SentencesMessage`](src/main/resources/json/schema/sentences-message.json) (see [example](src/main/resources/json/examples/sentences-message.json)) to `http://localhost:<your port here>/corenlp/sentiment/score/segmented`

Responses will be [`SentimentScores`](src/main/resources/json/schema/scores.json) (see [example](src/main/resources/json/examples/scores.json))

### Rule-based IE with `Odin`

- `http://localhost:<your port here>/odin/extract`
  - Requires one of the following`json` POST requests:
    - [text with rules](src/main/resources/json/schema/text-with-rules.json) (see [example](src/main/resources/json/examples/text-with-rules.json))
    - [text with rules url](src/main/resources/json/schema/text-with-rules-url.json) (see [example](src/main/resources/json/examples/text-with-rules-url.json))
    - [document with rules](src/main/resources/json/schema/document-with-rules.json) (see [example](src/main/resources/json/examples/document-with-rules.json))
    - [document with rules url](src/main/resources/json/schema/document-with-rules-url.json) (see [example](src/main/resources/json/examples/document-with-rules-url.json))

For more info on `Odin`, see [the manual](http://arxiv.org/pdf/1509.07513v1.pdf)
# Responses

A `POST` to an `/annotate` endpoint will return a `Document` of the form specified in [`document.json`](src/main/resources/json/schema/document.json).

### An example using `cURL`

To see it in action, you can try to `POST` `json` using `cuRL`.  The text to parse should be given as the value of the `json`'s `text` field:   
```bash
curl -H "Content-Type: application/json" -X POST -d '{"text": "My name is <NAME>. You killed my father. Prepare to die."}' http://localhost:8888/annotate
{'fraction_non_alphanumeric': 0.14244785697914278, 'fraction_numerical': 0.005730002292000917, 'mean_word_length': 4.677944046844503, 'pattern_counts': {'":': 2, '<': 18, '<?xml version=': 0, '>': 18, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1805608', 'n_tokens_mistral': 2852, 'n_tokens_neox': 2703, 'n_words': 757}