Skip to content
wildroot-ioPublic
forked from fazlerocks/jevmail

About

A read-only Gmail reader that sorts your mail with a small model on your own machine. Fork of JevMail.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

45 Commits

Folders and files

Repository files navigation

LocalMail

License: MIT Model: wildroot-mail-v1

A read-only Gmail reader that sorts your mail with a small model on your own machine. No mail leaves the machine for triage.

LocalMail is a fork of JevMail by fazlerocks. JevMail sends each message to a hosted model; LocalMail replaces that with a local one.

Features

  • Sorts mail into Needs reply, Updates, Promos, Sales and Spam, with reply urgency and a personal-mail flag.
  • An urgent strip for mail that needs action today. Only senders you have written to can mark mail urgent.
  • Read-only: the only Gmail scope is gmail.readonly. Nothing is sent, archived, labelled or marked read. Done marks and corrections stay in a local SQLite file.
  • Runs on CPU with ONNX Runtime. No GPU, no model server, no hosted fallback.
  • Optional, also local: summaries and questions with a small language model, and search by meaning with an embedding model.

Model

Sorting uses wildroot-mail-v1: two bge-small-en-v1.5 models (33M parameters each) fine-tuned for mail triage and exported to float32 ONNX. One answers lane, reply urgency and personal; the other scores whether a message needs action today. Rules the model cannot override sit on top: for example, a sender you have never written to cannot raise urgency above 3. The Wildroot browser uses the same model.

Measure LocalMail Jev 1.14 (hosted)
Lane accuracy, 5 lanes 90.2% 92.4%
Needs reply precision 87.8% 84.8%
Needs reply recall 90.8% 98.3%
Reply urgency, exact 84.4% 83.9%
Personal mail 96.7% 95.2%
Needs action today, AUC 0.965 0.993

546 held-out public emails, enriched for mail that needs a reply or action, so these are not figures for a typical inbox. Jev is the hosted model JevMail uses. Method and limits: docs/BENCHMARK.md.

Each model takes about 40 ms per email on 4 CPU threads. Both together use about 460 MiB of memory and 266 MB of disk.

Quick start

Requires Node.js 22, pnpm 10 and Python 3.12.

git clone https://github.com/wildroot-io/localmail
cd localmail
pnpm install --frozen-lockfile
python3 -m venv .venv
.venv/bin/pip install -r requirements-student.txt

for f in student.onnx action.onnx tokenizer.json vocab.txt; do
  curl -L -o "models/student-v1/$f" "https://huggingface.co/bpmatt/wildroot-mail-v1/resolve/main/$f"
done

cp .env.example .env.local    # then set the Google values below
pnpm build
PYTHON=.venv/bin/python bin/start-local.sh

Open http://localhost:3000. bin/start-local.sh starts the mail service and the app on loopback; Ctrl-C stops both. The service checks each model file against the hash in models/student-v1/config.json.

Google sign-in

  1. In Google Cloud Console, create a project and enable the Gmail API.
  2. Configure the OAuth consent screen as External, in Testing, and add your Gmail address as a test user.
  3. Create an OAuth client of type Web application with the redirect URI http://localhost:3000/api/auth/callback/google.
  4. In .env.local, set AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET, MAILBOX_OWNER_EMAIL (the one account this installation serves) and AUTH_SECRET (for example openssl rand -base64 32).

In Testing mode Google expires refresh tokens after 7 days, so expect to sign in again weekly.

Configuration

.env.example lists the app's settings. THREADS, MAIL_PORT, WORKSPACE and PYTHON are shell variables read by bin/start-local.sh; THREADS defaults to half the logical CPUs.

Variable Default
SYNC_LIMIT 20 Newest messages fetched on first sync, and the cap per later sync
FETCH_MORE_LIMIT 100 Older messages per Fetch more
GMAIL_RATE_PER_MIN 100 Gmail fetch pace
MAX_BODY_CHARS 2000 Characters of each body the model reads
AUTO_SORT 1 0 waits for the Start sorting button

New mail is fetched every five minutes while the page is open. Each new sender costs one read-only Gmail search, to check whether you have written to them.

A correction applies to that message at once and is kept locally. It does not retrain the model.

Limits

  • Gmail sign-in and sync have not yet been run end to end against a real mailbox. All tests use a fake Gmail client.
  • Training and test mail is mostly from 2000 to 2002. Modern newsletters, receipts and automated alerts are lightly covered. English only; text past 256 tokens is ignored.
  • About 1 in 11 messages that needed a reply was missed in testing. Lanes are suggestions: check All.

Development

pnpm dev                     # app only; /preview runs a simulator with no credentials
pnpm test && pnpm lint && pnpm exec tsc --noEmit
pnpm build --webpack         # production build; the default pnpm build uses Turbopack
python3 -m unittest discover -s decision_engine -t . -p 'test_*.py'
python3 -m unittest assistant_runtime.test_server

pnpm sort:reset clears sorting and corrections and keeps messages. pnpm db:reset deletes the local database. Keep data/ out of any repository: it holds your mail.

License

MIT. See LICENSE, which keeps the copyright notice of the original JevMail project. The sorting model is MIT. The search model, EmbeddingGemma 2, is Apache-2.0. The assistant model is your choice; its licence is on its model card.

Acknowledgements

  • JevMail by Fazle Rahman, the app this fork is built on.
  • BAAI/bge-small-en-v1.5, the base model.
  • The Enron, SpamAssassin and phishing_pot email corpora, and public mailing-list archives.

About

A read-only Gmail reader that sorts your mail with a small model on your own machine. Fork of JevMail.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages