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.
Files changed (34) hide show
  1. mailsort-0.0.3/PKG-INFO +295 -0
  2. mailsort-0.0.3/README.md +271 -0
  3. mailsort-0.0.3/src/mailsort/__init__.py +16 -0
  4. mailsort-0.0.3/src/mailsort/__main__.py +672 -0
  5. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/_version.py +2 -2
  6. mailsort-0.0.3/src/mailsort/api.py +43 -0
  7. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/database.py +18 -0
  8. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/mail.py +203 -47
  9. mailsort-0.0.3/src/mailsort/evaluation.py +156 -0
  10. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/mail.py +0 -7
  11. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/ml/__init__.py +10 -0
  12. mailsort-0.0.3/src/mailsort/ml/calibration.py +201 -0
  13. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/ml/database.py +12 -0
  14. mailsort-0.0.3/src/mailsort/ml/evaluation.py +545 -0
  15. mailsort-0.0.3/src/mailsort/ml/model.py +266 -0
  16. mailsort-0.0.3/src/mailsort/results.py +140 -0
  17. mailsort-0.0.3/src/mailsort/sorter.py +201 -0
  18. mailsort-0.0.3/src/mailsort/status.py +67 -0
  19. mailsort-0.0.3/src/mailsort/training.py +102 -0
  20. mailsort-0.0.2/PKG-INFO +0 -66
  21. mailsort-0.0.2/README.md +0 -42
  22. mailsort-0.0.2/src/mailsort/__init__.py +0 -6
  23. mailsort-0.0.2/src/mailsort/__main__.py +0 -91
  24. mailsort-0.0.2/src/mailsort/ml/model.py +0 -127
  25. {mailsort-0.0.2 → mailsort-0.0.3}/.gitignore +0 -0
  26. {mailsort-0.0.2 → mailsort-0.0.3}/LICENSE +0 -0
  27. {mailsort-0.0.2 → mailsort-0.0.3}/pyproject.toml +0 -0
  28. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/__init__.py +0 -0
  29. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/base/message.py +0 -0
  30. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/__init__.py +0 -0
  31. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/authentication.py +0 -0
  32. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/imap/message.py +0 -0
  33. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/local.py +0 -0
  34. {mailsort-0.0.2 → mailsort-0.0.3}/src/mailsort/ml/encoding.py +0 -0
@@ -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
+ [![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)
27
+ [![codecov](https://codecov.io/github/jan-janssen/mailsort/graph/badge.svg)](https://codecov.io/github/jan-janssen/mailsort)
28
+ [![Documentation Status](https://readthedocs.org/projects/mailsort/badge/?version=latest)](https://mailsort.readthedocs.io/en/latest/?badge=latest)
29
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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.
@@ -0,0 +1,271 @@
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
+ 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
+ ]