mailsort 0.0.2__tar.gz → 0.0.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mailsort-0.0.3/PKG-INFO +295 -0
- mailsort-0.0.3/README.md +271 -0
- mailsort-0.0.3/src/mailsort/__init__.py +16 -0
- mailsort-0.0.3/src/mailsort/__main__.py +672 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/_version.py +2 -2
- mailsort-0.0.3/src/mailsort/api.py +43 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/database.py +18 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/mail.py +203 -47
- mailsort-0.0.3/src/mailsort/evaluation.py +156 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/mail.py +0 -7
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/ml/__init__.py +10 -0
- mailsort-0.0.3/src/mailsort/ml/calibration.py +201 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/ml/database.py +12 -0
- mailsort-0.0.3/src/mailsort/ml/evaluation.py +545 -0
- mailsort-0.0.3/src/mailsort/ml/model.py +266 -0
- mailsort-0.0.3/src/mailsort/results.py +140 -0
- mailsort-0.0.3/src/mailsort/sorter.py +201 -0
- mailsort-0.0.3/src/mailsort/status.py +67 -0
- mailsort-0.0.3/src/mailsort/training.py +102 -0
- mailsort-0.0.2/PKG-INFO +0 -66
- mailsort-0.0.2/README.md +0 -42
- mailsort-0.0.2/src/mailsort/__init__.py +0 -6
- mailsort-0.0.2/src/mailsort/__main__.py +0 -91
- mailsort-0.0.2/src/mailsort/ml/model.py +0 -127
- {mailsort-0.0.2 → mailsort-0.0.3}/.gitignore +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/LICENSE +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/pyproject.toml +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/__init__.py +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/message.py +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/__init__.py +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/authentication.py +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/message.py +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/local.py +0 -0
- {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/ml/encoding.py +0 -0
mailsort-0.0.3/PKG-INFO
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: mailsort
|
|
3
|
+
Version: 0.0.3
|
|
4
|
+
Summary: Assign labels to emails on any IMAP mail server based on their similarity to other emails assigned to the same label.
|
|
5
|
+
Project-URL: Homepage, https://github.com/jan-janssen/mailsort
|
|
6
|
+
Author-email: Jan Janssen <jan.janssen@outlook.com>
|
|
7
|
+
License-Expression: BSD-3-Clause
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Science/Research
|
|
11
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Requires-Dist: numpy<=2.5.1,>=1.23.5
|
|
19
|
+
Requires-Dist: pandas<=3.0.5,>=1.5.3
|
|
20
|
+
Requires-Dist: scikit-learn<=1.9.0,>=1.2.2
|
|
21
|
+
Requires-Dist: sqlalchemy<=2.0.52,>=2.0.0
|
|
22
|
+
Requires-Dist: tqdm<=4.70.1,>=4.64.1
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# mailsort
|
|
26
|
+
[](https://github.com/jan-janssen/mailsort/actions/workflows/unittest.yml)
|
|
27
|
+
[](https://codecov.io/github/jan-janssen/mailsort)
|
|
28
|
+
[](https://mailsort.readthedocs.io/en/latest/?badge=latest)
|
|
29
|
+
[](https://github.com/psf/black)
|
|
30
|
+
|
|
31
|
+
Assign labels to emails on any IMAP mail server based on their similarity to other emails already
|
|
32
|
+
assigned to the same label.
|
|
33
|
+
|
|
34
|
+
`mailsort` connects to a mail account over plain IMAP, trains a machine learning model on the labels
|
|
35
|
+
(IMAP folders) you have already assigned, and uses that model to suggest or apply labels to new
|
|
36
|
+
messages. It has no dependency on Google APIs - for Gmail-specific features (OAuth, the Gmail label
|
|
37
|
+
API, the sorting daemon and web UI) see [gmailsorter](https://github.com/jan-janssen/gmailsorter),
|
|
38
|
+
which depends on `mailsort` for the shared IMAP and machine learning core.
|
|
39
|
+
|
|
40
|
+
To learn more about `mailsort` please have a look at the documentation below.
|
|
41
|
+
|
|
42
|
+
* [Preparation](https://mailsort.readthedocs.io/en/latest/preparation.html)
|
|
43
|
+
* [Sort your emails](https://mailsort.readthedocs.io/en/latest/preparation.html#sort-your-emails)
|
|
44
|
+
* [Configure your email account](https://mailsort.readthedocs.io/en/latest/preparation.html#configure-your-email-account)
|
|
45
|
+
* [Configuration](https://mailsort.readthedocs.io/en/latest/configuration.html)
|
|
46
|
+
* [Command line interface](https://mailsort.readthedocs.io/en/latest/configuration.html#command-line-interface)
|
|
47
|
+
* [Dry run / recommendation mode](https://mailsort.readthedocs.io/en/latest/configuration.html#dry-run-recommendation-mode)
|
|
48
|
+
* [Python interface](https://mailsort.readthedocs.io/en/latest/configuration.html#python-interface)
|
|
49
|
+
* [How mailsort works](https://mailsort.readthedocs.io/en/latest/architecture.html)
|
|
50
|
+
* [The fetch-store-train-predict-move loop](https://mailsort.readthedocs.io/en/latest/architecture.html#the-fetch-store-train-predict-move-loop)
|
|
51
|
+
* [What is stored, and where](https://mailsort.readthedocs.io/en/latest/architecture.html#what-is-stored-and-where)
|
|
52
|
+
* [Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html)
|
|
53
|
+
* [Why a classifier score is not automatically a probability](https://mailsort.readthedocs.io/en/latest/evaluation.html#why-a-classifier-score-is-not-automatically-a-probability)
|
|
54
|
+
* [`mailsort evaluate`](https://mailsort.readthedocs.io/en/latest/evaluation.html#mailsort-evaluate)
|
|
55
|
+
* [Troubleshooting](https://mailsort.readthedocs.io/en/latest/troubleshooting.html)
|
|
56
|
+
* [Support](https://mailsort.readthedocs.io/en/latest/support.html)
|
|
57
|
+
* [Developer](https://mailsort.readthedocs.io/en/latest/developer.html)
|
|
58
|
+
* [Python Interface](https://mailsort.readthedocs.io/en/latest/developer.html#python-interface)
|
|
59
|
+
* [Dry run / recommendation mode](https://mailsort.readthedocs.io/en/latest/developer.html#dry-run-recommendation-mode)
|
|
60
|
+
* [Evaluation](https://mailsort.readthedocs.io/en/latest/developer.html#evaluation)
|
|
61
|
+
* [The mailsort.api module](https://mailsort.readthedocs.io/en/latest/developer.html#the-mailsort-api-module)
|
|
62
|
+
|
|
63
|
+
## Installation
|
|
64
|
+
```
|
|
65
|
+
pip install mailsort
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Command line interface
|
|
69
|
+
`mailsort` is organized around six subcommands - `sync`, `train`, `predict`, `sort`, `status` and `evaluate`:
|
|
70
|
+
```
|
|
71
|
+
mailsort sync --host imap.example.com --username user@example.com --password "..."
|
|
72
|
+
mailsort train
|
|
73
|
+
mailsort predict some_label
|
|
74
|
+
mailsort sort some_label
|
|
75
|
+
mailsort status
|
|
76
|
+
mailsort evaluate
|
|
77
|
+
```
|
|
78
|
+
The IMAP password is provided with `--password`, e.g. by having your shell pull it from a
|
|
79
|
+
password manager.
|
|
80
|
+
|
|
81
|
+
- `sync` downloads new and changed messages from the mail server into the local database.
|
|
82
|
+
- `train` (re-)trains the machine learning model on the local database - it does not connect to
|
|
83
|
+
the mail server, so it also works offline once `sync` has run at least once. Each folder's
|
|
84
|
+
model is calibrated automatically where there is enough data to do so safely - see
|
|
85
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html).
|
|
86
|
+
- `predict FOLDER` reports what the trained model would recommend for the messages currently in
|
|
87
|
+
`FOLDER`, without moving, deleting or otherwise modifying anything on the server:
|
|
88
|
+
```
|
|
89
|
+
MESSAGE ID SUBJECT RECOMMENDED FOLDER SCORE TYPE ACCEPTED
|
|
90
|
+
-----------------------------------------------------------------------------------------------------------------------------
|
|
91
|
+
some_label\x1f101 Your invoice for March Receipts 0.97 calibrated True
|
|
92
|
+
some_label\x1f102 Let's catch up next week - 0.00 raw False
|
|
93
|
+
```
|
|
94
|
+
- `sort FOLDER` does the same scoring as `predict`, but actually moves the messages whose score
|
|
95
|
+
clears the configured threshold (`--recommendation-ratio`, 90% by default). That threshold is a
|
|
96
|
+
cutoff on a model score, not a guaranteed probability of being correct - use `mailsort evaluate`
|
|
97
|
+
to check what it actually achieves on your own mailbox before trusting it.
|
|
98
|
+
- `status` reports the local database location, how many messages it knows about, and how many
|
|
99
|
+
per-folder models have been trained - also without connecting to the mail server.
|
|
100
|
+
- `evaluate` estimates precision, recall, F1, support and coverage/abstention rate at
|
|
101
|
+
`--recommendation-ratio` on held-out data - the evidence a threshold choice should be based on.
|
|
102
|
+
Add `--sweep` to compare several thresholds at once. It never connects to the mail server and
|
|
103
|
+
never changes the models `mailsort train` has already stored - see
|
|
104
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html).
|
|
105
|
+
|
|
106
|
+
Run `mailsort --help` or `mailsort <command> --help` for the full list of options and examples.
|
|
107
|
+
|
|
108
|
+
### Upgrading from the pre-1.0 CLI
|
|
109
|
+
The previous flat `-u/--update` and `-l/--label` options still work exactly as before, but are
|
|
110
|
+
deprecated in favor of the subcommands above:
|
|
111
|
+
```
|
|
112
|
+
mailsort --host imap.example.com --username user@example.com --password "..." -u
|
|
113
|
+
mailsort --host imap.example.com --username user@example.com --password "..." -l "some_label"
|
|
114
|
+
mailsort --host imap.example.com --username user@example.com --password "..." -l "some_label" --dry-run
|
|
115
|
+
```
|
|
116
|
+
is equivalent to:
|
|
117
|
+
```
|
|
118
|
+
mailsort sync --host imap.example.com --username user@example.com --password "..."
|
|
119
|
+
mailsort train
|
|
120
|
+
mailsort sort some_label --host imap.example.com --username user@example.com --password "..."
|
|
121
|
+
mailsort predict some_label --host imap.example.com --username user@example.com --password "..."
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Python interface
|
|
125
|
+
The recommended way to use `mailsort` from Python is `MailSorter`, a small facade that wraps a
|
|
126
|
+
mailbox backend (such as `Imap`) and exposes the fetch-store-train-predict-move loop through the
|
|
127
|
+
same vocabulary as the CLI:
|
|
128
|
+
```python
|
|
129
|
+
from mailsort import Imap, MailSorter
|
|
130
|
+
|
|
131
|
+
with MailSorter(
|
|
132
|
+
Imap(
|
|
133
|
+
host="imap.example.com",
|
|
134
|
+
port=993,
|
|
135
|
+
username="user@example.com",
|
|
136
|
+
password="...",
|
|
137
|
+
connection_str="sqlite:///email.db",
|
|
138
|
+
)
|
|
139
|
+
) as sorter:
|
|
140
|
+
sorter.sync()
|
|
141
|
+
sorter.train()
|
|
142
|
+
predictions = sorter.predict("some_label")
|
|
143
|
+
sorter.sort("some_label")
|
|
144
|
+
```
|
|
145
|
+
- `sync()` downloads new and changed messages into the local database and returns a `SyncResult`.
|
|
146
|
+
- `train()` (re-)trains the machine learning models on the local database and returns a
|
|
147
|
+
`TrainResult`.
|
|
148
|
+
- `predict(folder)` is read-only: it downloads and scores the messages currently in `folder` and
|
|
149
|
+
returns a `list[Prediction]`, without moving, deleting or otherwise modifying anything on the
|
|
150
|
+
server.
|
|
151
|
+
- `sort(folder)` scores messages the same way as `predict()`, but actually moves the ones whose
|
|
152
|
+
score clears `recommendation_ratio` (90% by default), and returns a `SortResult`.
|
|
153
|
+
|
|
154
|
+
`MailSorter` only relies on the public `AbstractMailBox` interface, not on anything IMAP-specific,
|
|
155
|
+
so it works unmodified with any current or future mailbox backend - including a Gmail backend
|
|
156
|
+
built by [gmailsorter](https://github.com/jan-janssen/gmailsorter).
|
|
157
|
+
|
|
158
|
+
### Dry run / recommendation mode
|
|
159
|
+
`predict()` computes the exact same machine learning predictions `sort()` would act on, but only
|
|
160
|
+
returns them - it never moves, deletes, archives or otherwise modifies anything on the server.
|
|
161
|
+
Each message gets a `Prediction`, a plain, JSON-serializable dataclass - a first-class,
|
|
162
|
+
side-effect-free representation of one classification result, independent of any mailbox change:
|
|
163
|
+
```python
|
|
164
|
+
for prediction in sorter.predict("some_label"):
|
|
165
|
+
print(
|
|
166
|
+
prediction.message_id,
|
|
167
|
+
prediction.source_folder,
|
|
168
|
+
prediction.recommended_folder,
|
|
169
|
+
prediction.score,
|
|
170
|
+
prediction.threshold,
|
|
171
|
+
prediction.accepted,
|
|
172
|
+
prediction.score_type,
|
|
173
|
+
prediction.subject,
|
|
174
|
+
)
|
|
175
|
+
```
|
|
176
|
+
`Prediction` has:
|
|
177
|
+
- `message_id` - id that uniquely identifies the message
|
|
178
|
+
- `source_folder` - the folder the message was fetched and scored from
|
|
179
|
+
- `recommended_folder` - the folder the model scores highest for this message, or `None` if no
|
|
180
|
+
model has been trained yet
|
|
181
|
+
- `score` - the model's score for `recommended_folder`
|
|
182
|
+
- `threshold` - the `recommendation_ratio` this prediction was scored against
|
|
183
|
+
- `accepted` - whether `score` clears `threshold`, i.e. whether `sort()` would move this message
|
|
184
|
+
for real given the same `recommendation_ratio` - an abstained prediction (`accepted=False`) is
|
|
185
|
+
never acted on
|
|
186
|
+
- `score_type` - whether `score` is a calibrated probability (`ScoreType.CALIBRATED`) or a raw,
|
|
187
|
+
uncalibrated classifier score (`ScoreType.RAW`) - see
|
|
188
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html) for what
|
|
189
|
+
that distinction means and why `recommendation_ratio` is not automatically a probability
|
|
190
|
+
- `subject` - the message subject, if available; display metadata, not itself part of the
|
|
191
|
+
classification
|
|
192
|
+
|
|
193
|
+
Because every field is a plain value, `Prediction` is equally useful to the CLI's `predict` table,
|
|
194
|
+
to a caller such as `gmailsorter`, to a future web interface, or to an audit log - store or ship a
|
|
195
|
+
`Prediction` as-is, no scikit-learn objects involved.
|
|
196
|
+
|
|
197
|
+
### Evaluation
|
|
198
|
+
Before trusting `sort()`/`mailsort sort` to move mail automatically, check what a given
|
|
199
|
+
`recommendation_ratio` actually achieves on your own data, rather than assuming it does what the
|
|
200
|
+
number suggests:
|
|
201
|
+
```python
|
|
202
|
+
from mailsort.api import evaluate_models
|
|
203
|
+
|
|
204
|
+
report = evaluate_models(connection_str="sqlite:///email.db", recommendation_ratio=0.9)
|
|
205
|
+
print(report.coverage, report.overall_precision)
|
|
206
|
+
```
|
|
207
|
+
This trains a separate, throwaway set of models on part of your local database and scores them
|
|
208
|
+
against the rest - it never touches the models `mailsort train` has already stored. See
|
|
209
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html) for the
|
|
210
|
+
full reasoning (why a classifier score is not automatically a probability, when calibration is and
|
|
211
|
+
is not applied, and how to read the report), and the command line equivalent,
|
|
212
|
+
`mailsort evaluate`.
|
|
213
|
+
|
|
214
|
+
### Low-level interface
|
|
215
|
+
`MailSorter` is a thin wrapper around methods `Imap` (an `AbstractMailBox`) already exposes
|
|
216
|
+
directly. They remain available, both for backwards compatibility with existing scripts and for
|
|
217
|
+
callers who want finer-grained control - `MailSorter.sync()`/`train()`/`predict()`/`sort()` above
|
|
218
|
+
are implemented purely in terms of them, so behavior is identical either way:
|
|
219
|
+
```python
|
|
220
|
+
from mailsort import Imap
|
|
221
|
+
|
|
222
|
+
imap = Imap(
|
|
223
|
+
host="imap.example.com",
|
|
224
|
+
port=993,
|
|
225
|
+
username="user@example.com",
|
|
226
|
+
password="...",
|
|
227
|
+
connection_str="sqlite:///email.db",
|
|
228
|
+
)
|
|
229
|
+
imap.update_database(quick=False)
|
|
230
|
+
imap.fit_machine_learning_model_to_database()
|
|
231
|
+
imap.filter_messages_from_server(label="some_label", recommendation_ratio=0.9)
|
|
232
|
+
```
|
|
233
|
+
`update_database()`, `fit_machine_learning_model_to_database()` and `filter_messages_from_server()`
|
|
234
|
+
return the same `SyncResult`/`TrainResult`/`SortResult` objects as their `MailSorter` counterparts.
|
|
235
|
+
`get_label_recommendations()` is `predict()`'s implementation - it already returns `list[Prediction]`,
|
|
236
|
+
so `MailSorter.predict()` is a pure passthrough to it:
|
|
237
|
+
```python
|
|
238
|
+
for prediction in imap.get_label_recommendations(
|
|
239
|
+
label="some_label", recommendation_ratio=0.9
|
|
240
|
+
):
|
|
241
|
+
print(prediction.message_id, prediction.recommended_folder)
|
|
242
|
+
```
|
|
243
|
+
`filter_messages_from_server()` scores messages through this exact same call, then moves only the
|
|
244
|
+
accepted predictions - inference and mailbox mutation are separated in code, not just by
|
|
245
|
+
convention, so it is not possible to move a message without it first having gone through
|
|
246
|
+
`get_label_recommendations()`.
|
|
247
|
+
|
|
248
|
+
### Train and inspect the local database without a mail connection
|
|
249
|
+
`train_machine_learning_models()` and `get_database_status()` are the functions behind the
|
|
250
|
+
`train` and `status` CLI commands. Both only need the database connection string, not mail server
|
|
251
|
+
credentials:
|
|
252
|
+
```python
|
|
253
|
+
from mailsort.api import get_database_status, train_machine_learning_models
|
|
254
|
+
|
|
255
|
+
train_machine_learning_models(connection_str="sqlite:///email.db")
|
|
256
|
+
status = get_database_status(connection_str="sqlite:///email.db")
|
|
257
|
+
print(status.message_count, status.trained_label_lst)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
## API for downstream packages
|
|
261
|
+
Packages built on top of `mailsort`, such as `gmailsorter`, should import the shared database and
|
|
262
|
+
machine learning building blocks from `mailsort.api` rather than from mailsort's internal modules
|
|
263
|
+
directly. This keeps `mailsort.api` as the single place that needs to stay consistent when
|
|
264
|
+
mailsort's internals are refactored.
|
|
265
|
+
```python
|
|
266
|
+
from mailsort.api import (
|
|
267
|
+
AbstractMailBox,
|
|
268
|
+
AbstractMessage,
|
|
269
|
+
DatabaseInterface,
|
|
270
|
+
DatabaseStatus,
|
|
271
|
+
DatabaseTemplate,
|
|
272
|
+
EvaluationReport,
|
|
273
|
+
FolderMetrics,
|
|
274
|
+
MachineLearningDatabase,
|
|
275
|
+
MailSorter,
|
|
276
|
+
Prediction,
|
|
277
|
+
ScoreType,
|
|
278
|
+
SortResult,
|
|
279
|
+
SyncResult,
|
|
280
|
+
TrainResult,
|
|
281
|
+
email_date_converter,
|
|
282
|
+
evaluate_models,
|
|
283
|
+
get_database_status,
|
|
284
|
+
get_email_database,
|
|
285
|
+
get_machine_learning_database,
|
|
286
|
+
strip_html_tags,
|
|
287
|
+
train_machine_learning_models,
|
|
288
|
+
)
|
|
289
|
+
```
|
|
290
|
+
`MailSorter`, `evaluate_models()` and the `SyncResult`/`TrainResult`/`Prediction`/`SortResult`/
|
|
291
|
+
`EvaluationReport`/`FolderMetrics` result types are exported here, not just from `mailsort`
|
|
292
|
+
directly, because they are generic over `AbstractMailBox`: a downstream package implementing its
|
|
293
|
+
own mailbox backend (as `gmailsorter` does for Gmail) can wrap its own `AbstractMailBox` subclass
|
|
294
|
+
in the same `MailSorter` facade, and evaluate its own database the same way, without
|
|
295
|
+
reimplementing either.
|
mailsort-0.0.3/README.md
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
# mailsort
|
|
2
|
+
[](https://github.com/jan-janssen/mailsort/actions/workflows/unittest.yml)
|
|
3
|
+
[](https://codecov.io/github/jan-janssen/mailsort)
|
|
4
|
+
[](https://mailsort.readthedocs.io/en/latest/?badge=latest)
|
|
5
|
+
[](https://github.com/psf/black)
|
|
6
|
+
|
|
7
|
+
Assign labels to emails on any IMAP mail server based on their similarity to other emails already
|
|
8
|
+
assigned to the same label.
|
|
9
|
+
|
|
10
|
+
`mailsort` connects to a mail account over plain IMAP, trains a machine learning model on the labels
|
|
11
|
+
(IMAP folders) you have already assigned, and uses that model to suggest or apply labels to new
|
|
12
|
+
messages. It has no dependency on Google APIs - for Gmail-specific features (OAuth, the Gmail label
|
|
13
|
+
API, the sorting daemon and web UI) see [gmailsorter](https://github.com/jan-janssen/gmailsorter),
|
|
14
|
+
which depends on `mailsort` for the shared IMAP and machine learning core.
|
|
15
|
+
|
|
16
|
+
To learn more about `mailsort` please have a look at the documentation below.
|
|
17
|
+
|
|
18
|
+
* [Preparation](https://mailsort.readthedocs.io/en/latest/preparation.html)
|
|
19
|
+
* [Sort your emails](https://mailsort.readthedocs.io/en/latest/preparation.html#sort-your-emails)
|
|
20
|
+
* [Configure your email account](https://mailsort.readthedocs.io/en/latest/preparation.html#configure-your-email-account)
|
|
21
|
+
* [Configuration](https://mailsort.readthedocs.io/en/latest/configuration.html)
|
|
22
|
+
* [Command line interface](https://mailsort.readthedocs.io/en/latest/configuration.html#command-line-interface)
|
|
23
|
+
* [Dry run / recommendation mode](https://mailsort.readthedocs.io/en/latest/configuration.html#dry-run-recommendation-mode)
|
|
24
|
+
* [Python interface](https://mailsort.readthedocs.io/en/latest/configuration.html#python-interface)
|
|
25
|
+
* [How mailsort works](https://mailsort.readthedocs.io/en/latest/architecture.html)
|
|
26
|
+
* [The fetch-store-train-predict-move loop](https://mailsort.readthedocs.io/en/latest/architecture.html#the-fetch-store-train-predict-move-loop)
|
|
27
|
+
* [What is stored, and where](https://mailsort.readthedocs.io/en/latest/architecture.html#what-is-stored-and-where)
|
|
28
|
+
* [Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html)
|
|
29
|
+
* [Why a classifier score is not automatically a probability](https://mailsort.readthedocs.io/en/latest/evaluation.html#why-a-classifier-score-is-not-automatically-a-probability)
|
|
30
|
+
* [`mailsort evaluate`](https://mailsort.readthedocs.io/en/latest/evaluation.html#mailsort-evaluate)
|
|
31
|
+
* [Troubleshooting](https://mailsort.readthedocs.io/en/latest/troubleshooting.html)
|
|
32
|
+
* [Support](https://mailsort.readthedocs.io/en/latest/support.html)
|
|
33
|
+
* [Developer](https://mailsort.readthedocs.io/en/latest/developer.html)
|
|
34
|
+
* [Python Interface](https://mailsort.readthedocs.io/en/latest/developer.html#python-interface)
|
|
35
|
+
* [Dry run / recommendation mode](https://mailsort.readthedocs.io/en/latest/developer.html#dry-run-recommendation-mode)
|
|
36
|
+
* [Evaluation](https://mailsort.readthedocs.io/en/latest/developer.html#evaluation)
|
|
37
|
+
* [The mailsort.api module](https://mailsort.readthedocs.io/en/latest/developer.html#the-mailsort-api-module)
|
|
38
|
+
|
|
39
|
+
## Installation
|
|
40
|
+
```
|
|
41
|
+
pip install mailsort
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Command line interface
|
|
45
|
+
`mailsort` is organized around six subcommands - `sync`, `train`, `predict`, `sort`, `status` and `evaluate`:
|
|
46
|
+
```
|
|
47
|
+
mailsort sync --host imap.example.com --username user@example.com --password "..."
|
|
48
|
+
mailsort train
|
|
49
|
+
mailsort predict some_label
|
|
50
|
+
mailsort sort some_label
|
|
51
|
+
mailsort status
|
|
52
|
+
mailsort evaluate
|
|
53
|
+
```
|
|
54
|
+
The IMAP password is provided with `--password`, e.g. by having your shell pull it from a
|
|
55
|
+
password manager.
|
|
56
|
+
|
|
57
|
+
- `sync` downloads new and changed messages from the mail server into the local database.
|
|
58
|
+
- `train` (re-)trains the machine learning model on the local database - it does not connect to
|
|
59
|
+
the mail server, so it also works offline once `sync` has run at least once. Each folder's
|
|
60
|
+
model is calibrated automatically where there is enough data to do so safely - see
|
|
61
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html).
|
|
62
|
+
- `predict FOLDER` reports what the trained model would recommend for the messages currently in
|
|
63
|
+
`FOLDER`, without moving, deleting or otherwise modifying anything on the server:
|
|
64
|
+
```
|
|
65
|
+
MESSAGE ID SUBJECT RECOMMENDED FOLDER SCORE TYPE ACCEPTED
|
|
66
|
+
-----------------------------------------------------------------------------------------------------------------------------
|
|
67
|
+
some_label\x1f101 Your invoice for March Receipts 0.97 calibrated True
|
|
68
|
+
some_label\x1f102 Let's catch up next week - 0.00 raw False
|
|
69
|
+
```
|
|
70
|
+
- `sort FOLDER` does the same scoring as `predict`, but actually moves the messages whose score
|
|
71
|
+
clears the configured threshold (`--recommendation-ratio`, 90% by default). That threshold is a
|
|
72
|
+
cutoff on a model score, not a guaranteed probability of being correct - use `mailsort evaluate`
|
|
73
|
+
to check what it actually achieves on your own mailbox before trusting it.
|
|
74
|
+
- `status` reports the local database location, how many messages it knows about, and how many
|
|
75
|
+
per-folder models have been trained - also without connecting to the mail server.
|
|
76
|
+
- `evaluate` estimates precision, recall, F1, support and coverage/abstention rate at
|
|
77
|
+
`--recommendation-ratio` on held-out data - the evidence a threshold choice should be based on.
|
|
78
|
+
Add `--sweep` to compare several thresholds at once. It never connects to the mail server and
|
|
79
|
+
never changes the models `mailsort train` has already stored - see
|
|
80
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html).
|
|
81
|
+
|
|
82
|
+
Run `mailsort --help` or `mailsort <command> --help` for the full list of options and examples.
|
|
83
|
+
|
|
84
|
+
### Upgrading from the pre-1.0 CLI
|
|
85
|
+
The previous flat `-u/--update` and `-l/--label` options still work exactly as before, but are
|
|
86
|
+
deprecated in favor of the subcommands above:
|
|
87
|
+
```
|
|
88
|
+
mailsort --host imap.example.com --username user@example.com --password "..." -u
|
|
89
|
+
mailsort --host imap.example.com --username user@example.com --password "..." -l "some_label"
|
|
90
|
+
mailsort --host imap.example.com --username user@example.com --password "..." -l "some_label" --dry-run
|
|
91
|
+
```
|
|
92
|
+
is equivalent to:
|
|
93
|
+
```
|
|
94
|
+
mailsort sync --host imap.example.com --username user@example.com --password "..."
|
|
95
|
+
mailsort train
|
|
96
|
+
mailsort sort some_label --host imap.example.com --username user@example.com --password "..."
|
|
97
|
+
mailsort predict some_label --host imap.example.com --username user@example.com --password "..."
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Python interface
|
|
101
|
+
The recommended way to use `mailsort` from Python is `MailSorter`, a small facade that wraps a
|
|
102
|
+
mailbox backend (such as `Imap`) and exposes the fetch-store-train-predict-move loop through the
|
|
103
|
+
same vocabulary as the CLI:
|
|
104
|
+
```python
|
|
105
|
+
from mailsort import Imap, MailSorter
|
|
106
|
+
|
|
107
|
+
with MailSorter(
|
|
108
|
+
Imap(
|
|
109
|
+
host="imap.example.com",
|
|
110
|
+
port=993,
|
|
111
|
+
username="user@example.com",
|
|
112
|
+
password="...",
|
|
113
|
+
connection_str="sqlite:///email.db",
|
|
114
|
+
)
|
|
115
|
+
) as sorter:
|
|
116
|
+
sorter.sync()
|
|
117
|
+
sorter.train()
|
|
118
|
+
predictions = sorter.predict("some_label")
|
|
119
|
+
sorter.sort("some_label")
|
|
120
|
+
```
|
|
121
|
+
- `sync()` downloads new and changed messages into the local database and returns a `SyncResult`.
|
|
122
|
+
- `train()` (re-)trains the machine learning models on the local database and returns a
|
|
123
|
+
`TrainResult`.
|
|
124
|
+
- `predict(folder)` is read-only: it downloads and scores the messages currently in `folder` and
|
|
125
|
+
returns a `list[Prediction]`, without moving, deleting or otherwise modifying anything on the
|
|
126
|
+
server.
|
|
127
|
+
- `sort(folder)` scores messages the same way as `predict()`, but actually moves the ones whose
|
|
128
|
+
score clears `recommendation_ratio` (90% by default), and returns a `SortResult`.
|
|
129
|
+
|
|
130
|
+
`MailSorter` only relies on the public `AbstractMailBox` interface, not on anything IMAP-specific,
|
|
131
|
+
so it works unmodified with any current or future mailbox backend - including a Gmail backend
|
|
132
|
+
built by [gmailsorter](https://github.com/jan-janssen/gmailsorter).
|
|
133
|
+
|
|
134
|
+
### Dry run / recommendation mode
|
|
135
|
+
`predict()` computes the exact same machine learning predictions `sort()` would act on, but only
|
|
136
|
+
returns them - it never moves, deletes, archives or otherwise modifies anything on the server.
|
|
137
|
+
Each message gets a `Prediction`, a plain, JSON-serializable dataclass - a first-class,
|
|
138
|
+
side-effect-free representation of one classification result, independent of any mailbox change:
|
|
139
|
+
```python
|
|
140
|
+
for prediction in sorter.predict("some_label"):
|
|
141
|
+
print(
|
|
142
|
+
prediction.message_id,
|
|
143
|
+
prediction.source_folder,
|
|
144
|
+
prediction.recommended_folder,
|
|
145
|
+
prediction.score,
|
|
146
|
+
prediction.threshold,
|
|
147
|
+
prediction.accepted,
|
|
148
|
+
prediction.score_type,
|
|
149
|
+
prediction.subject,
|
|
150
|
+
)
|
|
151
|
+
```
|
|
152
|
+
`Prediction` has:
|
|
153
|
+
- `message_id` - id that uniquely identifies the message
|
|
154
|
+
- `source_folder` - the folder the message was fetched and scored from
|
|
155
|
+
- `recommended_folder` - the folder the model scores highest for this message, or `None` if no
|
|
156
|
+
model has been trained yet
|
|
157
|
+
- `score` - the model's score for `recommended_folder`
|
|
158
|
+
- `threshold` - the `recommendation_ratio` this prediction was scored against
|
|
159
|
+
- `accepted` - whether `score` clears `threshold`, i.e. whether `sort()` would move this message
|
|
160
|
+
for real given the same `recommendation_ratio` - an abstained prediction (`accepted=False`) is
|
|
161
|
+
never acted on
|
|
162
|
+
- `score_type` - whether `score` is a calibrated probability (`ScoreType.CALIBRATED`) or a raw,
|
|
163
|
+
uncalibrated classifier score (`ScoreType.RAW`) - see
|
|
164
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html) for what
|
|
165
|
+
that distinction means and why `recommendation_ratio` is not automatically a probability
|
|
166
|
+
- `subject` - the message subject, if available; display metadata, not itself part of the
|
|
167
|
+
classification
|
|
168
|
+
|
|
169
|
+
Because every field is a plain value, `Prediction` is equally useful to the CLI's `predict` table,
|
|
170
|
+
to a caller such as `gmailsorter`, to a future web interface, or to an audit log - store or ship a
|
|
171
|
+
`Prediction` as-is, no scikit-learn objects involved.
|
|
172
|
+
|
|
173
|
+
### Evaluation
|
|
174
|
+
Before trusting `sort()`/`mailsort sort` to move mail automatically, check what a given
|
|
175
|
+
`recommendation_ratio` actually achieves on your own data, rather than assuming it does what the
|
|
176
|
+
number suggests:
|
|
177
|
+
```python
|
|
178
|
+
from mailsort.api import evaluate_models
|
|
179
|
+
|
|
180
|
+
report = evaluate_models(connection_str="sqlite:///email.db", recommendation_ratio=0.9)
|
|
181
|
+
print(report.coverage, report.overall_precision)
|
|
182
|
+
```
|
|
183
|
+
This trains a separate, throwaway set of models on part of your local database and scores them
|
|
184
|
+
against the rest - it never touches the models `mailsort train` has already stored. See
|
|
185
|
+
[Evaluation and confidence](https://mailsort.readthedocs.io/en/latest/evaluation.html) for the
|
|
186
|
+
full reasoning (why a classifier score is not automatically a probability, when calibration is and
|
|
187
|
+
is not applied, and how to read the report), and the command line equivalent,
|
|
188
|
+
`mailsort evaluate`.
|
|
189
|
+
|
|
190
|
+
### Low-level interface
|
|
191
|
+
`MailSorter` is a thin wrapper around methods `Imap` (an `AbstractMailBox`) already exposes
|
|
192
|
+
directly. They remain available, both for backwards compatibility with existing scripts and for
|
|
193
|
+
callers who want finer-grained control - `MailSorter.sync()`/`train()`/`predict()`/`sort()` above
|
|
194
|
+
are implemented purely in terms of them, so behavior is identical either way:
|
|
195
|
+
```python
|
|
196
|
+
from mailsort import Imap
|
|
197
|
+
|
|
198
|
+
imap = Imap(
|
|
199
|
+
host="imap.example.com",
|
|
200
|
+
port=993,
|
|
201
|
+
username="user@example.com",
|
|
202
|
+
password="...",
|
|
203
|
+
connection_str="sqlite:///email.db",
|
|
204
|
+
)
|
|
205
|
+
imap.update_database(quick=False)
|
|
206
|
+
imap.fit_machine_learning_model_to_database()
|
|
207
|
+
imap.filter_messages_from_server(label="some_label", recommendation_ratio=0.9)
|
|
208
|
+
```
|
|
209
|
+
`update_database()`, `fit_machine_learning_model_to_database()` and `filter_messages_from_server()`
|
|
210
|
+
return the same `SyncResult`/`TrainResult`/`SortResult` objects as their `MailSorter` counterparts.
|
|
211
|
+
`get_label_recommendations()` is `predict()`'s implementation - it already returns `list[Prediction]`,
|
|
212
|
+
so `MailSorter.predict()` is a pure passthrough to it:
|
|
213
|
+
```python
|
|
214
|
+
for prediction in imap.get_label_recommendations(
|
|
215
|
+
label="some_label", recommendation_ratio=0.9
|
|
216
|
+
):
|
|
217
|
+
print(prediction.message_id, prediction.recommended_folder)
|
|
218
|
+
```
|
|
219
|
+
`filter_messages_from_server()` scores messages through this exact same call, then moves only the
|
|
220
|
+
accepted predictions - inference and mailbox mutation are separated in code, not just by
|
|
221
|
+
convention, so it is not possible to move a message without it first having gone through
|
|
222
|
+
`get_label_recommendations()`.
|
|
223
|
+
|
|
224
|
+
### Train and inspect the local database without a mail connection
|
|
225
|
+
`train_machine_learning_models()` and `get_database_status()` are the functions behind the
|
|
226
|
+
`train` and `status` CLI commands. Both only need the database connection string, not mail server
|
|
227
|
+
credentials:
|
|
228
|
+
```python
|
|
229
|
+
from mailsort.api import get_database_status, train_machine_learning_models
|
|
230
|
+
|
|
231
|
+
train_machine_learning_models(connection_str="sqlite:///email.db")
|
|
232
|
+
status = get_database_status(connection_str="sqlite:///email.db")
|
|
233
|
+
print(status.message_count, status.trained_label_lst)
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## API for downstream packages
|
|
237
|
+
Packages built on top of `mailsort`, such as `gmailsorter`, should import the shared database and
|
|
238
|
+
machine learning building blocks from `mailsort.api` rather than from mailsort's internal modules
|
|
239
|
+
directly. This keeps `mailsort.api` as the single place that needs to stay consistent when
|
|
240
|
+
mailsort's internals are refactored.
|
|
241
|
+
```python
|
|
242
|
+
from mailsort.api import (
|
|
243
|
+
AbstractMailBox,
|
|
244
|
+
AbstractMessage,
|
|
245
|
+
DatabaseInterface,
|
|
246
|
+
DatabaseStatus,
|
|
247
|
+
DatabaseTemplate,
|
|
248
|
+
EvaluationReport,
|
|
249
|
+
FolderMetrics,
|
|
250
|
+
MachineLearningDatabase,
|
|
251
|
+
MailSorter,
|
|
252
|
+
Prediction,
|
|
253
|
+
ScoreType,
|
|
254
|
+
SortResult,
|
|
255
|
+
SyncResult,
|
|
256
|
+
TrainResult,
|
|
257
|
+
email_date_converter,
|
|
258
|
+
evaluate_models,
|
|
259
|
+
get_database_status,
|
|
260
|
+
get_email_database,
|
|
261
|
+
get_machine_learning_database,
|
|
262
|
+
strip_html_tags,
|
|
263
|
+
train_machine_learning_models,
|
|
264
|
+
)
|
|
265
|
+
```
|
|
266
|
+
`MailSorter`, `evaluate_models()` and the `SyncResult`/`TrainResult`/`Prediction`/`SortResult`/
|
|
267
|
+
`EvaluationReport`/`FolderMetrics` result types are exported here, not just from `mailsort`
|
|
268
|
+
directly, because they are generic over `AbstractMailBox`: a downstream package implementing its
|
|
269
|
+
own mailbox backend (as `gmailsorter` does for Gmail) can wrap its own `AbstractMailBox` subclass
|
|
270
|
+
in the same `MailSorter` facade, and evaluate its own database the same way, without
|
|
271
|
+
reimplementing either.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
from mailsort.local import Imap
|
|
2
|
+
from mailsort.results import Prediction, ScoreType, SortResult, SyncResult, TrainResult
|
|
3
|
+
from mailsort.sorter import MailSorter
|
|
4
|
+
|
|
5
|
+
from . import _version
|
|
6
|
+
|
|
7
|
+
__version__: str = _version.__version__
|
|
8
|
+
__all__ = [
|
|
9
|
+
"Imap",
|
|
10
|
+
"MailSorter",
|
|
11
|
+
"Prediction",
|
|
12
|
+
"ScoreType",
|
|
13
|
+
"SortResult",
|
|
14
|
+
"SyncResult",
|
|
15
|
+
"TrainResult",
|
|
16
|
+
]
|