initial deployment

.dockerignore

@@ -0,0 +1,8 @@
+data/raw/
+data/processed/
+.venv/
+__pycache__/
+*.pyc
+.git/
+notebooks/
+extension/

.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+*.pt
+*.npy

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /code
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "api.app:app", "--host", "0.0.0.0", "--port", "7860"]

api/app.py

@@ -0,0 +1,379 @@
+import os
+os.environ.setdefault("OMP_NUM_THREADS", "1")
+os.environ.setdefault("OPENBLAS_NUM_THREADS", "1")
+import sys
+import re
+import json
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+import numpy as np
+import torch
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from src.config import checkpoints, device, max_seq_len, data_processed, numeric_features
+
+_model = None
+_model_info = None
+_tokenizer = None
+_numeric_mean = None
+_numeric_std = None
+_threshold = 0.5
+
+def load_model():
+    global _model, _model_info, _tokenizer, _numeric_mean, _numeric_std, _threshold
+    if _model is not None:
+        return
+    proc_path = os.path.join(data_processed, "processed.pt")
+    if os.path.exists(proc_path):
+        proc_data = torch.load(proc_path, weights_only=False)
+        _numeric_mean = proc_data.get("numeric_mean")
+        _numeric_std = proc_data.get("numeric_std")
+    info_path = os.path.join(checkpoints, "best_model_info.json")
+    if not os.path.exists(info_path):
+        raise FileNotFoundError("No trained model. Run: python src/train.py")
+    with open(info_path) as f:
+        _model_info = json.load(f)
+    name = _model_info["model_name"]
+    model_type = _model_info.get("model_type", "neural")
+    _threshold = float(_model_info.get("threshold", 0.5))
+    if model_type == "xgboost":
+        import xgboost as xgb
+        _model = xgb.XGBClassifier()
+        _model.load_model(os.path.join(checkpoints, f"{name}_best.json"))
+        _tokenizer = None
+    else:
+        from src.data import GloveVocab
+        _tokenizer = GloveVocab.load(os.path.join(checkpoints, "vocab.json"))
+        from src.models import BiGRU_LSTM, CNN_BiLSTM
+        _model = BiGRU_LSTM(vocab_size=_tokenizer.vocab_size) if name == "bigru_lstm" else CNN_BiLSTM(vocab_size=_tokenizer.vocab_size)
+
+        ckpt = os.path.join(checkpoints, f"{name}_best.pt")
+        _model.load_state_dict(torch.load(ckpt, map_location="cpu", weights_only=True))
+        _model.to(device)
+        _model.eval()
+
+def prepare_text(profile):
+    parts = []
+    bio = str(profile.get("bio", "") or profile.get("description", "") or "")
+    if bio.strip():
+        parts.append(bio.strip())
+    for t in (profile.get("recent_tweets", []) or [])[:20]:
+        t = str(t).strip()
+        if t:
+            parts.append(t)
+    combined = " [SEP] ".join(parts)
+    combined = re.sub(r"http\S+", "<URL>", combined)
+    return re.sub(r"\s+", " ", combined).strip() or "<EMPTY>"
+
+def extract_numeric(profile):
+    followers = float(profile.get("followers_count", 0))
+    friends = float(profile.get("following_count", 0) or profile.get("friends_count", 0))
+    statuses = float(profile.get("tweet_count", 0) or profile.get("statuses_count", 0))
+    favourites = float(profile.get("favourites_count", 0))
+    age = max(float(profile.get("account_age_days", 365)), 1.0)
+    tweets_per_day = statuses / age
+    bio = str(profile.get("bio", "") or profile.get("description", "") or "")
+    username = str(profile.get("username", "") or profile.get("screen_name", "") or "")
+    location = str(profile.get("location", "") or "")
+    verified = int(profile.get("is_verified", False) or profile.get("verified", False))
+    default_profile = int(profile.get("default_profile", False))
+    default_avatar = int(profile.get("has_default_avatar", False) or profile.get("default_profile_image", False))
+    f2f_ratio = followers / max(friends, 1)
+    fav2stat_ratio = favourites / max(statuses, 1)
+    fr2fol_ratio = friends / max(followers, 1)
+    stat2fol_ratio = statuses / max(followers, 1)
+    has_desc = int(len(bio) > 0)
+    has_loc = int(len(location) > 0)
+    completeness = has_desc + has_loc + (1 - default_profile) + (1 - default_avatar) + verified
+    sn_digits = sum(c.isdigit() for c in username)
+    sn_digit_ratio = sn_digits / max(len(username), 1)
+    sn_underscore = int("_" in username)
+    tweets_per_follower = statuses / max(followers, 1)
+    tpd_per_follower = tweets_per_day / max(followers, 1)
+    bio_urls = len(re.findall(r"http|www\.|\.com|\.net", bio))
+    bio_hashtags = bio.count("#")
+    bio_mentions = bio.count("@")
+    bio_words = len(bio.split()) if bio else 0
+    news_pattern = r"\b(?:news|breaking|daily|magazine|journal|times|herald|tribune|gazette|broadcast|media|press|reporter|journalist|editor|anchor|correspondent|coverage|headlines|report)\b"
+    org_pattern = r"\b(?:official|corp|inc\.?|llc|ltd|company|brand|store|shop|support|customer|service|team|foundation|organisation|organization|ngo|charity)\b"
+    bio_lower = bio.lower()
+    bio_has_news = int(bool(re.search(news_pattern, bio_lower)))
+    bio_has_org = int(bool(re.search(org_pattern, bio_lower)))
+    bio_likely_org = int((bio_has_news or bio_has_org) and followers > 1000 and age > 365)
+    is_established = int(bool(verified) and followers > 10000 and age > 365)
+    log_followers = float(np.log1p(followers))
+    log_friends = float(np.log1p(friends))
+    log_statuses = float(np.log1p(statuses))
+    log_favourites = float(np.log1p(favourites))
+    log_tpf = float(np.log1p(tweets_per_follower))
+    log_f2f = float(np.log1p(f2f_ratio))
+    return [
+        followers, friends, statuses, favourites, age, tweets_per_day,
+        log_followers, log_friends, log_statuses, log_favourites, log_tpf, log_f2f,
+        f2f_ratio, fav2stat_ratio, fr2fol_ratio, stat2fol_ratio,
+        verified, default_profile, default_avatar,
+        has_desc, has_loc, completeness, len(bio), len(username),
+        sn_digits, sn_digit_ratio, sn_underscore,
+        tweets_per_follower, tpd_per_follower,
+        bio_urls, bio_hashtags, bio_mentions, bio_words,
+        bio_has_news, bio_has_org, bio_likely_org, is_established,
+    ]
+
+feature_descriptions = {
+    "followers_count": "total followers",
+    "friends_count": "total accounts followed",
+    "statuses_count": "total tweets posted",
+    "favourites_count": "total likes given",
+    "account_age_days": "how long the account has existed",
+    "average_tweets_per_day": "tweets posted per day on average",
+    "log_followers_count": "follower count (log scale)",
+    "log_friends_count": "following count (log scale)",
+    "log_statuses_count": "tweet count (log scale)",
+    "log_favourites_count": "likes given (log scale)",
+    "log_tweets_per_follower": "tweets per follower (log scale)",
+    "log_followers_to_friends_ratio": "follower-to-following balance (log scale)",
+    "followers_to_friends_ratio": "how many followers per account followed",
+    "favourites_to_statuses_ratio": "likes given per tweet posted",
+    "friends_to_followers_ratio": "how many followed per follower",
+    "statuses_to_followers_ratio": "tweets per follower",
+    "verified": "has the verified blue checkmark",
+    "default_profile": "still using the default profile theme",
+    "default_profile_image": "still using the default avatar",
+    "has_description": "has filled in a bio",
+    "has_location": "has filled in a location",
+    "profile_completeness": "how many profile fields are filled in",
+    "description_length": "length of the bio",
+    "screen_name_length": "length of the username",
+    "screen_name_digits": "number of digits in the username",
+    "screen_name_digit_ratio": "fraction of the username that is digits",
+    "screen_name_has_underscore": "username contains an underscore",
+    "tweets_per_follower": "tweets posted per follower",
+    "tweets_per_day_per_follower": "tweets per day relative to followers",
+    "bio_url_count": "URLs in the bio",
+    "bio_hashtag_count": "hashtags in the bio",
+    "bio_mention_count": "mentions in the bio",
+    "bio_word_count": "words in the bio",
+    "bio_has_news_keywords": "bio mentions news or journalism",
+    "bio_has_org_keywords": "bio mentions an organisation or brand",
+    "bio_likely_organisation": "bio plus reach suggests a real organisation",
+    "is_established_account": "verified, large following, account older than one year",
+}
+
+def format_feature_value(name, value):
+    if name == "verified":
+        return "yes" if value > 0.5 else "no"
+    if name in ("default_profile", "default_profile_image", "has_description", "has_location",
+                "screen_name_has_underscore", "bio_has_news_keywords", "bio_has_org_keywords",
+                "bio_likely_organisation", "is_established_account"):
+        return "yes" if value > 0.5 else "no"
+    if name == "account_age_days":
+        years = value / 365.0
+        if years >= 1:
+            return f"{years:.1f} yrs"
+        return f"{int(value)} days"
+    if name in ("followers_count", "friends_count", "statuses_count", "favourites_count"):
+        if value >= 1_000_000:
+            return f"{value/1_000_000:.1f}M"
+        if value >= 1_000:
+            return f"{value/1_000:.1f}K"
+        return str(int(value))
+    if name == "average_tweets_per_day":
+        return f"{value:.1f}/day"
+    if name == "profile_completeness":
+        return f"{int(value)}/5"
+    if name == "screen_name_length":
+        return f"{int(value)} chars"
+    if name.startswith("log_"):
+        return f"{value:.2f}"
+    if "ratio" in name:
+        return f"{value:.2f}"
+    if isinstance(value, float):
+        return f"{value:.1f}"
+    return str(value)
+
+def compute_contributions(numeric_arr, raw_numeric):
+    if _model_info.get("model_type") != "xgboost":
+        return None
+    import xgboost as xgb
+    booster = _model.get_booster()
+    dmatrix = xgb.DMatrix(numeric_arr.reshape(1, -1))
+    contribs = booster.predict(dmatrix, pred_contribs=True)[0]
+    feat_contribs = contribs[:-1]
+    indexed = sorted(enumerate(feat_contribs), key=lambda x: abs(x[1]), reverse=True)
+    toward_bot, toward_human = [], []
+    for idx, contrib in indexed:
+        if abs(contrib) < 0.01:
+            continue
+        if len(toward_bot) >= 4 and len(toward_human) >= 4:
+            break
+        name = numeric_features[idx]
+        entry = {
+            "feature": name,
+            "description": feature_descriptions.get(name, name.replace("_", " ")),
+            "value": format_feature_value(name, float(raw_numeric[idx])),
+            "contribution": round(float(contrib), 3),
+        }
+        if contrib > 0 and len(toward_bot) < 4:
+            toward_bot.append(entry)
+        elif contrib < 0 and len(toward_human) < 4:
+            toward_human.append(entry)
+    return {"toward_bot": toward_bot, "toward_human": toward_human}
+
+def generate_signals(profile, score):
+    signals = []
+    followers = int(profile.get("followers_count", 0))
+    following = int(profile.get("following_count", 0) or profile.get("friends_count", 0))
+    tweets = int(profile.get("tweet_count", 0) or profile.get("statuses_count", 0))
+    age = max(int(profile.get("account_age_days", 365)), 1)
+    if followers / max(following, 1) < 0.1 and following > 100:
+        signals.append("Very low follower-to-following ratio")
+    if age < 30:
+        signals.append("Account is less than 30 days old")
+    if tweets / age > 50:
+        signals.append("Extremely high tweet frequency")
+    if profile.get("has_default_avatar", False) or profile.get("default_profile_image", False):
+        signals.append("Using default profile image")
+    if followers < 5 and following > 500:
+        signals.append("Mass-following with few followers")
+    if len(str(profile.get("bio", "") or "")) < 5:
+        signals.append("Empty or very short bio")
+    if not signals and score >= 70:
+        signals.append("Text patterns indicate automated content")
+    if not signals:
+        signals.append("No strong bot signals detected")
+    return signals
+
+def predict(profile):
+    load_model()
+
+    raw_numeric = extract_numeric(profile)
+    numeric_arr = np.array(raw_numeric, dtype=np.float32)
+    if _numeric_mean is not None and _numeric_std is not None:
+        numeric_arr = (numeric_arr - _numeric_mean) / _numeric_std
+
+    name = _model_info["model_name"]
+    model_type = _model_info.get("model_type", "neural")
+
+    if model_type == "xgboost":
+        bot_prob = float(_model.predict_proba(numeric_arr.reshape(1, -1))[0, 1])
+    else:
+        text = prepare_text(profile)
+        numeric = torch.tensor([numeric_arr], dtype=torch.float32, device=device)
+        with torch.no_grad():
+            tokens = _tokenizer.tokenize_batch([text], max_len=max_seq_len).to(device)
+            logits = _model(input_ids=tokens, numeric=numeric)
+            bot_prob = torch.sigmoid(logits.squeeze()).item()
+
+    raw_followers, raw_age = raw_numeric[0], raw_numeric[4]
+    raw_verified, raw_likely_org = raw_numeric[16], raw_numeric[35]
+    override_applied = None
+    if raw_likely_org and raw_verified and raw_age > 365 and raw_followers > 10_000:
+        capped = max(0.0, _threshold - 0.15)
+        if bot_prob > capped:
+            override_applied = "news_org"
+        bot_prob = min(bot_prob, capped)
+
+    score = int(round(bot_prob * 100))
+
+    margin = 0.18 if raw_age < 60 else 0.1
+    delta = bot_prob - _threshold
+    if abs(delta) <= margin:
+        label = "uncertain"
+    elif delta > 0:
+        label = "bot"
+    else:
+        label = "human"
+    return {
+        "username": profile.get("username", ""),
+        "bot_probability": round(bot_prob, 4),
+        "bot_score": score,
+        "label": label,
+        "confidence": "high" if abs(delta) > 0.3 else ("medium" if abs(delta) > 0.15 else "low"),
+        "signals": generate_signals(profile, score),
+        "contributions": compute_contributions(numeric_arr, raw_numeric),
+        "override_applied": override_applied,
+        "threshold": round(_threshold, 4),
+        "margin": round(margin, 4),
+    }
+
+class PredictRequest(BaseModel):
+    username: str
+    display_name: str = ""
+    bio: str = ""
+    followers_count: int = 0
+    following_count: int = 0
+    tweet_count: int = 0
+    listed_count: int = 0
+    account_age_days: int = 365
+    recent_tweets: list[str] = []
+    has_default_avatar: bool = False
+    is_verified: bool = False
+    url: str = ""
+
+class PredictResponse(BaseModel):
+    username: str
+    bot_probability: float
+    bot_score: int
+    label: str
+    confidence: str
+    signals: list[str]
+    contributions: dict | None = None
+    override_applied: str | None = None
+    threshold: float = 0.5
+    margin: float = 0.1
+
+app = FastAPI(title="Twitter Bot Detector API", version="1.0.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origin_regex=r"^(https://(x|twitter)\.com|chrome-extension://.*)$",
+    allow_credentials=False,
+    allow_methods=["POST", "GET"],
+    allow_headers=["Content-Type"],
+)
+
+@app.on_event("startup")
+async def startup():
+    try:
+        load_model()
+        print("[+] Model loaded")
+    except FileNotFoundError:
+        print("[!] No model found, train first with: python src/train.py")
+    except Exception as e:
+        print(f"[!] Model load failed: {e}")
+
+
+@app.post("/predict", response_model=PredictResponse)
+async def predict_endpoint(request: PredictRequest):
+    try:
+        return PredictResponse(**predict(request.model_dump()))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=503, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+class BatchRequest(BaseModel):
+    profiles: list[PredictRequest]
+
+class BatchResponse(BaseModel):
+    results: list[PredictResponse]
+
+@app.post("/predict_batch", response_model=BatchResponse)
+async def predict_batch_endpoint(request: BatchRequest):
+    if len(request.profiles) > 50:
+        raise HTTPException(status_code=429, detail="batch limit is 50 profiles")
+    try:
+        results = [PredictResponse(**predict(p.model_dump())) for p in request.profiles]
+        return BatchResponse(results=results)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=503, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/health")
+async def health():
+    return {
+        "status": "ok",
+        "model_loaded": _model is not None,
+        "model_name": _model_info.get("model_name", "") if _model_info else "",
+    }

models/checkpoints/best_model_info.json

@@ -0,0 +1,24 @@
+{
+  "accuracy": 0.8725,
+  "precision": 0.8336,
+  "recall": 0.7832,
+  "f1": 0.8076,
+  "threshold": 0.58,
+  "roc_auc": 0.9329,
+  "pr_auc": 0.9031,
+  "confusion_matrix": [
+    [
+      3397,
+      300
+    ],
+    [
+      416,
+      1503
+    ]
+  ],
+  "model_name": "xgboost",
+  "model_type": "xgboost",
+  "train_time_s": 0.7579660415649414,
+  "epochs_trained": 177,
+  "num_params": 1000
+}

requirements.txt

@@ -0,0 +1,19 @@
+datasets
+fastapi
+ijson
+jupyter
+matplotlib
+numpy
+pandas
+pydantic
+scikit-learn
+seaborn
+sentence-transformers
+<<<<<<< Updated upstream
+torch
+=======
+torch>=2.0
+>>>>>>> Stashed changes
+tqdm
+uvicorn[standard]
+xgboost

src/config.py

@@ -0,0 +1,59 @@
+import os
+import torch
+
+root_dir       = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+data_raw       = os.path.join(root_dir, "data", "raw")
+data_processed = os.path.join(root_dir, "data", "processed")
+checkpoints    = os.path.join(root_dir, "models", "checkpoints")
+
+dataset_csv = os.path.join(data_raw, "twitter_human_bots.csv")
+
+glove_dir  = os.path.join(data_raw, "glove")
+glove_file = os.path.join(glove_dir, "glove.twitter.27B.200d.txt")
+
+def get_device():
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+device = get_device()
+
+numeric_features = [
+    "followers_count", "friends_count", "statuses_count", "favourites_count",
+    "account_age_days", "average_tweets_per_day",
+    "log_followers_count", "log_friends_count", "log_statuses_count",
+    "log_favourites_count", "log_tweets_per_follower", "log_followers_to_friends_ratio",
+    "followers_to_friends_ratio", "favourites_to_statuses_ratio",
+    "friends_to_followers_ratio", "statuses_to_followers_ratio",
+    "verified", "default_profile", "default_profile_image",
+    "has_description", "has_location", "profile_completeness",
+    "description_length", "screen_name_length",
+    "screen_name_digits", "screen_name_digit_ratio", "screen_name_has_underscore",
+    "tweets_per_follower", "tweets_per_day_per_follower",
+    "bio_url_count", "bio_hashtag_count", "bio_mention_count", "bio_word_count",
+    "bio_has_news_keywords", "bio_has_org_keywords", "bio_likely_organisation",
+    "is_established_account",
+]
+num_numeric_features = len(numeric_features)
+
+batch_size    = 64
+max_epochs    = 50
+patience      = 7
+learning_rate = 1e-3
+weight_decay  = 1e-5
+dropout       = 0.3
+
+max_seq_len    = 128
+max_vocab_size = 50_000
+glove_dim      = 200
+
+cnn_filters     = [3, 4, 5]
+cnn_num_filters = 100
+
+rnn_hidden = 128
+rnn_layers = 1
+
+label_map     = {"human": 0, "bot": 1}
+inv_label_map = {0: "human", 1: "bot"}

src/data.py

@@ -0,0 +1,265 @@
+import json
+import os
+import re
+import sys
+from collections import Counter
+import numpy as np
+import pandas as pd
+import torch
+from torch.utils.data import Dataset
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from src.config import (
+    dataset_csv, numeric_features, data_processed, data_raw, label_map,
+    max_seq_len, max_vocab_size, glove_dim, glove_file,
+)
+
+def download_dataset():
+    if os.path.exists(dataset_csv):
+        return
+
+    print("Dataset not found, downloading from Hugging Face")
+    from datasets import load_dataset
+
+    os.makedirs(data_raw, exist_ok=True)
+    ds = load_dataset("airt-ml/twitter-human-bots", split="train")
+    ds.to_csv(dataset_csv)
+    print(f"Downloaded {len(ds):,} rows to {dataset_csv}")
+
+
+def load_and_preprocess():
+    print("Loading dataset")
+    download_dataset()
+
+    if not os.path.exists(dataset_csv):
+        raise FileNotFoundError("Dataset not found and download failed.")
+
+    df = pd.read_csv(dataset_csv)
+    print(f"Rows: {len(df):,}")
+
+    df["label"] = df["account_type"].map(label_map)
+    df = df.dropna(subset=["label"])
+    df["label"] = df["label"].astype(int)
+
+    bot_count = df["label"].sum()
+    print(f"Bots: {bot_count:,}, humans: {len(df) - bot_count:,}")
+
+    df["followers_count"] = df["followers_count"].fillna(0).astype(float)
+    df["friends_count"] = df["friends_count"].fillna(0).astype(float)
+    df["statuses_count"] = df["statuses_count"].fillna(0).astype(float)
+    df["favourites_count"] = df["favourites_count"].fillna(0).astype(float)
+    df["account_age_days"] = df["account_age_days"].fillna(365).astype(float).clip(lower=1)
+    df["average_tweets_per_day"] = df["average_tweets_per_day"].fillna(0).astype(float)
+    df["verified"] = df["verified"].fillna(False).astype(int)
+    df["default_profile"] = df["default_profile"].fillna(False).astype(int)
+    df["default_profile_image"] = df["default_profile_image"].fillna(False).astype(int)
+    df["description"] = df["description"].fillna("")
+    df["screen_name"] = df["screen_name"].fillna("")
+    df["location"] = df["location"].fillna("")
+
+    df["followers_to_friends_ratio"] = df["followers_count"] / df["friends_count"].clip(lower=1)
+    df["favourites_to_statuses_ratio"] = df["favourites_count"] / df["statuses_count"].clip(lower=1)
+    df["friends_to_followers_ratio"] = df["friends_count"] / df["followers_count"].clip(lower=1)
+    df["statuses_to_followers_ratio"] = df["statuses_count"] / df["followers_count"].clip(lower=1)
+
+    df["has_description"] = (df["description"].str.len() > 0).astype(int)
+    df["has_location"] = (df["location"].str.len() > 0).astype(int)
+    df["description_length"] = df["description"].str.len()
+    df["screen_name_length"] = df["screen_name"].str.len()
+    df["profile_completeness"] = (
+        df["has_description"] + df["has_location"]
+        + (1 - df["default_profile"]) + (1 - df["default_profile_image"])
+        + df["verified"]
+    )
+
+    df["screen_name_digits"] = df["screen_name"].apply(lambda x: sum(c.isdigit() for c in str(x)))
+    df["screen_name_digit_ratio"] = df["screen_name_digits"] / df["screen_name_length"].clip(lower=1)
+    df["screen_name_has_underscore"] = df["screen_name"].str.contains("_", na=False).astype(int)
+
+    df["tweets_per_follower"] = df["statuses_count"] / df["followers_count"].clip(lower=1)
+    df["tweets_per_day_per_follower"] = df["average_tweets_per_day"] / df["followers_count"].clip(lower=1)
+
+    df["bio_url_count"] = df["description"].str.count(r"http|www\.|\.com|\.net")
+    df["bio_hashtag_count"] = df["description"].str.count(r"#")
+    df["bio_mention_count"] = df["description"].str.count(r"@")
+    df["bio_word_count"] = df["description"].str.split().str.len().fillna(0).astype(int)
+
+    news_pattern = r"\b(?:news|breaking|daily|magazine|journal|times|herald|tribune|gazette|broadcast|media|press|reporter|journalist|editor|anchor|correspondent|coverage|headlines|report)\b"
+    org_pattern = r"\b(?:official|corp|inc\.?|llc|ltd|company|brand|store|shop|support|customer|service|team|foundation|organisation|organization|ngo|charity)\b"
+    df["bio_has_news_keywords"] = df["description"].str.lower().str.contains(news_pattern, regex=True, na=False).astype(int)
+    df["bio_has_org_keywords"] = df["description"].str.lower().str.contains(org_pattern, regex=True, na=False).astype(int)
+    df["bio_likely_organisation"] = (
+        (df["bio_has_news_keywords"] | df["bio_has_org_keywords"])
+        & (df["followers_count"] > 1000)
+        & (df["account_age_days"] > 365)
+    ).astype(int)
+    df["is_established_account"] = (
+        (df["verified"] == 1)
+        & (df["followers_count"] > 10000)
+        & (df["account_age_days"] > 365)
+    ).astype(int)
+
+    df["log_followers_count"] = np.log1p(df["followers_count"])
+    df["log_friends_count"] = np.log1p(df["friends_count"])
+    df["log_statuses_count"] = np.log1p(df["statuses_count"])
+    df["log_favourites_count"] = np.log1p(df["favourites_count"])
+    df["log_tweets_per_follower"] = np.log1p(df["tweets_per_follower"])
+    df["log_followers_to_friends_ratio"] = np.log1p(df["followers_to_friends_ratio"])
+
+    print(f"Engineered {len(numeric_features)} features")
+
+    texts = []
+    for _, row in df.iterrows():
+        desc = str(row.get("description", "") or "")
+        desc = re.sub(r"http\S+", "<URL>", desc)
+        desc = re.sub(r"\s+", " ", desc).strip()
+        texts.append(desc if desc else "<EMPTY>")
+
+    n = len(df)
+    indices = np.random.RandomState(42).permutation(n)
+    train_end = int(0.7 * n)
+    val_end = int(0.85 * n)
+
+    user_ids = [str(i) for i in range(n)]
+    splits = {
+        "train": [user_ids[i] for i in indices[:train_end]],
+        "val": [user_ids[i] for i in indices[train_end:val_end]],
+        "test": [user_ids[i] for i in indices[val_end:]],
+    }
+
+    print(f"Split: {len(splits['train']):,} train, {len(splits['val']):,} val, {len(splits['test']):,} test")
+    print(f"Preprocessed {n:,} users")
+
+    return df, texts, df["label"].values, splits, user_ids
+
+def save_processed(df, texts, labels, splits, user_ids):
+    os.makedirs(data_processed, exist_ok=True)
+
+    numeric_values = df[numeric_features].values.astype(np.float32)
+
+    train_indices = [int(uid) for uid in splits["train"]]
+    train_numeric = numeric_values[train_indices]
+    mean = train_numeric.mean(axis=0)
+    std = train_numeric.std(axis=0)
+    std[std == 0] = 1.0
+
+    numeric_normalised = (numeric_values - mean) / std
+    print(f"Normalised {len(numeric_features)} features (fitted on train split)")
+
+    torch.save({
+        "texts": texts,
+        "labels": torch.tensor(labels, dtype=torch.long),
+        "user_ids": user_ids,
+        "splits": splits,
+        "numeric_features": torch.tensor(numeric_normalised, dtype=torch.float32),
+        "numeric_mean": mean,
+        "numeric_std": std,
+    }, os.path.join(data_processed, "processed.pt"))
+
+    print(f"Saved to {data_processed}/")
+
+def load_processed():
+    path = os.path.join(data_processed, "processed.pt")
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Run: python src/data.py  (no data at {path})")
+    return torch.load(path, weights_only=False)
+
+class TwiBotDataset(Dataset):
+    def __init__(self, texts, numeric_features, labels, user_ids, split_ids=None):
+        if split_ids is not None:
+            id_set = set(split_ids)
+            indices = [i for i, uid in enumerate(user_ids) if uid in id_set]
+        else:
+            indices = list(range(len(user_ids)))
+
+        self.texts = [texts[i] for i in indices]
+        self.numeric = numeric_features[indices]
+        self.labels = labels[indices]
+
+    def __len__(self):
+        return len(self.labels)
+
+    def __getitem__(self, idx):
+        return {"text": self.texts[idx], "numeric": self.numeric[idx], "label": self.labels[idx]}
+
+def create_datasets(data, splits):
+    texts = data["texts"]
+    numeric = data["numeric_features"]
+    labels = data["labels"]
+    user_ids = data["user_ids"]
+    train = TwiBotDataset(texts, numeric, labels, user_ids, splits.get("train"))
+    val   = TwiBotDataset(texts, numeric, labels, user_ids, splits.get("val", splits.get("valid")))
+    test  = TwiBotDataset(texts, numeric, labels, user_ids, splits.get("test"))
+    print(f"Datasets: train={len(train)}, val={len(val)}, test={len(test)}")
+    return train, val, test
+
+def _tokenize_text(text):
+    text = text.lower()
+    text = re.sub(r"<URL>", " url ", text)
+    text = re.sub(r"[^\w\s]", " ", text)
+    return text.split()
+
+class GloveVocab:
+    def __init__(self, word2idx=None):
+        self.word2idx = word2idx or {"<PAD>": 0, "<UNK>": 1}
+
+    @property
+    def vocab_size(self):
+        return len(self.word2idx)
+
+    @classmethod
+    def build_from_corpus(cls, texts, max_vocab=max_vocab_size):
+        counter = Counter()
+        for text in texts:
+            counter.update(_tokenize_text(text))
+        word2idx = {"<PAD>": 0, "<UNK>": 1}
+        for word, _ in counter.most_common(max_vocab - 2):
+            word2idx[word] = len(word2idx)
+        vocab = cls(word2idx)
+        print(f"Vocabulary: {vocab.vocab_size:,} words")
+        return vocab
+
+    def tokenize_batch(self, texts, max_len=max_seq_len):
+        batch = []
+        for text in texts:
+            tokens = _tokenize_text(text)
+            ids = [self.word2idx.get(t, 1) for t in tokens[:max_len]]
+            ids += [0] * (max_len - len(ids))
+            batch.append(ids)
+        return torch.tensor(batch, dtype=torch.long)
+
+    def load_glove_embeddings(self, path=glove_file):
+        print(f"Loading GloVe from {os.path.basename(path)}")
+        glove = {}
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                parts = line.rstrip().split(" ")
+                if parts[0] in self.word2idx:
+                    glove[parts[0]] = np.array(parts[1:], dtype=np.float32)
+
+        matrix = np.random.normal(scale=0.6, size=(self.vocab_size, glove_dim)).astype(np.float32)
+        matrix[0] = 0.0
+        found = sum(1 for w in self.word2idx if w in glove)
+        print(f"GloVe coverage: {found:,}/{self.vocab_size:,} ({found/self.vocab_size*100:.1f}%)")
+        for w, i in self.word2idx.items():
+            if w in glove:
+                matrix[i] = glove[w]
+        return matrix
+
+    def random_embeddings(self):
+        matrix = np.random.normal(scale=0.6, size=(self.vocab_size, glove_dim)).astype(np.float32)
+        matrix[0] = 0.0
+        print(f"Using random embeddings ({self.vocab_size:,} x {glove_dim})")
+        return matrix
+
+    def save(self, path):
+        with open(path, "w") as f:
+            json.dump(self.word2idx, f)
+
+    @classmethod
+    def load(cls, path):
+        with open(path) as f:
+            return cls(json.load(f))
+
+if __name__ == "__main__":
+    df, texts, labels, splits, user_ids = load_and_preprocess()
+    save_processed(df, texts, labels, splits, user_ids)

src/models.py

@@ -0,0 +1,110 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from src.config import (
+    glove_dim, rnn_hidden, rnn_layers, dropout,
+    num_numeric_features, max_vocab_size,
+    cnn_filters, cnn_num_filters,
+)
+
+class NumericNet(nn.Module):
+    def __init__(self, num_features=num_numeric_features, hidden=128, dropout=dropout):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(num_features, hidden),
+            nn.ReLU(),
+            nn.BatchNorm1d(hidden),
+            nn.Dropout(dropout),
+            nn.Linear(hidden, hidden),
+            nn.ReLU(),
+            nn.Dropout(dropout),
+        )
+
+    def forward(self, x):
+        return self.net(x)
+
+
+class BiGRU_LSTM(nn.Module):
+    def __init__(self, vocab_size=max_vocab_size, embed_dim=glove_dim,
+                 rnn_hidden=rnn_hidden, rnn_layers=rnn_layers,
+                 num_numeric=num_numeric_features, dropout=dropout,
+                 pretrained_embeddings=None):
+        super().__init__()
+        self.embedding = nn.Embedding(vocab_size, embed_dim, padding_idx=0)
+        if pretrained_embeddings is not None:
+            self.embedding.weight = nn.Parameter(
+                torch.tensor(pretrained_embeddings, dtype=torch.float32), requires_grad=False)
+
+        self.bigru = nn.GRU(embed_dim, rnn_hidden, num_layers=rnn_layers,
+                            batch_first=True, bidirectional=True,
+                            dropout=dropout if rnn_layers > 1 else 0)
+        self.lstm = nn.LSTM(rnn_hidden * 2, rnn_hidden, num_layers=rnn_layers,
+                            batch_first=True, dropout=dropout if rnn_layers > 1 else 0)
+
+        self.numeric_net = NumericNet(num_numeric, hidden=128, dropout=dropout)
+
+        fused_dim = 128
+        self.text_proj = nn.Linear(rnn_hidden, fused_dim)
+        self.gate = nn.Linear(fused_dim * 2, fused_dim)
+
+        self.dropout = nn.Dropout(dropout)
+        self.classifier = nn.Linear(fused_dim, 1)
+
+    def forward(self, input_ids, numeric):
+        embedded = self.embedding(input_ids)
+        gru_out, _ = self.bigru(embedded)
+        _, (h_n, _) = self.lstm(gru_out)
+        text_repr = self.text_proj(h_n.squeeze(0))
+        num_repr = self.numeric_net(numeric)
+
+        gate = torch.sigmoid(self.gate(torch.cat([text_repr, num_repr], dim=1)))
+        fused = gate * text_repr + (1 - gate) * num_repr
+
+        x = self.dropout(F.relu(fused))
+        return self.classifier(x)
+
+
+class CNN_BiLSTM(nn.Module):
+    def __init__(self, vocab_size=max_vocab_size, embed_dim=glove_dim,
+                 filter_sizes=cnn_filters, num_filters=cnn_num_filters,
+                 rnn_hidden=rnn_hidden, rnn_layers=rnn_layers,
+                 num_numeric=num_numeric_features, dropout=dropout,
+                 pretrained_embeddings=None):
+        super().__init__()
+        self.embedding = nn.Embedding(vocab_size, embed_dim, padding_idx=0)
+        if pretrained_embeddings is not None:
+            self.embedding.weight = nn.Parameter(
+                torch.tensor(pretrained_embeddings, dtype=torch.float32), requires_grad=False)
+
+        self.convs = nn.ModuleList([nn.Conv1d(embed_dim, num_filters, fs) for fs in filter_sizes])
+        cnn_out = num_filters * len(filter_sizes)
+
+        self.bilstm = nn.LSTM(cnn_out, rnn_hidden, num_layers=rnn_layers,
+                              batch_first=True, bidirectional=True,
+                              dropout=dropout if rnn_layers > 1 else 0)
+
+        self.numeric_net = NumericNet(num_numeric, hidden=128, dropout=dropout)
+
+        fused_dim = 128
+        self.text_proj = nn.Linear(rnn_hidden * 2, fused_dim)
+        self.gate = nn.Linear(fused_dim * 2, fused_dim)
+
+        self.dropout = nn.Dropout(dropout)
+        self.classifier = nn.Linear(fused_dim, 1)
+
+    def forward(self, input_ids, numeric):
+        embedded = self.embedding(input_ids).permute(0, 2, 1)
+        conv_outs = [F.max_pool1d(F.relu(conv(embedded)), conv(embedded).size(2)).squeeze(2)
+                     for conv in self.convs]
+        cnn_out = torch.cat(conv_outs, dim=1).unsqueeze(1)
+
+        _, (h_n, _) = self.bilstm(cnn_out)
+        text_repr = self.text_proj(torch.cat([h_n[-2], h_n[-1]], dim=1))
+        num_repr = self.numeric_net(numeric)
+
+        gate = torch.sigmoid(self.gate(torch.cat([text_repr, num_repr], dim=1)))
+        fused = gate * text_repr + (1 - gate) * num_repr
+
+        x = self.dropout(F.relu(fused))
+        return self.classifier(x)