Metadata-Version: 2.4
Name: calwash
Version: 0.3.0
Summary: Redact sensitive data from your calendar events
Author-email: Samuel Ahuno <ekwame001@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/sahuno/calwash
Project-URL: Issues, https://github.com/sahuno/calwash/issues
Keywords: calendar,privacy,redaction,google-calendar,pii,sensitive-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-api-python-client>=2.179.0
Requires-Dist: google-auth-oauthlib>=1.2.2
Provides-Extra: caldav
Requires-Dist: caldav>=1.3; extra == "caldav"
Requires-Dist: icalendar>=5.0; extra == "caldav"
Dynamic: license-file

# calwash

Redact sensitive data from your calendar events. Detect and remove PII (phone numbers, emails, SSNs, credit cards), medical terms, legal references, and more — with optional local AI detection that never sends your data to the cloud.

## Install

```bash
pipx install calwash
```

Or with pip:

```bash
pip install calwash
```

## Quick Start

```bash
# 1. Log in to your Google account (opens browser)
calwash login

# 2. Preview what would be redacted
calwash clean --dry-run

# 3. Apply redactions (creates backup first)
calwash clean
```

## What It Detects

**Regex (always on):**

| Pattern | Example | Replaced with |
|---|---|---|
| Email addresses | `john@example.com` | `[EMAIL REMOVED]` |
| Phone numbers | `555-123-4567` | `[PHONE REMOVED]` |
| Social Security Numbers | `123-45-6789` | `[SSN REMOVED]` |
| Credit card numbers | `4111-1111-1111-1111` | `[CARD REMOVED]` |
| URLs | `https://zoom.us/j/123` | `[URL REMOVED]` |
| Medical terms | `Dr. appointment at clinic` | `Private` |

**AI detection (opt-in, local only):**

| Category | Example |
|---|---|
| Medical | "Picking up lithium prescription" |
| Legal | "Meeting with divorce lawyer" |
| Financial | "Salary negotiation with HR" |
| Substance use | "AA meeting at St. Mark's Church" |
| Career | "Interview at Google" (optional) |
| Relationship | "Couples counseling" (optional) |
| Political | "Campaign fundraiser" (optional) |
| Religious | "Prayer group meeting" (optional) |

## CLI Reference

### Core Commands

```bash
calwash login                             # Authenticate with Google
calwash clean --dry-run                   # Preview redactions
calwash clean                             # Apply redactions (backs up first)
calwash restore --dry-run                 # Preview restore from backup
calwash restore                           # Restore events from backup
calwash accounts                          # List saved accounts
```

### Date Filtering

```bash
calwash clean --dry-run --days-back 30              # Last 30 days
calwash clean --dry-run --from-date 2025-01-01 --to-date 2025-12-31
calwash clean --dry-run --year 2024                  # All of 2024
calwash clean --dry-run --month 2025-08              # August 2025
calwash clean --dry-run --from-date today --to-date next-month
```

### Redaction Levels

```bash
calwash clean --dry-run --redaction-level coarse    # Replace entire event content
calwash clean --dry-run --redaction-level medium     # Replace only matched patterns (default)
```

### Multiple Accounts

```bash
calwash login --account work              # Add a second Google account
calwash clean --dry-run --account work    # Use the work account
calwash accounts                          # List all accounts
```

### Multiple Providers

```bash
calwash login                             # Google (default)
calwash login --provider apple            # Apple iCloud (requires calwash[caldav])
calwash clean --dry-run --provider apple
```

Install Apple Calendar support:

```bash
pipx install calwash[caldav]
```

## AI Detection

calwash can use a local LLM via [ollama](https://ollama.ai) to catch sensitive content that regex patterns miss — things like "AA meeting" or "meeting with divorce lawyer" that don't contain obvious PII but are still private.

**All AI processing happens locally. Your calendar data never leaves your machine.**

### Setup

```bash
# Interactive setup — installs ollama + downloads a model
calwash ai setup

# Or set up manually
brew install ollama        # macOS
ollama serve               # Start the server
ollama pull phi4-mini      # Download a model (2.5 GB)
```

### Usage

```bash
calwash clean --dry-run --ai                           # Use default model
calwash clean --dry-run --ai --ai-model phi4-mini      # Choose model
calwash clean --dry-run --ai --ai-categories medical,legal,substance_use
```

### Recommended Models

| Model | Size | Notes |
|---|---|---|
| phi4-mini | 2.5 GB | Fast, good accuracy (recommended) |
| llama3.2 | 2.0 GB | Lightweight default |
| llama3.1 | 4.7 GB | Best accuracy |
| gemma3n | 5.6 GB | Google, efficient on-device |
| nemotron-mini | 4.7 GB | Nvidia, strong reasoning |

Any ollama-compatible model works: `calwash clean --dry-run --ai --ai-model <name>`

### AI Management

```bash
calwash ai setup                  # Guided setup (install + model + test)
calwash ai setup --model llama3.1 # Install a specific model
calwash ai status                 # Check ollama + model readiness
calwash ai models                 # List recommended models with sizes
```

## How It Works

1. **Backup** — calwash saves a full JSON backup of your events before any changes
2. **Regex pass** — scans event summaries, descriptions, and locations for PII patterns with validation (Luhn checksum for credit cards, format checks for SSNs, etc.)
3. **AI pass** (if `--ai`) — sends events to a local LLM to classify context-dependent sensitive content
4. **Redact** — replaces matched text with tags like `[EMAIL REMOVED]` or `[SENSITIVE: MEDICAL]`
5. **Update** — pushes cleaned events back to your calendar (or shows a dry-run preview)

### Dry-Run Output

```
CLEANING PREVIEW
============================================================
User: you@gmail.com
Total events that would be modified: 96

Event 1:
  Date: 2024-01-03T11:15:00-05:00
  Description:
    Original: Contact: john@example.com, Phone: 555-123-4567
    Would change to: Contact: [EMAIL REMOVED], Phone: [PHONE REMOVED]
```

## Privacy

- **No cloud APIs for detection** — regex runs locally, AI runs on your machine via ollama
- **Google OAuth** is used only to access your calendar (read + write events)
- **Bundled OAuth credentials** — calwash ships with a Google OAuth client ID for convenience. You can use your own by placing `credentials.json` at `~/.calwash/credentials.json`
- **Tokens stored locally** at `~/.calwash/accounts/`

## Data Storage

```
~/.calwash/
  accounts/
    default/
      token.pickle          # Google OAuth token
      email.txt             # Cached email address
    work/
      token.pickle
  credentials.json          # Optional: your own OAuth client ID
```

## Requirements

- Python 3.12+
- Google account (for Google Calendar)
- ollama (optional, for AI detection)

## License

MIT
