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