@cohortapp/agent-sdk 2.3.0

package/scripts/llm_email_dedup.py

@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+"""LLM-based email dedup — checks recent conversation history before sending.
+
+Replaces the subject+recipient lock approach (email_thread_dedup.py) per CEO
+directive ib-20260406-001. Instead of mechanically locking by subject hash,
+this module asks Claude Haiku to assess whether the proposed email duplicates
+something already sent to the same recipient.
+
+Design:
+  1. Fetch the last 5 messages from the Gmail thread with the recipient (via IMAP)
+  2. Send a fast Haiku check: "Has this topic already been addressed?"
+  3. Return skip/proceed decision with reasoning
+
+Fail-open: If the LLM call fails, the email proceeds (better to risk a
+duplicate than to drop a legitimate message).
+
+Usage (as module):
+    from llm_email_dedup import llm_dedup_check
+
+    result = llm_dedup_check(to, subject, body)
+    if result["skip"]:
+        print(f"DEDUP_SKIP (LLM): {result['reason']}")
+        return
+    # ... send the email ...
+
+Usage (CLI):
+    python3 llm_email_dedup.py <to> <subject> <body>
+"""
+import imaplib
+import email
+import json
+import os
+import sys
+import time
+from datetime import datetime, timedelta, timezone
+from email.utils import parsedate_to_datetime
+
+from pathlib import Path
+import json as _json
+AGENT_REPO_DIR = os.environ.get("AGENT_DIR", str(Path(__file__).resolve().parent.parent))
+AUDIT_DIR = os.path.join(AGENT_REPO_DIR, "logs", "audit")
+
+# Load agent identity (canonical SOT)
+try:
+    with open(os.path.join(AGENT_REPO_DIR, "config", "agent.json")) as _f:
+        _AGENT = _json.load(_f)
+except Exception:
+    _AGENT = {"email": "agent@example.com", "firstName": "agent"}
+
+AGENT_EMAIL = _AGENT.get("email", "agent@example.com")
+AGENT_GMAIL_PASSWORD = os.environ.get("GMAIL_APP_PASSWORD", "")
+
+# Load from .env if not in environment
+if not AGENT_GMAIL_PASSWORD:
+    _env_path = os.path.join(AGENT_REPO_DIR, ".env")
+    if os.path.exists(_env_path):
+        with open(_env_path) as _f:
+            for _line in _f:
+                _line = _line.strip()
+                if _line.startswith("GMAIL_APP_PASSWORD="):
+                    AGENT_GMAIL_PASSWORD = _line.split("=", 1)[1].strip().strip('"').strip("'")
+                    break
+
+# Anthropic API key
+ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+if not ANTHROPIC_API_KEY:
+    if os.path.exists(_env_path):
+        with open(_env_path) as _f:
+            for _line in _f:
+                _line = _line.strip()
+                if _line.startswith("ANTHROPIC_API_KEY="):
+                    ANTHROPIC_API_KEY = _line.split("=", 1)[1].strip().strip('"').strip("'")
+                    break
+
+# Maximum number of recent messages to fetch from the thread
+MAX_THREAD_MESSAGES = 5
+
+# Maximum age of messages to consider (48 hours)
+MAX_MESSAGE_AGE_HOURS = 48
+
+
+def _log_audit(action: str, to: str, subject: str, detail: str = ""):
+    """Append an LLM dedup decision to the daily audit log."""
+    os.makedirs(AUDIT_DIR, exist_ok=True)
+    date_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    audit_file = os.path.join(AUDIT_DIR, f"{date_str}-actions.jsonl")
+    session_id = os.environ.get("SOPHIE_SESSION_ID", str(os.getpid()))
+    entry = {
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "agent": "llm-email-dedup",
+        "action": action,
+        "to": to,
+        "subject": subject[:200],
+        "detail": detail[:500],
+        "session": session_id,
+    }
+    try:
+        with open(audit_file, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass  # Never let audit logging block sends
+
+
+def fetch_recent_thread_messages(to: str, subject: str, sender_email: str = "",
+                                  sender_password: str = "", max_messages: int = MAX_THREAD_MESSAGES) -> list:
+    """Fetch recent messages exchanged with the recipient via IMAP.
+
+    Searches both Inbox and Sent Mail for messages involving the recipient
+    within the last 48 hours. Returns a list of dicts with from, date, subject,
+    and a truncated body (first 500 chars).
+
+    Args:
+        to: Recipient email address
+        subject: Email subject (used as a secondary filter, not primary)
+        sender_email: The sending account's email
+        sender_password: The sending account's app password
+        max_messages: Maximum number of messages to return
+
+    Returns:
+        List of message dicts sorted by date (newest first), or empty list on error.
+    """
+    if not sender_email:
+        sender_email = AGENT_EMAIL
+    if not sender_password:
+        sender_password = AGENT_GMAIL_PASSWORD
+
+    if not sender_email or not sender_password:
+        return []
+
+    messages = []
+    since_date = (datetime.now() - timedelta(hours=MAX_MESSAGE_AGE_HOURS)).strftime("%d-%b-%Y")
+
+    # Extract bare email address from "Name <email>" format
+    to_bare = to.strip().lower()
+    if '<' in to_bare:
+        import re
+        match = re.search(r'<([^>]+)>', to_bare)
+        if match:
+            to_bare = match.group(1)
+
+    try:
+        mail = imaplib.IMAP4_SSL("imap.gmail.com")
+        mail.login(sender_email, sender_password)
+
+        for folder in ["INBOX", "[Gmail]/Sent Mail"]:
+            try:
+                mail.select(folder, readonly=True)
+
+                # Search for messages involving this recipient in the last 48h
+                # In Inbox: FROM the recipient. In Sent: TO the recipient.
+                if folder == "INBOX":
+                    search_criteria = f'(SINCE "{since_date}" FROM "{to_bare}")'
+                else:
+                    search_criteria = f'(SINCE "{since_date}" TO "{to_bare}")'
+
+                status, msg_nums = mail.search(None, search_criteria)
+                if status != "OK" or not msg_nums[0]:
+                    continue
+
+                for num in msg_nums[0].split():
+                    try:
+                        status, data = mail.fetch(num, "(BODY[])")
+                        if status != "OK":
+                            continue
+                        raw = data[0][1]
+                        msg = email.message_from_bytes(raw)
+
+                        # Parse date
+                        date_str = msg.get("Date", "")
+                        try:
+                            dt = parsedate_to_datetime(date_str)
+                        except Exception:
+                            dt = datetime.min
+
+                        # Extract body
+                        body_text = _extract_text_body(msg)
+
+                        messages.append({
+                            "from": msg.get("From", ""),
+                            "to": msg.get("To", ""),
+                            "date": date_str,
+                            "date_parsed": dt,
+                            "subject": msg.get("Subject", ""),
+                            "body_preview": (body_text or "")[:500],
+                            "folder": folder,
+                        })
+                    except Exception:
+                        continue
+            except Exception:
+                continue
+
+        mail.logout()
+    except Exception as e:
+        print(f"LLM_DEDUP_IMAP_WARN: {e}", file=sys.stderr)
+        return []
+
+    # Sort by date descending, take most recent N
+    messages.sort(key=lambda m: m.get("date_parsed", datetime.min), reverse=True)
+    messages = messages[:max_messages]
+
+    # Clean up parsed datetime (not JSON-serializable) before returning
+    for m in messages:
+        m.pop("date_parsed", None)
+
+    return messages
+
+
+def _extract_text_body(msg) -> str:
+    """Extract plain text body from an email message, stripping HTML."""
+    text_body = None
+    html_body = None
+
+    if msg.is_multipart():
+        for part in msg.walk():
+            ct = part.get_content_type()
+            disp = str(part.get("Content-Disposition", ""))
+            if "attachment" in disp:
+                continue
+            try:
+                payload = part.get_payload(decode=True)
+                if payload is None:
+                    continue
+                charset = part.get_content_charset() or "utf-8"
+                decoded = payload.decode(charset, errors="replace")
+            except Exception:
+                continue
+
+            if ct == "text/plain" and text_body is None:
+                text_body = decoded
+            elif ct == "text/html" and html_body is None:
+                html_body = decoded
+    else:
+        try:
+            payload = msg.get_payload(decode=True)
+            charset = msg.get_content_charset() or "utf-8"
+            decoded = payload.decode(charset, errors="replace")
+            if msg.get_content_type() == "text/html":
+                html_body = decoded
+            else:
+                text_body = decoded
+        except Exception:
+            pass
+
+    if text_body:
+        return text_body
+
+    # Fall back to stripping HTML tags from HTML body
+    if html_body:
+        import re
+        text = re.sub(r'<style[^>]*>.*?</style>', '', html_body, flags=re.DOTALL | re.IGNORECASE)
+        text = re.sub(r'<script[^>]*>.*?</script>', '', text, flags=re.DOTALL | re.IGNORECASE)
+        text = re.sub(r'<[^>]+>', ' ', text)
+        text = re.sub(r'\s+', ' ', text).strip()
+        return text
+
+    return ""
+
+
+def _call_haiku(prompt: str) -> str:
+    """Call Claude Haiku for a fast dedup assessment.
+
+    Uses the Anthropic Python SDK. Falls back gracefully on any error.
+    """
+    try:
+        import anthropic
+
+        api_key = ANTHROPIC_API_KEY
+        if not api_key:
+            return ""
+
+        client = anthropic.Anthropic(api_key=api_key)
+        response = client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=200,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return response.content[0].text.strip()
+    except Exception as e:
+        print(f"LLM_DEDUP_API_WARN: {e}", file=sys.stderr)
+        return ""
+
+
+def llm_dedup_check(to: str, subject: str, body: str,
+                     sender_email: str = "", sender_password: str = "") -> dict:
+    """LLM-based pre-send dedup check.
+
+    Fetches recent conversation history with the recipient and asks Claude
+    Haiku whether the proposed email duplicates something already sent.
+
+    Args:
+        to: Recipient email address
+        subject: Proposed email subject
+        body: Proposed email body
+        sender_email: Sender's Gmail address (default: agent.email from config/agent.json)
+        sender_password: Sender's app password (default: from env/config)
+
+    Returns:
+        dict with:
+            skip: bool — True if the email should be skipped (duplicate detected)
+            reason: str — Human-readable explanation
+            confidence: str — "high", "medium", "low"
+            recent_messages: int — Number of recent messages found
+    """
+    start_time = time.time()
+
+    # Fetch recent conversation history
+    recent = fetch_recent_thread_messages(
+        to, subject,
+        sender_email=sender_email or AGENT_EMAIL,
+        sender_password=sender_password or AGENT_GMAIL_PASSWORD,
+    )
+
+    if not recent:
+        # No recent conversation — nothing to duplicate. Proceed.
+        _log_audit("LLM_DEDUP_PROCEED", to, subject, "No recent messages found with recipient")
+        return {
+            "skip": False,
+            "reason": "No recent conversation history with recipient",
+            "confidence": "high",
+            "recent_messages": 0,
+        }
+
+    # Build context for LLM assessment
+    conversation_summary = []
+    for i, msg in enumerate(recent):
+        direction = "SENT" if AGENT_EMAIL.lower() in msg.get("from", "").lower() or (sender_email and sender_email.lower() in msg.get("from", "").lower()) else "RECEIVED"
+        conversation_summary.append(
+            f"[{i+1}] {direction} | Date: {msg['date']} | Subject: {msg['subject']}\n"
+            f"    Preview: {msg['body_preview'][:300]}"
+        )
+
+    conversation_text = "\n\n".join(conversation_summary)
+
+    prompt = f"""You are an email deduplication checker. Your job is to determine whether a proposed outgoing email duplicates something that has ALREADY been sent to the same recipient in recent correspondence.
+
+RECENT CONVERSATION HISTORY with {to} (last {MAX_MESSAGE_AGE_HOURS} hours):
+{conversation_text}
+
+PROPOSED EMAIL TO SEND:
+Subject: {subject}
+Body: {body[:500]}
+
+QUESTION: Has the core topic or request in the proposed email already been adequately addressed in the recent conversation history above? Consider:
+- Is the proposed email covering the same topic as a recently SENT message?
+- Would the recipient perceive this as a duplicate or repetitive email?
+- Minor wording differences don't matter — focus on whether the SUBSTANCE is redundant.
+
+IMPORTANT: Only flag as duplicate if there is a SENT message (not received) that covers substantially the same ground. A received message from the recipient does NOT make our response a duplicate — we may need to reply.
+
+Respond with exactly one of these two formats:
+PROCEED: [brief reason why this is not a duplicate]
+SKIP: [brief reason why this duplicates a recent sent message]"""
+
+    llm_response = _call_haiku(prompt)
+    elapsed_ms = int((time.time() - start_time) * 1000)
+
+    if not llm_response:
+        # LLM call failed — fail-open
+        _log_audit("LLM_DEDUP_FAIL_OPEN", to, subject,
+                    f"LLM call returned empty after {elapsed_ms}ms. Proceeding with send.")
+        return {
+            "skip": False,
+            "reason": "LLM check failed — proceeding (fail-open)",
+            "confidence": "low",
+            "recent_messages": len(recent),
+        }
+
+    # Parse LLM response
+    response_upper = llm_response.upper().strip()
+
+    if response_upper.startswith("SKIP"):
+        reason = llm_response.split(":", 1)[1].strip() if ":" in llm_response else llm_response
+        _log_audit("LLM_DEDUP_SKIP", to, subject,
+                    f"LLM flagged duplicate ({elapsed_ms}ms): {reason}")
+        return {
+            "skip": True,
+            "reason": reason,
+            "confidence": "high" if len(recent) >= 2 else "medium",
+            "recent_messages": len(recent),
+        }
+    elif response_upper.startswith("PROCEED"):
+        reason = llm_response.split(":", 1)[1].strip() if ":" in llm_response else llm_response
+        _log_audit("LLM_DEDUP_PROCEED", to, subject,
+                    f"LLM approved send ({elapsed_ms}ms): {reason}")
+        return {
+            "skip": False,
+            "reason": reason,
+            "confidence": "high",
+            "recent_messages": len(recent),
+        }
+    else:
+        # Ambiguous response — fail-open
+        _log_audit("LLM_DEDUP_AMBIGUOUS", to, subject,
+                    f"LLM response ambiguous ({elapsed_ms}ms): {llm_response[:200]}. Proceeding.")
+        return {
+            "skip": False,
+            "reason": f"LLM response ambiguous — proceeding (fail-open). Response: {llm_response[:100]}",
+            "confidence": "low",
+            "recent_messages": len(recent),
+        }
+
+
+# --- CLI Interface ---
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="LLM-based email dedup check. Examines recent conversation history "
+                    "with the recipient and uses Claude Haiku to assess duplication."
+    )
+    parser.add_argument("to", help="Recipient email address")
+    parser.add_argument("subject", help="Proposed email subject")
+    parser.add_argument("body", help="Proposed email body")
+    parser.add_argument("--sender-email", default="", help="Sender email (default: agent.email from config/agent.json)")
+    parser.add_argument("--sender-password", default="", help="Sender app password (default: from env)")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Show detailed output")
+
+    args = parser.parse_args()
+
+    result = llm_dedup_check(
+        args.to, args.subject, args.body,
+        sender_email=args.sender_email,
+        sender_password=args.sender_password,
+    )
+
+    if result["skip"]:
+        print(f"SKIP: {result['reason']}")
+        if args.verbose:
+            print(f"  Confidence: {result['confidence']}")
+            print(f"  Recent messages checked: {result['recent_messages']}")
+        sys.exit(2)
+    else:
+        print(f"PROCEED: {result['reason']}")
+        if args.verbose:
+            print(f"  Confidence: {result['confidence']}")
+            print(f"  Recent messages checked: {result['recent_messages']}")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()