simple-agent/README.md

# Personal Gmail + Calendar Agent

This project runs a small local API service that:

- scans new Gmail inbox messages
- classifies emails with **Strands** (`LINKEDIN`, `ADVERTISING`, `OTHER`)
- moves LinkedIn emails to a `LinkedIn` label/folder
- moves advertising emails to an `Advertising` label/folder
- scans the `Advertising` label and emails you new unsubscribe links (deduplicated)
- discovers unsubscribe-ready mailing lists for human review, then auto-unsubscribes selected lists
- exposes a secure availability endpoint powered by Google Calendar free/busy

## 1) Prerequisites

- Python 3.11+
- `uv` ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
- A Google account
- An OpenAI-compatible API key for Strands (`STRANDS_OPENAI_API_KEY`)
- A Google Cloud project with:
  - Gmail API enabled
  - Google Calendar API enabled
  - OAuth consent configured
  - OAuth Client ID of type **Desktop app**

## 2) Google OAuth setup

1. In Google Cloud Console, create a desktop OAuth client.
2. Download the client JSON file.
3. Save it in this project as `credentials.json`.

The first run opens a browser window for consent and creates `token.json`.
If your existing token was created before `gmail.send` was added, you may be prompted again.

## 3) Install and configure

```bash
uv sync
cp .env.example .env
```

Edit `.env` and set:

- `AGENT_API_KEY` to a strong secret for agent-to-agent calls
- `STRANDS_OPENAI_API_KEY` and optional `STRANDS_MODEL_ID` / `STRANDS_OPENAI_BASE_URL`
- optional unsubscribe digest settings (`UNSUBSCRIBE_*`)
- optional scan frequency and Gmail query

## 4) Run

```bash
uv run uvicorn app.main:app --reload
```

At startup, the scheduler runs:

- Gmail triage (`GMAIL_SCAN_INTERVAL_MINUTES`)
- unsubscribe digest (`UNSUBSCRIBE_DIGEST_INTERVAL_MINUTES`)
- auto-unsubscribe for approved lists (`UNSUBSCRIBE_AUTO_INTERVAL_MINUTES`) when `UNSUBSCRIBE_AUTO_ENABLED=true`

## 5) API usage

### Health check

```bash
curl http://127.0.0.1:8000/health
```

### Manual Gmail scan

```bash
curl -X POST "http://127.0.0.1:8000/scan?max_results=100" \
  -H "X-API-Key: your-secret"
```

### Availability for other AI agents

```bash
curl -X POST "http://127.0.0.1:8000/availability" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{
    "start": "2026-03-09T09:00:00+01:00",
    "end": "2026-03-09T10:00:00+01:00",
    "calendar_ids": ["primary"]
  }'
```

If `available` is `true`, there are no busy slots in that range.

### Manual unsubscribe digest

```bash
curl -X POST "http://127.0.0.1:8000/unsubscribe-digest?max_results=500" \
  -H "X-API-Key: your-secret"
```

### Human-in-the-loop unsubscribe candidates

```bash
curl -X POST "http://127.0.0.1:8000/unsubscribe/candidates?max_results=500" \
  -H "X-API-Key: your-secret"
```

### Execute unsubscribe for selected mailing lists

```bash
curl -X POST "http://127.0.0.1:8000/unsubscribe/execute" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{
    "selected_candidate_ids": ["abc123def456", "987zyx654wvu"],
    "remember_selection": true
  }'
```

### Trigger auto-unsubscribe run (approved lists only)

```bash
curl -X POST "http://127.0.0.1:8000/unsubscribe/auto-run?max_results=500" \
  -H "X-API-Key: your-secret"
```

## Classification behavior

- Strands classification is used for each email (`LINKEDIN`, `ADVERTISING`, `OTHER`).
- LinkedIn has priority over advertising inside the classifier prompt.
- Set `LLM_FALLBACK_TO_RULES=true` only if you want rules-based backup when LLM calls fail.
- Every scanned message gets an `AgentProcessed` label to avoid reprocessing loops.

## Unsubscribe digest behavior

- Reads emails from `UNSUBSCRIBE_QUERY` (default `label:Advertising`).
- Extracts unsubscribe URLs from `List-Unsubscribe` headers and message content.
- Removes duplicates within the run and across runs.
- Persists already sent links in `UNSUBSCRIBE_STATE_FILE`.
- Sends only new links by email, unless `UNSUBSCRIBE_SEND_EMPTY_DIGEST=true`.

## Human-In-The-Loop Unsubscribe

- Candidate discovery groups advertising messages into mailing lists using headers (`List-Id`, `From`) and unsubscribe methods.
- You pick the `candidate_id` values you want to unsubscribe from.
- Only selected lists are executed.
- Executed unsubscribe methods are persisted and never executed twice.
- Selected lists can be remembered (`remember_selection=true`) for scheduled auto-unsubscribe.
- State is saved in `UNSUBSCRIBE_HIL_STATE_FILE`.

## Notes

- Gmail "folders" are labels. This agent creates:
  - `LinkedIn`
  - `Advertising`
  - `AgentProcessed`
- Messages classified as LinkedIn/Advertising are removed from `INBOX` (moved out of inbox).