From 7564d11931fc4bd5b858a1327a5635d0a2fb6197 Mon Sep 17 00:00:00 2001 From: Bendt Date: Sun, 28 Dec 2025 10:57:19 -0500 Subject: [PATCH] docs: Add notification compression documentation - Update README with feature description - Add configuration section for notification compression - Create demo script showcasing the feature - Document all supported platforms (GitLab, GitHub, Jira, etc.) - Provide usage examples and configuration options --- README.md | 32 +++++ demo_notification_compression.py | 202 +++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100644 demo_notification_compression.py diff --git a/README.md b/README.md index d88b267..a9ab035 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ A CLI tool for syncing Microsoft Outlook email, calendar, and tasks to local fil - **TUI Dashboard**: Interactive terminal dashboard for monitoring sync progress - **Daemon Mode**: Background daemon with proper Unix logging - **Cross-Platform**: Works on macOS, Linux, and Windows +- **Smart Notification Compression**: Automatically detects and compresses transactional notification emails (GitLab, GitHub, Jira, Confluence, Datadog, Renovate) into terminal-friendly summaries ## Quick Start @@ -50,6 +51,37 @@ mkdir -p ~/.local/share/luk Create a configuration file at `~/.config/luk/config.env`: +### Notification Email Compression + +LUK includes intelligent notification email compression to reduce visual noise from automated emails (GitLab, GitHub, Jira, Confluence, Datadog, Renovate). Configure it in `~/.config/luk/mail.toml`: + +```toml +[content_display] +# Enable/disable notification compression +compress_notifications = true + +# Compression mode: +# - "summary": Brief one-page view (default) +# - "detailed": More details in structured format +# - "off": Disable compression, show full emails +notification_compression_mode = "summary" +``` + +**Features:** +- **Automatic detection**: Identifies notification emails by sender domain and subject patterns +- **Type-specific summaries**: Extracts relevant info per platform (pipeline IDs, PR numbers, etc.) +- **Terminal-friendly formatting**: Clean markdown with icons and clear hierarchy +- **Toggle support**: Press `m` in mail view to switch between compressed and full email + +**Demo:** +```bash +python demo_notification_compression.py +``` + +See `mail.toml.example` for full configuration options. + +### General Configuration + ```bash # Microsoft Graph settings MICROSOFT_CLIENT_ID=your_client_id diff --git a/demo_notification_compression.py b/demo_notification_compression.py new file mode 100644 index 0000000..61f2daf --- /dev/null +++ b/demo_notification_compression.py @@ -0,0 +1,202 @@ +#!/usr/bin/env python3 +""" +Demo script for notification email compression. + +This script demonstrates how notification emails are detected and compressed +into terminal-friendly summaries. +""" + +from src.mail.notification_detector import ( + is_notification_email, + classify_notification, + extract_notification_summary, + NOTIFICATION_TYPES, +) +from src.mail.notification_compressor import NotificationCompressor, DetailedCompressor + + +def demo_detection(): + """Demonstrate notification detection for various email types.""" + + test_emails = [ + { + "from": {"addr": "notifications@gitlab.com", "name": "GitLab"}, + "subject": "Pipeline #12345 failed by john.doe", + }, + { + "from": {"addr": "noreply@github.com", "name": "GitHub"}, + "subject": "[GitHub] PR #42: Add new feature", + }, + { + "from": {"addr": "jira@atlassian.net", "name": "Jira"}, + "subject": "[Jira] ABC-123: Fix login bug", + }, + { + "from": {"addr": "confluence@atlassian.net", "name": "Confluence"}, + "subject": "[Confluence] New comment on page", + }, + { + "from": {"addr": "alerts@datadoghq.com", "name": "Datadog"}, + "subject": "[Datadog] Alert: High CPU usage", + }, + { + "from": {"addr": "renovate@renovatebot.com", "name": "Renovate"}, + "subject": "[Renovate] Update dependency to v2.0.0", + }, + { + "from": {"addr": "john.doe@example.com", "name": "John Doe"}, + "subject": "Let's meet for lunch", + }, + ] + + print("=" * 70) + print("NOTIFICATION DETECTION DEMO") + print("=" * 70) + print() + + for i, envelope in enumerate(test_emails, 1): + from_addr = envelope.get("from", {}).get("addr", "") + subject = envelope.get("subject", "") + + print(f"Email {i}: {subject}") + print(f" From: {from_addr}") + + # Check if notification + is_notif = is_notification_email(envelope) + print(f" Is Notification: {is_notif}") + + if is_notif: + notif_type = classify_notification(envelope) + if notif_type: + print(f" Type: {notif_type.name}") + print(f" Icon: {notif_type.icon}") + + print() + + +def demo_compression(): + """Demonstrate notification compression.""" + + # GitLab pipeline email content (simplified) + gitlab_content = """ + Pipeline #12345 failed by john.doe + + The pipeline failed on stage: build + Commit: abc123def + + View pipeline: https://gitlab.com/project/pipelines/12345 + """ + + # GitHub PR email content (simplified) + github_content = """ + PR #42: Add new feature + + @john.doe requested your review + + View PR: https://github.com/repo/pull/42 + """ + + gitlab_envelope = { + "from": {"addr": "notifications@gitlab.com", "name": "GitLab"}, + "subject": "Pipeline #12345 failed", + "date": "2025-12-28T15:00:00Z", + } + + github_envelope = { + "from": {"addr": "noreply@github.com", "name": "GitHub"}, + "subject": "[GitHub] PR #42: Add new feature", + "date": "2025-12-28T15:00:00Z", + } + + print("=" * 70) + print("NOTIFICATION COMPRESSION DEMO") + print("=" * 70) + print() + + # GitLab compression - summary mode + print("1. GitLab Pipeline (Summary Mode)") + print("-" * 70) + compressor = NotificationCompressor(mode="summary") + compressed, notif_type = compressor.compress(gitlab_content, gitlab_envelope) + print(compressed) + print() + + # GitLab compression - detailed mode + print("2. GitLab Pipeline (Detailed Mode)") + print("-" * 70) + detailed_compressor = DetailedCompressor(mode="detailed") + compressed, notif_type = detailed_compressor.compress( + gitlab_content, gitlab_envelope + ) + print(compressed) + print() + + # GitHub PR - summary mode + print("3. GitHub PR (Summary Mode)") + print("-" * 70) + compressor = NotificationCompressor(mode="summary") + compressed, notif_type = compressor.compress(github_content, github_envelope) + print(compressed) + print() + + +def demo_summary_extraction(): + """Demonstrate structured summary extraction.""" + + test_content = """ + ABC-123: Fix login bug + + Status changed from In Progress to Done + + View issue: https://jira.atlassian.net/browse/ABC-123 + """ + + print("=" * 70) + print("SUMMARY EXTRACTION DEMO") + print("=" * 70) + print() + + notif_type = NOTIFICATION_TYPES[2] # jira + summary = extract_notification_summary(test_content, notif_type) + + print("Extracted Summary:") + print(f" Title: {summary.get('title')}") + print(f" Metadata: {summary.get('metadata')}") + print(f" Action Items: {summary.get('action_items')}") + print() + + +def main(): + """Run all demos.""" + + print() + print("╔" + "═" * 68 + "╗") + print("║" + " " * 68 + "║") + print("║" + " LUK Notification Email Compression - Feature Demo".center(68) + "║") + print("║" + " " * 68 + "║") + print("╚" + "═" * 68 + "╝") + print() + + # Run demos + demo_detection() + print() + demo_compression() + print() + demo_summary_extraction() + + print() + print("=" * 70) + print("DEMO COMPLETE") + print("=" * 70) + print() + print("The notification compression feature is now integrated into the mail app.") + print("Configure it in ~/.config/luk/mail.toml:") + print() + print(" [content_display]") + print(" compress_notifications = true") + print(" notification_compression_mode = 'summary' # or 'detailed' or 'off'") + print() + + +if __name__ == "__main__": + main()