README.md 4.44 KB
Newer Older
Zied SELLAMI's avatar
Zied SELLAMI committed
1
# Priority-Inbox Module
Zied SELLAMI's avatar
Zied SELLAMI committed
2

Zied SELLAMI's avatar
Zied SELLAMI committed
3
The priority-inbox is a maven java projet. This module allows to assign to an email a category (**IMPORTANT, TO_READ or NOTIFICATION**) and a score. The priority-inbox is based on a set of generic rules.
Zied SELLAMI's avatar
Zied SELLAMI committed
4

Zied SELLAMI's avatar
Zied SELLAMI committed
5
The tools is a rest-api that compute the category and a score from a email json file. In average, the service is able to process 37 emails/second {min 1,18/second;max 1000/second}(result obtained by processing 7768 emails).
Zied SELLAMI's avatar
Zied SELLAMI committed
6

Zied SELLAMI's avatar
Zied SELLAMI committed
7 8
### Supported categories

Zied SELLAMI's avatar
Zied SELLAMI committed
9
 1. **IMPORTANT**: is returned if the email is important. **15 generic rules** are implemented to indicate if an email is important or not. For instance, we analyse the signature of the email. An email will be considered important if its sender (from) is the CEO of a company or a Director of a Department. An email is important if the body contains many thread (many replies) or many forwards. 
Zied SELLAMI's avatar
Zied SELLAMI committed
10 11 12
 3. **NOTIFICATION**: is returned if the email is a notification email. For instance a chat notification, a social media notification or each email with a not-reply email.
 4. **TO_READ**: if the email is not **IMPORTANT** and not a **NOTIFICATION**

Zied SELLAMI's avatar
Zied SELLAMI committed
13
### First results
Zied SELLAMI's avatar
Zied SELLAMI committed
14
A small dataset of **706** emails was annotated manually (**310** important emails, **321** notification emails and **75** to_read email) was created to test this approach. 
Zied SELLAMI's avatar
Zied SELLAMI committed
15 16 17
Remember that this AI approach are not based on Machine Learning but only on generic rules to compute a priority for an email.

**The next table resume the obtained results:**
Zied SELLAMI's avatar
Zied SELLAMI committed
18

Zied SELLAMI's avatar
Zied SELLAMI committed
19 20
| Email category | Precision | Recall | Fmeasure |
| -------- | -------- | -------- | -------- |
Zied SELLAMI's avatar
Zied SELLAMI committed
21 22
| Important   | 84.61%   | 78.06%   | 81.20%   |
| To_Read   | 34.43%   | 69.33%   | 46.01%   |
Zied SELLAMI's avatar
Zied SELLAMI committed
23
| Notification   | 99.62%   | 83.48%   | 90.84%   |
Zied SELLAMI's avatar
Zied SELLAMI committed
24 25
  

Zied SELLAMI's avatar
Zied SELLAMI committed
26 27 28 29
# Running the service with Docker

## Building the image
```
Zied SELLAMI's avatar
Zied SELLAMI committed
30
wget https://ci.linagora.com/zsellami/priority-inbox/raw/master/Dockerfile
Zied SELLAMI's avatar
Zied SELLAMI committed
31 32 33

docker build -t demo:priorityInbox .
```
Zied SELLAMI's avatar
Zied SELLAMI committed
34 35 36
## Building a storage volume for data model
**Use this command to create a storage space for data model**

Zied SELLAMI's avatar
Zied SELLAMI committed
37 38 39 40
```
docker volume create volume_name
```

Zied SELLAMI's avatar
Zied SELLAMI committed
41 42 43
**if you want to delete the volume use the next command**

```
Zied SELLAMI's avatar
Zied SELLAMI committed
44
docker volume rm volume_name
Zied SELLAMI's avatar
Zied SELLAMI committed
45 46
```

Zied SELLAMI's avatar
Zied SELLAMI committed
47
## Running the image
Zied SELLAMI's avatar
Zied SELLAMI committed
48 49 50 51 52
**Before running the image**. Use the next command to get the full path for the docker storage volume:
```
docker volume inspect volume_name
```

Zied SELLAMI's avatar
Zied SELLAMI committed
53 54
**The image expose the port 9991 with the IP 0.0.0.0 .**  To run the service on a host port do the next instruction:
```
Zied SELLAMI's avatar
Zied SELLAMI committed
55
docker run --volume volume_storage_path:/priority-inbox/priorityInbox/models/ -it -p 5551:9991 demo:priorityInbox
Zied SELLAMI's avatar
Zied SELLAMI committed
56 57 58
```
## Calling the service

Zied SELLAMI's avatar
Zied SELLAMI committed
59
### Get email type and score service
Zied SELLAMI's avatar
Zied SELLAMI committed
60
```
Zied SELLAMI's avatar
Zied SELLAMI committed
61
curl  -X POST 'http://0.0.0.0:5551/rest/priorityinbox/parsejson' -F "file=@/path/to/email.json"
Zied SELLAMI's avatar
Zied SELLAMI committed
62
```
Zied SELLAMI's avatar
Zied SELLAMI committed
63 64 65 66 67 68 69 70 71
Sample of json file:

**Note that** the fields **user**, **alternativeAddress**, **from** and at least one of **to**, **cc** or **bcc** are required.
 1. **user** is the name of the INBOX user. For instance Jhon Doe.
 2. **alternativeAddress** is the differents email address for the INBOX. For instance jhon.doe@test.com or jdoe@test.com or doe@test.com.
 
**Note that** the field **emailFolder** is the folder in which the email is located. By default, please fill the string "**INBOX**"


Zied SELLAMI's avatar
Zied SELLAMI committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
```
{
  "messageId" : "messageId",
  "from" : {
    "address" : "from@test.com",
    "personal" : "first_name last_name"
   },
  "to" : [ {
    "address" : "to1@test.com",
    "personal" : "first_name last_name of to1"
   } ],
  "cc" : [ {
    "address" : "cc1@test.com",
    "personal" : null
    }, {
    "address" : "cc2@test.com",
    "personal" : "first_name last_name of cc2"
    }, {
    "address" : "cc3@test.com",
    "personal" : "first_name last_name of cc3"
   } ],
  "bcc" : [ ],
  "Received" : "Mon, 28 Jan 2019 07:56:43 +0000",
  "Date" : "Mon, 28 Jan 2019 07:56:43 +0000",
  "in-Reply-To" : "messageId_in_reply_to",
  "subject" : "IMPORTANT: Testing The Priority Inbox",
Zied SELLAMI's avatar
Zied SELLAMI committed
98
  "body" : "\nDear, \n\n this a test of the priority inbox\n regards,\nfirst_name last_name\nDirector Tester",
Zied SELLAMI's avatar
Zied SELLAMI committed
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
  "attachments" : [{
    "file_size" : "243534",
    "content_name" : "presentation.pdf",
    "content_type" : "APPLICATION/PDF"
    }, {
    "file_size": "243534",
    "content_name" : "APPLICATION/PDF",
    "content_type" : "performance.pdf"
    }],
  "emailFolder" : "INBOX",
  "user" : "first_name last_name of to1",
  "alternativeAddress" : [ "t1@test.com", "first_name.last_name@test.com" ],
  "X-Spam-Flag" : "NO"
}
```
Expected result:
```
{  
"category" : "IMPORTANT",  
Zied SELLAMI's avatar
Zied SELLAMI committed
118
"score" : 14.916666666666668  
Zied SELLAMI's avatar
Zied SELLAMI committed
119 120
}
```