mail_summariser

mail_summariser is a local-first email situational-awareness system with a FastAPI backend and a browser client. The macOS SwiftUI client remains in the repository, but macOS app deployment is paused while the browser workflow is hardened for daily use.

It supports:

• a resettable sample mailbox for local onboarding and fast validation
• live multi-account IMAP/SMTP mode for real inbox workflows
• local mail indexing, saved scopes, and a triage dashboard
• preview-first bulk actions for marking mail read, tagging it, and archiving it
• safe mode by default, per-action dry runs, and undo for supported mailbox mutations
• provider-backed summaries via Ollama, OpenAI, or Anthropic
• deterministic fallback summaries when providers are unavailable or return invalid output

Project layout

• backend/: FastAPI app, mail services, provider integration, SQLite persistence
• webapp/: static browser UI (index.html, app.js, api.js)
• macos-app/: SwiftUI desktop client source; deployment is currently paused
• tests/: pytest suite for backend behavior and integration boundaries
• scripts/: build, release packaging, hygiene checks, and full-stack validation

Quick start

Homebrew (macOS)

brew tap krahd/tap
brew install mail-summariser
mail_summariser

This installs the pre-built backend binary. Serve the webapp/ folder separately (see Web app below).

Current product decision: use the backend plus browser client for now. macOS app deployment, notarisation, and end-user distribution are paused until the browser workflow has passed real-account acceptance testing.

Backend

./start_backend.sh

Backend defaults to http://127.0.0.1:8766.

Web app

Serve the webapp/ folder with any static server, for example:

python -m http.server 8000 --directory webapp

Tests

Install the contributor dependencies first:

python3 -m pip install -e . -r dev-requirements.txt

pytest -q

Full-stack validation

./scripts/validate_full_stack.sh

Cross-platform equivalent:

python scripts/validate_full_stack.py

CI runs startup validation in a matrix on Linux, macOS, and Windows.

Rendered UI regression

Install the Playwright browser once, then run the rendered browser smoke test:

python -m playwright install chromium
python scripts/validate_rendered_ui.py

This starts isolated backend and static-web instances, verifies the sample mailbox first-run flow, empty-result handling, settings/live-mode toggle, and a mobile layout check. Screenshots are written under the system temp directory.

Repository hygiene guard

./scripts/check_repo_hygiene.sh

Configuration notes

• Runtime settings are persisted in SQLite (backend/data/mail_summariser.sqlite3 by default).
• The backend setting is still named dummyMode for API compatibility, but user-facing clients present it as the sample mailbox.
• safeMode defaults to on. Bulk actions preview and log dry runs until safe mode is disabled explicitly.
• Archive is implemented as an IMAP folder move and requires server support for both MOVE and UIDPLUS so undo can identify the moved message.
• Secrets are masked on reads from /settings.
• Writing masked sentinel values (__MASKED__) does not overwrite stored secrets.

Dependency note

The project depends on the external modelito package for LLM helper utilities.

Licence

MIT. See LICENSE.

Contributing

Contributions are welcome. Open an issue to discuss significant changes before submitting a pull request. Please keep changes focused, ensure pytest -q passes, and update STATUS.md when behaviour changes.

Disclaimer

This software is provided as-is, without warranty of any kind, express or implied. Use at your own risk. The authors accept no liability for data loss, mailbox corruption, unintended message actions, or any other damages arising from its use. Live IMAP/SMTP mode operates on real mailboxes — review configuration carefully before enabling it.