Email Spam Detection System

# ─── Core data science libraries ──────────────────────────────────────────
import numpy as np           # numerical arrays and math operations
import pandas as pd          # DataFrame (table) operations
import seaborn as sns         # statistical visualisations (bar charts, boxplots)
import matplotlib.pyplot as plt  # display charts in notebook output

print('✓ Libraries imported successfully')

# Load the dataset into a pandas DataFrame
data = pd.read_csv('spam_ham_dataset.csv')

# ── Quick overview ─────────────────────────────────────────────────────────
print(f'Dataset shape: {data.shape}')         # (rows, columns) — expect ~(5172, 4)
print(f'\nColumn names:  {data.columns.tolist()}')
print(f'\nData types:\n{data.dtypes}')
print(f'\nClass distribution:\n{data["label"].value_counts()}')

# Preview the first 5 rows to confirm the data loaded correctly
data.head()

# Print one raw email from each class to build intuition before preprocessing
print("=== Example HAM (legitimate) email (first 300 chars) ===")
print(data[data['label'] == 'ham']['text'].iloc[0][:300])

print("\n=== Example SPAM email (first 300 chars) ===")
print(data[data['label'] == 'spam']['text'].iloc[0][:300])

# ── Class distribution bar chart ─────────────────────────────────────────
class_counts = data['label'].value_counts()

plt.figure(figsize=(8, 5))
sns.barplot(x=class_counts.index, y=class_counts.values,
            palette=['#00e676', '#ff4d6d'])
plt.title('Class Distribution: Ham vs Spam', fontweight='bold')
plt.ylabel('Number of Emails')
plt.xlabel('Class Label')
plt.show()

print(f'Ham  (legitimate): {class_counts["ham"]} emails ({class_counts["ham"]/len(data)*100:.1f}%)')
print(f'Spam:              {class_counts["spam"]} emails ({class_counts["spam"]/len(data)*100:.1f}%)')

from collections import Counter

def get_most_common_words(label, num_words, column_name, data):
    """
    Returns the N most common words in all emails with a given label.
    Parameters:
        label       : 'spam' or 'ham'
        num_words   : how many top words to return
        column_name : which column to read text from ('text' or 'cleaned_txt')
        data        : the DataFrame
    """
    # Join all emails of this class into one long string, split into words
    text  = " ".join(msg for msg in data[data['label'] == label][column_name])
    words = text.lower().split()
    return Counter(words).most_common(num_words)

# Raw text (before cleaning) — includes stopwords and punctuation
ham_words  = get_most_common_words("ham",  20, "text", data)
spam_words = get_most_common_words("spam", 20, "text", data)

print("Top 20 words in HAM emails (before cleaning):")
print(ham_words)
print("\nTop 20 words in SPAM emails (before cleaning):")
print(spam_words)

# Create a new column with the character length of each email
data['text_length'] = data['text'].apply(len)

# Summary statistics: mean, median, min, max per class
print('Email length statistics by class:')
print(data.groupby('label')['text_length'].describe())

# Boxplot: box = middle 50% of data, centre line = median, dots = outliers
plt.figure(figsize=(10, 5))
sns.boxplot(x='label', y='text_length', data=data,
            palette={'ham': '#00e676', 'spam': '#ff4d6d'})
plt.title('Email Character Length by Class', fontweight='bold')
plt.ylabel('Character Count')
plt.xlabel('Label')
plt.ylim(0, 5000)   # cap at 5000 to stop extreme outliers dominating the chart
plt.show()

import string
from sklearn.feature_extraction.text import ENGLISH_STOP_WORDS

def preprocess_text(text):
    """
    Clean a single email string:
      1. Lowercase all characters  →  "FREE" becomes "free"
      2. Remove punctuation        →  "Click!" becomes "Click"
      3. Remove English stopwords  →  "the", "is", "a" etc. stripped out
    Returns a cleaned string ready for CountVectorizer.
    """
    # Step 1: lowercase — unifies different capitalisations of the same word
    text = text.lower()
    # Step 2: remove all punctuation using Python's built-in string.punctuation
    text = text.translate(str.maketrans("", "", string.punctuation))
    # Step 3: split into words, filter out stopwords, rejoin into a clean string
    words = text.split()
    words = [w for w in words if w not in ENGLISH_STOP_WORDS]
    return ' '.join(words)

# Apply cleaning to every email — use 'cleaned_txt' (underscore, not dot)
data['cleaned_txt'] = data['text'].apply(preprocess_text)

print('✓ Text cleaning applied to all emails')
print('\nOriginal email (first 200 chars):')
print(data['text'].iloc[0][:200])
print('\nCleaned version:')
print(data['cleaned_txt'].iloc[0][:200])
data.head()

# Compare top words AFTER cleaning — stopwords are now gone
# Distinctive spam words should now be clearly visible in the spam list
ham_words_clean  = get_most_common_words("ham",  20, "cleaned_txt", data)
spam_words_clean = get_most_common_words("spam", 20, "cleaned_txt", data)

print("Top 20 words in cleaned HAM emails:")
print(ham_words_clean)
print("\nTop 20 words in cleaned SPAM emails:")
print(spam_words_clean)

from sklearn.feature_extraction.text import CountVectorizer

# ── Initialise CountVectorizer ─────────────────────────────────────────────
# fit_transform() does two things in one step:
#   .fit()       — scans all emails and builds the vocabulary
#   .transform() — converts each email into its word-count vector
vectorizer = CountVectorizer()

# X = feature matrix (inputs to the model)
# y = target vector (labels: 0 = ham, 1 = spam)
X = vectorizer.fit_transform(data['cleaned_txt'])
y = data['label_num']

print(f'Feature matrix shape: {X.shape}')
# Expected output: (5172, ~50179) — 5172 emails, ~50179 unique vocabulary words
print(f'Matrix type:          {type(X)}')
# Shows 'scipy.sparse matrix' — only non-zero values are stored in memory
print(f'Vocabulary size:      {len(vectorizer.vocabulary_)}')
print(f'\nTarget class distribution:\n{y.value_counts()}')

from sklearn.model_selection import train_test_split
from sklearn.neighbors import KNeighborsClassifier
from sklearn.metrics import accuracy_score, classification_report

# ── 80/20 train-test split ────────────────────────────────────────────────
# random_state=42 makes the split reproducible — every student gets
# the same train/test division so results can be directly compared.
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

print(f'Training set: {X_train.shape[0]} emails ({X_train.shape[0]/len(y)*100:.0f}% of data)')
print(f'Test set:     {X_test.shape[0]} emails ({X_test.shape[0]/len(y)*100:.0f}% of data)')

# ── Initialise and train KNN ──────────────────────────────────────────────
# n_neighbors=5: find 5 most similar training emails, then majority-vote their labels
knn = KNeighborsClassifier(n_neighbors=5)

print('\n⏳ Training KNN (may take 30–60 seconds on Colab)...')
knn.fit(X_train, y_train)
print('✓ Training complete')

# ── Generate predictions on the held-out test set ─────────────────────────
y_pred = knn.predict(X_test)

# ── Overall accuracy ──────────────────────────────────────────────────────
knn_accuracy = accuracy_score(y_test, y_pred)
print(f'\n✅ KNN Accuracy: {knn_accuracy:.4f} ({knn_accuracy*100:.2f}%)')
print('\n📊 Full Classification Report:')
print(classification_report(y_test, y_pred, target_names=['ham', 'spam']))

# Install the Groq Python client (run once per Colab session)
!pip install -q groq

from groq import Groq
from google.colab import userdata
import time

# Load the API key from Colab Secrets — never paste keys directly into code
client = Groq(api_key=userdata.get('GROQ_API_KEY'))
print('✅ Groq client ready — connected to Llama 3')

def classify_with_groq(email_text):
    """
    Classify a single email as spam (1) or ham (0) using Llama 3 via Groq.
    Sends the first 500 characters. temperature=0 = deterministic output.
    Returns: int — 0 (ham) or 1 (spam)
    """
    prompt = f"""You are an email spam classifier.
Classify the following email as either spam or ham (not spam).
Reply with ONLY the number 1 if it is spam, or 0 if it is ham.
Do not explain your reasoning. Output ONLY 0 or 1.

Email:
{email_text[:500]}
"""
    try:
        response = client.chat.completions.create(
            model="llama-3.3-70b-versatile",
            messages=[{"role": "user", "content": prompt}],
            max_tokens=5,    # we only need 1 character (0 or 1)
            temperature=0     # no randomness — consistent output
        )
        result = response.choices[0].message.content.strip()
        return int(result) if result in ['0', '1'] else 0
    except Exception as e:
        print(f'  ⏳ Rate limit hit — waiting 10s... ({e})')
        time.sleep(10)
        return classify_with_groq(email_text)   # recursive retry

print('✅ classify_with_groq() defined and ready')

from sklearn.metrics import accuracy_score, classification_report

sample_size = 10
test_sample = data.sample(n=sample_size, random_state=42)
groq_preds  = []

print(f'Classifying {sample_size} emails with Groq (Llama 3)...\n')
for i, email in enumerate(test_sample['text']):
    pred = classify_with_groq(email)
    groq_preds.append(pred)
    print(f'  Email {i+1:>2}/{sample_size} → {"SPAM" if pred==1 else "HAM"}')
    time.sleep(1)   # pause between calls to respect rate limits

groq_accuracy = accuracy_score(test_sample['label_num'], groq_preds)
print(f'\n✅ Groq/Llama 3 accuracy on {sample_size} samples: {groq_accuracy:.4f}')
print('\n📊 Classification Report:')
print(classification_report(
    test_sample['label_num'], groq_preds, target_names=['ham', 'spam']
))

# Install Google API client libraries (pre-installed on Colab, but just in case)
!pip install -q google-auth google-auth-oauthlib google-api-python-client

import os
from google.colab import files
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import Flow
from googleapiclient.discovery import build

print('📁 A file picker will appear — select your credentials.json file')
uploaded = files.upload()

# Read-only scope: can read emails only — cannot send, delete, or modify
SCOPES           = ['https://www.googleapis.com/auth/gmail.readonly']
CREDENTIALS_PATH = 'credentials.json'
TOKEN_PATH       = 'token.json'

# Try to load a saved token from a previous run
creds = None
if os.path.exists(TOKEN_PATH):
    creds = Credentials.from_authorized_user_file(TOKEN_PATH, SCOPES)

# Run the OAuth flow if no valid token exists
if not creds or not creds.valid:
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())          # silently refresh expired token
    else:
        flow = Flow.from_client_secrets_file(
            CREDENTIALS_PATH, scopes=SCOPES,
            redirect_uri='urn:ietf:wg:oauth:2.0:oob'  # out-of-band flow for Colab
        )
        auth_url, _ = flow.authorization_url(prompt='consent')
        print('='*60)
        print('👉 STEP 1: Open this URL in a new browser tab:')
        print('='*60)
        print(auth_url)
        print('='*60)
        print('👉 STEP 2: Sign in with your Gmail and click Allow')
        print('👉 STEP 3: Copy the authorisation code shown by Google')
        print('='*60)
        code = input('📋 STEP 4: Paste the code here and press Enter: ')
        flow.fetch_token(code=code)
        creds = flow.credentials

    with open(TOKEN_PATH, 'w') as token:
        token.write(creds.to_json())
    print('✅ Token saved to token.json')

gmail_service = build('gmail', 'v1', credentials=creds)
print('✅ Gmail connected successfully!')

import base64

def get_email_body(payload):
    """
    Recursively extract plain text body from a Gmail message payload.
    Gmail stores bodies in a nested 'parts' structure. Some emails have
    a single body; others have multiple parts (plain text + HTML).
    We extract plain text and ignore HTML parts.
    """
    if 'parts' in payload:
        for part in payload['parts']:
            result = get_email_body(part)   # recursive call for nested parts
            if result: return result
    if payload.get('mimeType') == 'text/plain':
        data = payload.get('body', {}).get('data', '')
        if data:
            # Gmail encodes body bytes as URL-safe base64 — decode to readable text
            return base64.urlsafe_b64decode(data).decode('utf-8', errors='ignore')
    return ''

def fetch_inbox_emails(service, max_results=10):
    """Fetch N most recent emails. Returns list of {id, subject, sender, body}."""
    results  = service.users().messages().list(
        userId='me', labelIds=['INBOX'], maxResults=max_results
    ).execute()
    messages = results.get('messages', [])
    emails   = []
    for msg in messages:
        full_msg = service.users().messages().get(
            userId='me', id=msg['id'], format='full'
        ).execute()
        headers = full_msg['payload']['headers']
        subject = next((h['value'] for h in headers if h['name']=='Subject'), 'No Subject')
        sender  = next((h['value'] for h in headers if h['name']=='From'),    'Unknown')
        body    = get_email_body(full_msg['payload'])
        emails.append({'id':msg['id'], 'subject':subject, 'sender':sender, 'body':body})
    print(f'✅ Fetched {len(emails)} emails from inbox')
    return emails

inbox_emails = fetch_inbox_emails(gmail_service, max_results=10)

import time

print('🔍 Running spam detection on your inbox...\n')
print(f"{'#':<4} {'VERDICT':<10} {'SENDER':<35} {'SUBJECT'}")
print('─' * 95)

results = []
for i, email in enumerate(inbox_emails, 1):
    # Subject + body combined — subject often has the most direct spam signals
    text_to_classify = email['subject'] + ' ' + email['body']
    pred    = classify_with_groq(text_to_classify)
    verdict = '🚨 SPAM' if pred == 1 else '✅ HAM'
    subject_short = email['subject'][:40] + ('...' if len(email['subject']) > 40 else '')
    sender_short  = email['sender'][:33]
    results.append({'subject':email['subject'],'sender':email['sender'],
                     'verdict':'spam' if pred==1 else 'ham','pred':pred})
    print(f"{i:<4} {verdict:<10} {sender_short:<35} {subject_short}")
    time.sleep(2)   # 2-second pause — respects Groq free-tier rate limits

spam_count = sum(1 for r in results if r['pred'] == 1)
ham_count  = len(results) - spam_count
print(f"\n{'='*60}")
print(f"📊 Summary: {ham_count} HAM  |  {spam_count} SPAM  |  {len(results)} total scanned")
print(f"{'='*60}")

import pandas as pd

results_df = pd.DataFrame(results)
print(results_df[['verdict', 'sender', 'subject']].to_string(index=False))

# Save flagged spam to CSV — download from Colab Files panel (left sidebar)
spam_df = results_df[results_df['verdict'] == 'spam']
spam_df.to_csv('flagged_spam.csv', index=False)
print(f'\n✅ {len(spam_df)} spam email(s) saved to flagged_spam.csv')
results_df.to_csv('all_scan_results.csv', index=False)
print(f'✅ All {len(results_df)} results saved to all_scan_results.csv')
print('\nDownload both files from the Files panel in the left sidebar.')