Vast Parcel: the tracking number model
Confirms tracking numbers found in mail (src/manage/parcels.rs). The app
finds candidates without a model: runs of uppercase letters and digits
(possibly in groups split by spaces) that have a carrier's format and check
digit, checked by the tracking-numbers
crate against the tracking_number_data
catalog. About one random 10- or 12-digit number in ten passes some carrier's
check, so order, invoice and phone numbers would pass too. This model decides
from the words around each candidate whether the message gives it as a
tracking number.
It is installed when Settings β Local AI β Find tracking numbers is turned on, and deleted when it is turned off. Like the other models, it isn't kept in git:
| File | Used on | Runtime |
|---|---|---|
parcel-v1.mlmodel |
macOS | Core ML (compiled for the Mac when installed) |
parcel-v1.bin |
Windows, Linux, phones | Picacho's own (src/manage/local_ai/runtime.rs) |
Both hold the same network, and each is checked against the size and
SHA-256 of PARCEL_COREML / PARCEL_NATIVE in src/manage/local_ai/mod.rs.
It will be published on Hugging Face as
pinaltech/vast-parcel.
Until it is, the model is marked local: true there and
installed from this directory (where train.py writes it) instead of being
downloaded: the path is compiled in from the source tree Picacho was built
from, or PICACHO_LOCAL_MODELS names another directory holding the files.
PICACHO_MODELS_URL still downloads it from a mirror. A build used on
another computer can't install it until it is published.
Without the model, the app accepts a candidate only with a shipping word
shortly before it on its line (or in the subject), and never a bare number
shorter than 12 digits. Tracking numbers in schema.org ParcelDelivery
markup are taken as the sender gives them, with or without the model.
The reader shows the tracking numbers of the open message, and each account's Summary (under its Inbox) lists every parcel its mail tells of, last updated first: the newest update date a message gives (a delivery event's time in the markup, or an "Updated:" date in the text), or else when the newest message was sent.
How it works
- Features. The sign-in code model's features (
../otp/features.py: the words around the number, their prefixes, its shape and line, the subject, and the OTP lexicon's concepts), plus the concepts inlexicon.jsonnamed by the words before and after the number, close before it on its line, and in the subject: track, parcel, deliver, ship, and order, invoice, customer, phone, reference, with stems in many languages. Everything is hashed into 16,384 slots. - Model. A bag-of-features network with one hidden layer of 8 units and a logistic output (512 KB). A candidate scoring 0.5 or more is a tracking number.
features.py and lexicon.json are the reference; the app builds the same
features in src/manage/local_ai/parcel.rs, with the lexicon compiled in, so
a lexicon change needs an app update as well as a new model. parity.json
is checked by cargo test matches_the_training_code: each of its numbers is
found by the app as a candidate at the same place, with the same features,
vector and score.
Training
python3 train.py # numpy: parcel-v1.bin, parity.json
python3 train.py --coreml # also parcel-v1.mlmodel (needs coremltools)
--coreml needs coremltools,
which has builds only for Python 3.13 and older: on a newer Python it
installs without its compiled parts and can't write the file, so
train.py stops before training. Use a Python 3.13 environment, on any
system (Linux works too: only running the model needs a Mac):
uv venv --python 3.13 .venv && uv pip install --python .venv numpy coremltools
.venv/bin/python train.py --coreml
Lines saying Failed to load ... libcoremlpython are expected outside
macOS: those parts run models, and writing one doesn't need them.
The weights depend slightly on the numpy version, so after training, update
both sizes and digests in src/manage/local_ai/mod.rs with what train.py
prints (parity.json is rewritten to match).
The training mail is synthetic (data.py). Every number in it is one of
the catalog's valid test numbers (numbers.json: those the
tracking-numbers crate identifies, with the carrier it names), given as a
tracking number in shipping mail, or as an order, invoice, account, phone,
booking or other number in other mail and beside tracking numbers. Labels,
sentences and subjects are held out a quarter at a time:
| Wording | Precision | Recall |
|---|---|---|
| Held out of training | 99.9% | 93% |
| Seen in training | 100% | 100% |
Real mail will have phrasings the templates don't cover; more varied examples improve it.
Publishing a new version
- Retrain with
--coreml, then update the sizes and digeststrain.pyprints inPARCEL_NATIVEandPARCEL_COREML(src/manage/local_ai/mod.rs). Bump the version in the file names when the features or lexicon change. - Upload both files:
hf upload pinaltech/vast-parcel models/parcel/parcel-v1.bin parcel-v1.bin, and the same forparcel-v1.mlmodel. Then setlocal: falseon both models, so the app downloads them. Upload before releasing that app. cargo test the_published_models_are_the_ones_the_app_expectschecks the uploaded file (deletetarget/test-modelsfirst).
- Downloads last month
- -