{"id":30770008,"url":"https://github.com/copyleftdev/mailsentinel","last_synced_at":"2026-04-14T00:02:39.423Z","repository":{"id":310319144,"uuid":"1039437026","full_name":"copyleftdev/mailsentinel","owner":"copyleftdev","description":"AI-powered Gmail classification system using local Ollama LLM inference. Privacy-first email triage with modular YAML profiles, cryptographic audit trails, and enterprise-grade security.","archived":false,"fork":false,"pushed_at":"2025-08-17T08:37:48.000Z","size":1447,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-17T10:19:37.491Z","etag":null,"topics":["ai","audit-logging","automation","circuit-breaker","email-automation","email-classification","email-filtering","gmail","gmail-api","golang","llm","local-ai","machine-learning","oauth","ollama","privacy","productivity","security","triage","yaml"],"latest_commit_sha":null,"homepage":"https://mailsentinal.vercel.app/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/copyleftdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-17T08:16:31.000Z","updated_at":"2025-08-17T08:37:51.000Z","dependencies_parsed_at":"2025-08-17T10:19:39.711Z","dependency_job_id":"ae51aacf-0466-4c36-a448-12c301082b1a","html_url":"https://github.com/copyleftdev/mailsentinel","commit_stats":null,"previous_names":["copyleftdev/mailsentinel"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/copyleftdev/mailsentinel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmailsentinel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmailsentinel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmailsentinel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmailsentinel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/copyleftdev","download_url":"https://codeload.github.com/copyleftdev/mailsentinel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmailsentinel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273685604,"owners_count":25149722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","audit-logging","automation","circuit-breaker","email-automation","email-classification","email-filtering","gmail","gmail-api","golang","llm","local-ai","machine-learning","oauth","ollama","privacy","productivity","security","triage","yaml"],"created_at":"2025-09-04T23:02:58.324Z","updated_at":"2026-04-14T00:02:39.376Z","avatar_url":"https://github.com/copyleftdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MailSentinel\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"media/MSLOGO.png\" alt=\"MailSentinel Logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\nMailSentinel is a Gmail triage system that uses local Ollama LLM inference to automatically classify and organize emails based on configurable profiles. It provides privacy-first email processing with comprehensive audit trails and policy-driven decision making.\n\n## Development Story\n\nThis project was developed through a collaborative human-AI pair programming session. The human provided strategic guidance, requirements, and context while the AI (Cascade) implemented the technical solution.\n\n**Development Timeline**: August 16-17, 2025 (approximately 4 hours)\n- **Started**: 2025-08-16 ~21:00 PST  \n- **Completed**: 2025-08-17 01:01 PST\n- **Total Duration**: ~4 hours of intensive development\n\n**What Was Built**:\n- Complete Gmail OAuth integration with secure token management\n- Local Ollama LLM client with circuit breaker patterns\n- Modular YAML profile system with inheritance\n- Comprehensive audit logging with cryptographic integrity\n- Production-ready CLI with dry-run safety features\n- Full test suite with benchmarks and integration tests\n- 8 different email classification profiles\n- Enterprise-grade security and monitoring\n\n**Human Contributions**:\n- Strategic direction and requirements definition\n- Architecture decisions and security considerations  \n- Profile design and classification logic\n- Testing strategy and validation approach\n- Production deployment guidance\n\n**AI Contributions**:\n- Complete codebase implementation (~2000+ lines of Go)\n- OAuth flow and Gmail API integration\n- Cryptographic audit system design\n- Circuit breaker and resilience patterns\n- Comprehensive error handling and logging\n- Test suite and benchmarking framework\n- Documentation and deployment scripts\n\n**Final Result**: A production-ready email classification system that successfully processed 25+ real Gmail emails across 5 different profiles with 100% success rate and zero errors.\n\n## Features\n\n- **Local LLM Processing**: All inference via local Ollama - zero cloud calls\n- **Profile-Driven Classification**: Modular YAML profiles with inheritance and dependencies  \n- **Policy Resolution**: Advanced conflict resolution with priority rules and confidence weighting\n- **Enterprise Security**: Encrypted storage, audit trails with integrity verification\n- **Circuit Breaker Patterns**: Resilient handling of external dependencies\n- **Batch Processing**: Efficient processing with configurable concurrency\n- **Dry-Run Mode**: Safe testing without modifying emails\n\n## Quick Start\n\n### Prerequisites\n\n1. **Go 1.21+** - [Download](https://golang.org/dl/)\n2. **Ollama** - [Install](https://ollama.ai/) and pull `qwen2.5:7b` model\n3. **Gmail API Credentials** - [Setup Guide](https://developers.google.com/gmail/api/quickstart/go)\n\n### Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/mailsentinel/core.git\ncd core\n\n# Install dependencies\ngo mod tidy\n\n# Copy environment template\ncp env.example .env\n# Edit .env with your Gmail credentials\n\n# Create data directories\nmkdir -p data/audit profiles\n\n# Build binary\ngo build -o bin/mailsentinel cmd/mailsentinel/main.go\n```\n\n### Configuration\n\n1. **Gmail OAuth Setup**:\n   - Go to [Google Cloud Console](https://console.cloud.google.com/)\n   - Create project and enable Gmail API\n   - Create OAuth 2.0 credentials (Desktop application)\n   - Add credentials to `.env` file\n\n2. **Ollama Setup**:\n   ```bash\n   # Install and start Ollama\n   ollama serve\n   \n   # Pull required model\n   ollama pull qwen2.5:7b\n   ```\n\n### Usage\n\n```bash\n# Run in dry-run mode (safe, no email modifications)\n./bin/mailsentinel -dry-run -query \"is:unread\" -max-emails 10\n\n# Process with specific profile\n./bin/mailsentinel -dry-run -profile spam -query \"is:unread\"\n\n# Apply changes (removes dry-run protection)\n./bin/mailsentinel -query \"is:unread\" -max-emails 100\n\n# Verbose logging\n./bin/mailsentinel -verbose -dry-run\n```\n\n## Architecture\n\n```\ncmd/mailsentinel/     # CLI application entry point\ninternal/\n├── gmail/           # Gmail API client with OAuth\n├── ollama/          # Ollama client with circuit breaker  \n├── profile/         # Profile loading and dependency resolution\n├── resolver/        # Policy conflict resolution\n└── audit/           # Secure audit logging\npkg/\n├── types/           # Core data structures\n└── config/          # Configuration management\nprofiles/            # YAML classification profiles\ndata/               # Runtime data (tokens, audit logs)\n```\n\n## Profile System\n\nProfiles define email classification behavior using YAML:\n\n```yaml\nid: \"spam\"\nversion: \"1.0.0\"\nmodel: \"qwen2.5:7b\"\nsystem: \"You are an expert spam classifier...\"\nfewshot:\n  - name: \"phishing_example\"\n    input: \"Suspicious email content...\"\n    output: '{\"action\": \"delete\", \"confidence\": 0.95}'\npolicy:\n  conditions:\n    - name: \"high_risk\"\n      expression: \"metadata.phishing_score \u003e= 0.8\"\n      actions: [\"delete\"]\n```\n\n### Profile Features\n\n- **Inheritance**: `inherits_from: base_profile`\n- **Dependencies**: `depends_on: [other_profiles]`\n- **Conditional Execution**: `when: \"expression\"`\n- **Few-Shot Learning**: Training examples for better accuracy\n- **Policy Rules**: Confidence thresholds and action mapping\n\n## Security\n\n- **Local-Only Processing**: No external LLM calls\n- **Encrypted Storage**: AES-256 for OAuth tokens and sensitive data\n- **Audit Integrity**: SHA-256 checksums and cryptographic signatures\n- **Input Sanitization**: Protection against prompt injection\n- **Resource Limits**: DoS protection and memory constraints\n\n## Monitoring\n\nMailSentinel provides comprehensive observability:\n\n- **Structured Logging**: JSON format with correlation IDs\n- **Performance Metrics**: Latency, throughput, memory usage\n- **Circuit Breaker Status**: External dependency health\n- **Audit Trail**: Immutable log of all decisions\n\n## Development\n\n### Running Tests\n\n```bash\n# Unit tests\ngo test ./...\n\n# With coverage\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n\n# Race detection\ngo test -race ./...\n```\n\n### Using Workflows\n\nMailSentinel includes Windsurf workflows for common tasks:\n\n```bash\n# Setup development environment\n/setup-development\n\n# Create new profile\n/develop-profile\n\n# Run full test suite\n/run-tests\n\n# Security review\n/security-review\n\n# Deploy to production\n/deploy-production\n```\n\n### Project Structure\n\n- `.windsurf/rules/` - Development guidelines and standards\n- `.windsurf/workflows/` - Automated development processes\n- `testdata/` - Test fixtures and golden files\n- `profiles/` - Email classification profiles\n\n## Configuration Reference\n\nSee `config.yaml` for full configuration options and `docs/spec.md` for detailed technical specifications:\n\n- **Gmail**: OAuth, rate limiting, batch sizes\n- **Ollama**: Models, timeouts, circuit breaker settings  \n- **Profiles**: Directory, reload intervals, validation\n- **Audit**: Logging, rotation, integrity checks\n- **Security**: Encryption, input validation, resource limits\n\n## Performance Targets\n\n- **Single Email**: p95 ≤ 1.5s processing time\n- **Batch Processing**: 100 emails in ≤ 30s\n- **Memory Usage**: ≤ 512MB for 1000 email batch\n- **Uptime**: 99.9% for scheduled operations\n\n## Contributing\n\n1. Follow the development rules in `.windsurf/rules/`\n2. Use workflows for consistent processes\n3. Maintain 80%+ test coverage\n4. Security review required for all changes\n\n## License\n\nMIT License - See LICENSE file for details.\n\n## Author\n\n**copyleftdev** - Email classification system architect and developer  \nContact: dj@codetestcode.io\n\n## Support\n\n- Documentation: `docs/spec.md`\n- Issues: GitHub Issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcopyleftdev%2Fmailsentinel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcopyleftdev%2Fmailsentinel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcopyleftdev%2Fmailsentinel/lists"}