Metadata-Version: 2.4
Name: draftpilot
Version: 0.1.0
Summary: Dead man's switch email outreach with AI personalization
Project-URL: Homepage, https://github.com/Alae-J/draftpilot
Project-URL: Repository, https://github.com/Alae-J/draftpilot
Project-URL: Issues, https://github.com/Alae-J/draftpilot/issues
Author: Alae Eddine Jahid
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,automation,cold-email,drafts,email,gmail,outreach
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: dnspython>=2.4.0
Requires-Dist: email-validator>=2.0.0
Requires-Dist: google-api-python-client>=2.100.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# DraftPilot

**AI writes Gmail drafts. You review. Undeleted drafts auto-send.**

Most AI email tools send for you or wait for you to click Send. DraftPilot does neither: it drafts to Gmail, you review, and if you don't delete it, it fires automatically after 6 hours. Human judgment, zero manual effort.

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)

---

## How It Works

```
1. You provide a CSV of companies + a YAML profile with your info
2. DraftPilot generates personalized emails via LLM
3. Drafts appear in Gmail under a labeled folder
4. You review - delete the bad ones, leave the good ones
5. After 6 hours - undeleted drafts auto-send (the dead man's switch)
```

```
CSV + Profile --> LLM generates email --> Gmail draft created
                                              |
                                    You review in Gmail
                                        /           \
                                 Delete it        Leave it
                                    |                |
                              Cancelled         Auto-sends
                                              after 6 hours
```

---

## Features

- **Dead man's switch** - Drafts auto-send after a configurable delay. Delete to cancel, ignore to approve.
- **AI personalization** - Uses any OpenAI-compatible LLM (Cerebras, Groq, OpenAI) to write emails tailored to each company
- **30+ anti-cliche rules** - A rules engine that prevents "I hope this finds you well", "passionate", and other template-sounding phrases
- **Multi-source email finder** - Scrapes job boards, company websites, and Hunter.io to find real recruitment emails
- **MX validation** - Checks if email domains actually accept mail before sending
- **Full audit trail** - SQLite database tracks every email: pending, drafted, sent, cancelled, error
- **HTML emails** - Clickable links for portfolio and CV in the signature
- **Bilingual** - Generates emails in French or English based on company language
- **Rate limiting** - Smart backoff and retry logic for LLM APIs
- **Cron-ready** - Set it up once and it runs daily

---

## Quick Start

### Install

```bash
pip install draftpilot
```

Or from source:

```bash
git clone https://github.com/Alae-J/draftpilot.git
cd draftpilot
pip install -e .
```

### Configure

```bash
# Copy example configs
mkdir -p config
cp examples/profile.yaml config/
cp examples/templates.yaml config/

# Edit with your info
nano config/profile.yaml

# Set your LLM API key
export CEREBRAS_API_KEY="your-key-here"
```

### Authenticate with Gmail

```bash
draftpilot auth
```

This opens a browser for Google OAuth. You need a Google Cloud project with Gmail API enabled. [Setup guide](#gmail-setup).

### Run

```bash
# Generate drafts from a company list
draftpilot draft --csv companies.csv --batch 20

# Check your Gmail - review the drafts under the "DraftPilot" label
# Delete any you don't like

# Trigger the dead man's switch (or let cron do it)
draftpilot send

# Check stats
draftpilot status --list
```

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `draftpilot draft` | Generate personalized email drafts |
| `draftpilot send` | Auto-send drafts past their validation window |
| `draftpilot status` | Display pipeline statistics |
| `draftpilot find` | Find recruitment emails via web scraping |
| `draftpilot validate` | Validate emails (syntax + MX check) |
| `draftpilot auth` | Gmail OAuth setup |

### Draft options

```bash
draftpilot draft --csv companies.csv   # company list
draftpilot draft --batch 30            # emails per run (default: 50)
draftpilot draft --delay 12            # hours before auto-send (default: 6)
draftpilot draft --dry-run             # generate without creating drafts
```

### Find emails

```bash
# Input: CSV with company_name and website columns
# Output: CSV with company_name, email, website, description, language, sector
draftpilot find --csv company_names.csv
draftpilot find --csv company_names.csv --no-hunter  # skip Hunter.io
draftpilot find --csv company_names.csv --no-llm     # skip LLM descriptions
```

---

## Configuration

### Profile (`config/profile.yaml`)

Your personal info, skills, experience, and preferences. See [examples/profile.yaml](examples/profile.yaml) for the full template.

Key sections:

```yaml
name: "Your Name"
email: "you@gmail.com"
phone: "+1 234 567 8900"
portfolio: "https://your-site.com"

education:
  school: "Your University"
  school_short: "University"    # used in subject lines

experience:
  - name: "Project X"
    role: "Developer"
    description: "What you built"
    tech: "Python, React"

# LLM provider (any OpenAI-compatible API)
llm:
  base_url: "https://api.cerebras.ai/v1"
  model: "qwen-3-235b-a22b-instruct-2507"
  api_key_env: "CEREBRAS_API_KEY"

# Email signature (uses $variable substitution)
signature:
  fr: "$name | $school_short\n$phone | <a href=\"$portfolio\">Portfolio</a>"
  en: "$name | $school_short\n$phone | <a href=\"$portfolio\">Portfolio</a>"
```

### Templates (`config/templates.yaml`)

Controls the email structure and rules. Ships with French and English templates. See [examples/templates.yaml](examples/templates.yaml).

The rules engine enforces:
- Greeting on its own line
- Company-first opening (not self-introduction)
- No cliches ("I hope this finds you well", "passionate", etc.)
- Word limit (150 words max)
- Proper accent marks in French
- Call-to-action with specific days
- And 20+ more rules

### LLM Providers

DraftPilot works with any OpenAI-compatible API:

| Provider | Free Tier | Model |
|----------|-----------|-------|
| [Cerebras](https://cerebras.ai) | 14,400 req/day, 1M tokens/day | Qwen 235B |
| [Groq](https://groq.com) | 1,000 req/day, 100K tokens/day | Llama 3.3 70B |
| [OpenAI](https://openai.com) | Pay per use | GPT-4o |
| [Together](https://together.ai) | Free tier available | Llama 3.3 70B |

Just change `llm.base_url` and `llm.model` in your profile.

---

## Gmail Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create a project and enable the **Gmail API**
3. Go to **APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client ID**
4. Select **Desktop app**, download the JSON
5. Save as `config/credentials.json`
6. Add yourself as a test user under **OAuth consent screen > Test users**
7. Run `draftpilot auth`

---

## Cron Setup (Automated Daily Runs)

```bash
# Edit crontab
crontab -e

# Add these lines:
CEREBRAS_API_KEY=your-key-here

# Generate drafts every day at 8am
0 8 * * * cd /path/to/project && /path/to/venv/bin/draftpilot draft >> logs/generate.log 2>&1

# Check and send every 30 minutes
*/30 * * * * cd /path/to/project && /path/to/venv/bin/draftpilot send >> logs/send.log 2>&1
```

---

## Email Finder Pipeline

DraftPilot includes a multi-source email finder that scrapes real email addresses:

1. **Rekrute.com** - Morocco's largest job board (extracts emails from job postings)
2. **Company websites** - Scrapes /contact, /careers, /recrutement pages for mailto: links
3. **Hunter.io API** - Domain-based email search (50 free credits/month)
4. **MX validation** - Filters out domains that don't accept email

```bash
# Input: just company names and websites
echo "company_name,website
TechCorp,https://techcorp.com
StartupX,https://startupx.ma" > targets.csv

# Find their emails
draftpilot find --csv targets.csv

# Output: targets_found.csv with email, description, language, sector
```

---

## Responsible Use

This tool is designed for **targeted, relevant, professional outreach** - not bulk spam.

By using this tool, you agree to:
- Comply with CAN-SPAM, GDPR, CASL, and your local email laws
- Only email addresses where you have a legitimate professional basis
- Include opt-out mechanisms in all sent emails
- Honor opt-out requests immediately
- Not use this tool to send unsolicited bulk commercial email

The authors are not responsible for misuse. Email scraping and cold outreach may be regulated or restricted in your jurisdiction.

---

## Project Structure

```
draftpilot/
├── src/draftpilot/
│   ├── cli.py          # Typer CLI with 6 subcommands
│   ├── config.py       # Config loading, LLM client, signature rendering
│   ├── generator.py    # LLM email generation + post-processing
│   ├── drafts.py       # Phase 1: CSV -> LLM -> Gmail drafts
│   ├── sender.py       # Phase 2: Dead man's switch auto-sender
│   ├── gmail.py        # Gmail API wrapper
│   ├── db.py           # SQLite state tracking
│   ├── finder.py       # Multi-source email discovery
│   ├── validator.py    # Email syntax + MX validation
│   └── dashboard.py    # Rich terminal stats display
├── config/
│   ├── profile.yaml    # Your info (not committed)
│   └── templates.yaml  # Email templates + rules
├── examples/           # Example configs to copy
├── tests/
├── pyproject.toml
└── LICENSE             # Apache 2.0
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.

---

## License

Apache 2.0 - See [LICENSE](LICENSE) for details.
