153 lines
3.5 KiB
Markdown
153 lines
3.5 KiB
Markdown
# Mail Agent
|
|
|
|
IMAP-based email triage with multi-tier escalation.
|
|
|
|
## Overview
|
|
|
|
Mail Agent monitors IMAP accounts for new mail and automatically triages messages:
|
|
|
|
- **L1 (Cheap Model):** Fast classification using Fireworks llama-v3p1-8b
|
|
- Spam → delete
|
|
- Newsletter/receipt → archive
|
|
- Shipping → dashboard + archive
|
|
- Uncertain → escalate to L2
|
|
|
|
- **L2 (James/Opus):** Review via Clawdbot Gateway
|
|
- Full context review
|
|
- Can draft replies or escalate
|
|
|
|
- **L3 (Johan):** Signal notification
|
|
- Important stuff only
|
|
- Human decision required
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Set environment variables
|
|
export FIREWORKS_API_KEY=your-api-key
|
|
export PROTON_BRIDGE_PASSWORD=BlcMCKtNDfqv0cq1LmGR9g
|
|
|
|
# Run
|
|
python -m src.main
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Edit `config.yaml`:
|
|
|
|
```yaml
|
|
server:
|
|
host: 127.0.0.1
|
|
port: 8025
|
|
|
|
accounts:
|
|
proton:
|
|
host: 127.0.0.1
|
|
port: 1143
|
|
username: tj@jongsma.me
|
|
password: ${PROTON_BRIDGE_PASSWORD}
|
|
tls: starttls
|
|
folders:
|
|
watch: [INBOX]
|
|
archive: Archive
|
|
|
|
triage:
|
|
enabled: true
|
|
l1:
|
|
provider: fireworks
|
|
model: accounts/fireworks/models/llama-v3p1-8b-instruct
|
|
api_key: ${FIREWORKS_API_KEY}
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Accounts
|
|
- `GET /accounts` - List all configured accounts
|
|
- `GET /accounts/{id}` - Get account details
|
|
- `GET /accounts/{id}/mailboxes` - List folders
|
|
|
|
### Messages
|
|
- `GET /accounts/{id}/messages?folder=INBOX&unread=true` - List messages
|
|
- `GET /accounts/{id}/messages/{uid}?folder=INBOX` - Get full message
|
|
- `PATCH /accounts/{id}/messages/{uid}` - Update flags/move
|
|
- `DELETE /accounts/{id}/messages/{uid}` - Delete message
|
|
|
|
### Events (SSE)
|
|
- `GET /accounts/{id}/events?folder=INBOX` - Subscribe to new mail events
|
|
|
|
## Systemd Service
|
|
|
|
```bash
|
|
# Copy service file
|
|
cp systemd/mail-agent.service ~/.config/systemd/user/
|
|
|
|
# Edit to add FIREWORKS_API_KEY
|
|
systemctl --user edit mail-agent.service
|
|
|
|
# Enable and start
|
|
systemctl --user enable mail-agent
|
|
systemctl --user start mail-agent
|
|
|
|
# Check status
|
|
systemctl --user status mail-agent
|
|
journalctl --user -u mail-agent -f
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
New Mail (IMAP IDLE)
|
|
│
|
|
▼
|
|
┌─────────────────────┐
|
|
│ L1: Cheap Model │ ~$0.20/1M tokens
|
|
│ Fast classification│
|
|
└─────────────────────┘
|
|
│
|
|
▼ (uncertain/important)
|
|
┌─────────────────────┐
|
|
│ L2: James (Opus) │ via Gateway
|
|
│ Context review │
|
|
└─────────────────────┘
|
|
│
|
|
▼ (needs human)
|
|
┌─────────────────────┐
|
|
│ L3: Johan │ Signal notification
|
|
└─────────────────────┘
|
|
```
|
|
|
|
## Shipping Dashboard
|
|
|
|
Shipping notifications are automatically posted to the James Dashboard:
|
|
|
|
```
|
|
POST http://100.123.216.65:9200/api/news
|
|
{
|
|
"title": "📦 E3-1275 Server",
|
|
"body": "Picked up by UPS. Expected Feb 3rd.",
|
|
"type": "info",
|
|
"source": "shipping"
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run with auto-reload
|
|
uvicorn src.main:app --reload --host 127.0.0.1 --port 8025
|
|
|
|
# Test IMAP connection
|
|
python -c "from src.imap import ImapClient; from src.config import get_config; c=get_config(); client=ImapClient('proton', c.accounts['proton']); client.connect(); print(client.list_mailboxes())"
|
|
```
|
|
|
|
## License
|
|
|
|
Proprietary - Johan Jongsma
|