Metadata-Version: 2.4
Name: morning-brief
Version: 0.3.0
Summary: Rule-based daily Gmail inbox triage. Zero LLM, read-only, Windows-friendly.
Project-URL: Homepage, https://github.com/Pawansingh3889/morning-brief
Project-URL: Repository, https://github.com/Pawansingh3889/morning-brief
Project-URL: Issues, https://github.com/Pawansingh3889/morning-brief/issues
Author-email: Pawansingh3889 <pawankapkoti3889@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cli,digest,gmail,inbox,productivity,triage
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: google-api-python-client>=2.100
Requires-Dist: google-auth-oauthlib>=1.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: windows
Requires-Dist: winotify>=1.1; (sys_platform == 'win32') and extra == 'windows'
Description-Content-Type: text/markdown

# morning-brief

[![PyPI](https://img.shields.io/pypi/v/morning-brief)](https://pypi.org/project/morning-brief/)
[![Python](https://img.shields.io/pypi/pyversions/morning-brief)](https://pypi.org/project/morning-brief/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![codecov](https://codecov.io/gh/Pawansingh3889/morning-brief/branch/main/graph/badge.svg)](https://codecov.io/gh/Pawansingh3889/morning-brief)

Rule-based daily Gmail inbox triage. Zero LLM, read-only, Windows-friendly.

Classifies recent mail into HIGH / MEDIUM / LOW / SPAM from a YAML rules file, writes a markdown digest, and pops a desktop toast. Scan your inbox in thirty seconds instead of thirty minutes.

## Why not an LLM-based tool

Paid-LLM triage tools like [mailtrim](https://github.com/sadhgurutech/mailtrim) and [gmail-digest](https://github.com/iloveitaly/gmail-digest) work, but cost money per run and fail silently when the API is down. For a personal inbox, most of the signal lives in sender domain plus a handful of subject keywords. Rules handle that case reliably and for free.

## Install

```
pip install morning-brief
```

Windows users also want the toast helper:

```
pip install "morning-brief[windows]"
```

## One-time setup

1. Create a Google Cloud project, enable the Gmail API, create an OAuth 2.0 Client ID of type **Desktop app**, and download the JSON as `credentials.json`.
2. Run `morning-brief init` to scaffold `~/.morning-brief/`.
3. Drop `credentials.json` into `~/.morning-brief/`.
4. Edit `~/.morning-brief/rules.yaml` to match your senders.
5. Run `morning-brief run`. First run opens your browser for read-only consent and writes `token.json` locally.

## Sub-day windows

```
morning-brief run --hours 4    # last four hours instead of last day
morning-brief run --hours 1    # quick post-lunch sweep
```

`--hours` overrides the default `--days 1`. Maps directly to Gmail's `newer_than:Nh` query.

## Thread collapse

Conversations that fan out across many messages collapse to one digest entry annotated with `(N msgs)`. On by default; pass `--no-collapse-threads` to keep the v0.2.0 one-line-per-message behaviour.

## Debug your rules

```
morning-brief preview --sender "hr@canonical.com" --subject "Interview Tuesday"
# Bucket: HIGH
# Reason: high_sender:@canonical.com

morning-brief why <message-id>
# From:    notifications@github.com
# Subject: Review requested on PR #42
# Stored:  HIGH
# Now:     HIGH
# Reason:  high_keyword:review requested
```

`preview` answers "what would happen if I added this rule?" without calling Gmail. `why` looks up a stored message and shows whether your current `rules.yaml` would still classify it the same way.

## Daily run

Windows Task Scheduler, WSL cron, or macOS launchd can each fire the command once a day at 8am.

Windows Task Scheduler: create a basic task triggered daily at 08:00 running `morning-brief run`.

WSL cron:

```
0 8 * * * /home/you/.local/bin/morning-brief run >> /tmp/morning-brief.log 2>&1
```

For toast notifications from WSL cron, install [wsl-notify-send](https://github.com/stuartleeks/wsl-notify-send); morning-brief will pick it up automatically.

## Rules

`rules.yaml` uses case-insensitive substring matching. The starter generated by `morning-brief init` covers GitHub notifications, common spam patterns, and a placeholder high-priority sender list.

Classification precedence: spam wins first, then high, then github-low, then medium (default).

## Scope

- Read-only Gmail access. The tool never marks, labels, moves, or deletes mail.
- Writes digests to `~/.morning-brief/digests/YYYY-MM-DD.md`.
- Tracks processed message IDs locally for 7 days so reruns are idempotent.

## Status

Alpha. Classifier is covered by unit tests; integration tests for the Gmail client come next.

## License

MIT.
