# Pulse AI — Alert Subscriptions: Full Technical Specification

## Architecture Overview

```
User: "let me know when property_a in Miami spikes again"
        ↓
ROUTER: classifies as ALERT_SUBSCRIPTION (fast, cheap — exactly 7 classifications)
        ↓
AGENT LOOP (_resolve_active_tools):
  - Injects exactly 2 tools: create_alert_subscription + suggest_actions
  - Prompt: _PROMPT_BASE + _PROMPT_ALERT + _PROMPT_RESPONSE_RULES
        ↓
SYNTHESIS:
  - Missing details? → invokes suggest_actions with concrete chips
  - Details complete? → invokes create_alert_subscription (PENDING, unconfirmed)
        ↓
CONFIRMATION EMAIL:
  - System sends double opt-in email with single-use verification token
  - Link: https://pulse.jouledynamics.com/alerts/confirm?token=<token>
        ↓
CONFIRMATION ENDPOINT (GET /api/v1/alerts/confirm):
  - Service role validates token, sets confirmed = true, status = 'active'
  - Pulse agent itself CANNOT confirm — double opt-in strictly enforced
        ↓
EVALUATION WORKERS (Post-scrape / Scheduled / Webhook):
  - Alert Evaluator: evaluates 9 event-driven criteria types against fresh data via existing Supabase RPCs
  - Digest Sender: evaluates scheduled digest subscriptions (daily/weekly)
  - Cleanup Job: expires and purges unconfirmed pending subscriptions > 48h
        ↓
COOLDOWN ENFORCEMENT & DELIVERY:
  - 24-hour rolling cooldown prevents duplicate fires for persistent conditions
  - HTML email with unsubscribe link (GET /api/v1/alerts/unsubscribe?token=<token>)
```

---

## 1. Supported Alert Criteria Types (10 Types)

The alert system supports 10 distinct criteria types spanning event-driven, threshold, and scheduled monitoring:

| `criteria_type` | Description | Target / Required Criteria | Evaluator RPC Used | Default Cooldown |
|---|---|---|---|---|
| `spike` | Price or rate spikes exceeding threshold | `{"market": "Miami", "threshold_pct": 25, "direction": "both"}` | `get_spike_alerts` | 24 hours |
| `rate_change` | Material rate changes over window | `{"market": "Abuja", "days": 7, "min_change_pct": 10}` | `get_market_rate_changes` | 24 hours |
| `price_threshold` | Property price crosses numeric limit | `{"property_search": "...", "operator": "below", "value": 150000}` | `get_property_snapshot` | 24 hours |
| `availability_change` | Property or market occupancy change | `{"property_search": "..."}` or `{"market": "Miami"}` | `get_property_snapshot` / `get_availability_rate` | 24 hours |
| `new_listing` | New property added to tracking | `{"market": "Lagos"}` | `get_recently_changed_tracking` | 24 hours |
| `tracking_removed` | Property delisted or untracked | `{"market": "Lagos"}` or `{"property_search": "..."}` | `get_recently_changed_tracking` | 24 hours |
| `anomaly` | Statistical rate deviation | `{"property_search": "...", "days": 30}` | `get_rate_anomaly_report` | 24 hours |
| `volatility` | High rate fluctuation in market | `{"market": "Abuja", "days": 14, "limit": 5}` | `get_most_volatile_properties` | 24 hours |
| `trend_reversal` | Market trend direction shift | `{"market": "Miami", "days": 14}` | `get_market_trend` | 24 hours |
| `digest` | Periodic market recap | `{"market": "Miami", "frequency": "weekly"}` (`"daily"` or `"weekly"`) | `get_real_estate_kpis` + `get_market_averages` | Cron-driven |

---

## 2. Router Integration (`services/query_router.py`)

`ALERT_SUBSCRIPTION` is the 7th valid classification alongside:
- `OUT_OF_SCOPE`
- `PATH_A` (live market intelligence)
- `PATH_B` (general real estate / UI concepts)
- `BOTH`
- `GREETING`
- `COMMERCIAL_HANDOFF`
- `ALERT_SUBSCRIPTION`

Prompt instructions guide the router to detect explicit future-monitoring intent ("alert me when...", "notify me if...", "send me a weekly digest of...").

---

## 3. Tool Definition & Token Budget (`services/alert_tool_schema.py`)

To preserve strict token economy:
- Exactly 2 tools are exposed during `ALERT_SUBSCRIPTION` turns: `create_alert_subscription` and `suggest_actions`.
- No heavy SQL or market analysis tools are loaded into context during subscription creation.

```json
{
  "type": "function",
  "function": {
    "name": "create_alert_subscription",
    "description": "Create a PENDING alert subscription. Never call this until you have the condition type, target (market or property), and email address.",
    "parameters": {
      "type": "object",
      "properties": {
        "email": {"type": "string"},
        "criteria_type": {
          "type": "string",
          "enum": [
            "spike", "rate_change", "price_threshold", "availability_change",
            "new_listing", "tracking_removed", "anomaly", "volatility",
            "trend_reversal", "digest"
          ]
        },
        "criteria": {"type": "object"},
        "raw_request_text": {"type": "string"}
      },
      "required": ["email", "criteria_type", "criteria", "raw_request_text"]
    }
  }
}
```

---

## 4. Prompt Extension (`_PROMPT_ALERT` in `services/prompts.py`)

When `classification == "ALERT_SUBSCRIPTION"`, the system prompt injects `_PROMPT_ALERT`:
- Demands 3 essential fields before subscription creation: WHAT condition, WHICH market/property, and EMAIL ADDRESS.
- Enforces conversational follow-up via `suggest_actions` if any field is missing.
- Explains that the subscription will be created in `PENDING` state and requires confirmation via email.
- Enforces anti-spam and privacy constraints (never store personal data beyond email).

---

## 5. Security Architecture & RLS Boundary

1. **Table Schema (`misc/alert_subscriptions_migration.sql`):**
   - Columns: `id`, `email`, `criteria_type`, `criteria`, `raw_request_text`, `confirmed`, `confirmation_token`, `unsubscribe_token`, `status`, `created_at`, `confirmed_at`, `last_checked_at`, `last_fired_at`.
   - Double opt-in default: `confirmed BOOLEAN NOT NULL DEFAULT false`, `status TEXT NOT NULL DEFAULT 'pending'`.
2. **Access Control:**
   - Frontend / Public agent role: `INSERT` only (cannot `SELECT`, `UPDATE`, or `DELETE`).
   - Service Role key (`SUPABASE_SERVICE_ROLE_KEY`): Used exclusively by backend API routes and workers to confirm, update `last_fired_at`, and unsubscribe.
3. **Caps:** Maximum 5 active subscriptions per email address to prevent abuse. Friendly error message returned if exceeded.

---

## 6. Endpoints (`routes/v1/alerts.py`)

- `GET /api/v1/alerts/confirm?token=<token>`: Validates confirmation token, activates subscription (`confirmed = true, status = 'active'`), returns branded HTML response.
- `GET /api/v1/alerts/unsubscribe?token=<token>`: Validates unsubscribe token, cancels subscription (`status = 'unsubscribed'`), returns branded confirmation.
- `POST /api/v1/internal/evaluate-alerts`: Protected internal endpoint called by scrapers or webhooks with `X-Internal-Secret` header to trigger evaluation runs.

---

## 7. Workers & Automation (`workers/`)

1. **`alert_evaluator.py`**:
   - Dispatches across the 9 event-driven criteria types.
   - Reuses existing audited RPCs (`get_spike_alerts`, `get_property_snapshot`, `get_rate_anomaly_report`, etc.).
   - Enforces 24-hour rolling cooldown (`ALERT_COOLDOWN_HOURS = 24`).
2. **`digest_sender.py`**:
   - Queries active `digest` subscriptions.
   - Compiles KPIs and average metrics via `get_real_estate_kpis` and `get_market_averages`.
   - Sends daily or weekly digests based on elapsed time since `last_fired_at`.
3. **`alert_cleanup.py`**:
   - Deletes unconfirmed subscriptions older than `CONFIRMATION_EXPIRY_HOURS = 48`.

---

## 8. Pluggable Email Service (`services/email_service.py`)

- Currently backed by Gmail SMTP via `SMTP_USER` and `SMTP_PASSWORD`.
- Configured via environment variables with fallback support:
  - `SMTP_HOST` (default: `smtp.gmail.com`)
  - `SMTP_PORT` (default: `587`)
  - `SMTP_USER` (default: `jouledynamicscto@gmail.com`)
  - `FROM_EMAIL` (default: `jouledynamicscto@gmail.com`)
  - `CONFIRMATION_BASE_URL` (default: `https://pulse.jouledynamics.com`)
- Ready to swap provider (e.g. Resend, Zoho) purely via `.env` configuration without modifying business logic.