""" models/tgat.py ============== Temporal Graph Attention Network (TGAT) Xu et al., "Inductive Representation Learning on Temporal Graphs" (ICLR 2020) Architecture ------------ - Sinusoidal time encoding (reuses src/tgn/time_encoding.py) - Per-node ring buffer of K most recent temporal neighbors - Multi-head scaled dot-product attention over temporal neighborhood - GRU-cell aggregator updates node memory after each event - Node classifier head: memory → fraud probability Event processing (streaming, chronological): For each edge (u, v, t, edge_feat): 1. Retrieve last K neighbors of u from buffer → {(t_i, h_i, e_i)} 2. Build query: Q = W_q(cat(h_u, φ(0))) [current state at t] Build keys: K = W_k(cat(h_i, φ(t−t_i))) [neighbor state at t_i] Build vals: V = W_v(cat(h_i, e_i, φ(t−t_i))) [neighbor context] 3. attn = softmax(Q K^T / √d), z = attn·V 4. h_u ← GRU(z, h_u) [update sender memory] 5. Symmetrically update h_v using u's neighborhood 6. Append (t, h_u, h_v, e) to neighbor buffers """ from __future__ import annotations from collections import defaultdict from typing import List import numpy as np import pandas as pd import torch import torch.nn as nn import torch.nn.functional as F from models.base import TemporalModel from models.tgn_wrapper import _make_users_df from src.graph.graph_builder import build_edge_features from src.tgn.time_encoding import TimeEncoding # ------------------------------------------------------------------ # # Core TGAT nn.Module # # ------------------------------------------------------------------ # class _TGATModule(nn.Module): def __init__( self, memory_dim: int, edge_dim: int, time_dim: int, num_heads: int, ): super().__init__() self.memory_dim = memory_dim self.time_enc = TimeEncoding(time_dim) # Input dimensions after concatenation q_in = memory_dim + 2 * time_dim # h_u || φ(0) kv_base = memory_dim + 2 * time_dim # h_nbr || φ(dt) v_in = memory_dim + edge_dim + 2 * time_dim # h_nbr || e || φ(dt) self.attn_dim = memory_dim # output of attention self.num_heads = num_heads assert self.attn_dim % num_heads == 0, "attn_dim must be divisible by num_heads" self.W_q = nn.Linear(q_in, self.attn_dim, bias=False) self.W_k = nn.Linear(kv_base, self.attn_dim, bias=False) self.W_v = nn.Linear(v_in, self.attn_dim, bias=False) self.scale = (self.attn_dim // num_heads) ** -0.5 # Merge attended output with current memory self.merge = nn.Linear(self.attn_dim + memory_dim, memory_dim) self.gru = nn.GRUCell(memory_dim, memory_dim) # Node classifier self.classifier = nn.Sequential( nn.Linear(memory_dim, 64), nn.ReLU(), nn.Linear(64, 1), ) def attend( self, h_u: torch.Tensor, # (B, memory_dim) — current node state h_nbrs: torch.Tensor, # (B, K, memory_dim) e_nbrs: torch.Tensor, # (B, K, edge_dim) dt_nbrs: torch.Tensor, # (B, K) — time deltas mask: torch.Tensor, # (B, K) bool — True = valid ) -> torch.Tensor: """Compute multi-head attention over temporal neighborhood.""" B, K = dt_nbrs.shape H = self.num_heads d_h = self.attn_dim // H phi_0 = self.time_enc(torch.zeros(B, device=h_u.device)) # (B, 2*time_dim) phi_dt = self.time_enc(dt_nbrs.reshape(-1)).reshape(B, K, -1) # (B, K, 2*time_dim) # Query q_in = torch.cat([h_u, phi_0], dim=-1) # (B, q_in) Q = self.W_q(q_in).view(B, H, d_h) # (B, H, d_h) # Key h_nbrs_flat = h_nbrs.reshape(B * K, -1) phi_dt_flat = phi_dt.reshape(B * K, -1) k_in = torch.cat([h_nbrs_flat, phi_dt_flat], dim=-1) # (B*K, kv) K_ = self.W_k(k_in).view(B, K, H, d_h) # (B, K, H, d_h) K_ = K_.permute(0, 2, 1, 3) # (B, H, K, d_h) # Value v_in = torch.cat([h_nbrs_flat, e_nbrs.reshape(B * K, -1), phi_dt_flat], dim=-1) V = self.W_v(v_in).view(B, K, H, d_h) V = V.permute(0, 2, 1, 3) # (B, H, K, d_h) # Attention scores scores = (Q.unsqueeze(2) @ K_.transpose(-2, -1)).squeeze(2) # (B, H, K) scores = scores * self.scale # Mask invalid neighbors (padding) if mask is not None: inv_mask = ~mask.unsqueeze(1) # (B, 1, K) scores = scores.masked_fill(inv_mask, float("-inf")) attn = F.softmax(scores, dim=-1) attn = torch.nan_to_num(attn, nan=0.0) # handle all-masked rows # Weighted sum z = (attn.unsqueeze(-1) * V).sum(dim=2) # (B, H, d_h) z = z.reshape(B, self.attn_dim) # (B, attn_dim) return z def update(self, h_u: torch.Tensor, z: torch.Tensor) -> torch.Tensor: merged = self.merge(torch.cat([z, h_u], dim=-1)) return self.gru(merged, h_u) def classify(self, memory: torch.Tensor) -> torch.Tensor: return self.classifier(memory).squeeze(-1) # ------------------------------------------------------------------ # # TGAT Streamer (event-level memory management) # # ------------------------------------------------------------------ # class _TGATStreamer: """ Maintains per-node memory and temporal neighbor buffers. Processes events in a batched manner (approximate — same-batch events use pre-batch memory state, standard practice for scalability). """ def __init__( self, module: _TGATModule, n_nodes: int, memory_dim: int, edge_dim: int, n_neighbors: int, device: torch.device, ): self.module = module self.memory_dim = memory_dim self.edge_dim = edge_dim self.n_neighbors = n_neighbors self.device = device # Node memory: (n_nodes, memory_dim) self.memory = torch.zeros(n_nodes, memory_dim, device=device) # Per-node circular neighbor buffer: stores (time, h_nbr, edge_feat) tuples # Stored as plain Python lists for flexibility; trimmed to n_neighbors self.nbr_times: List[List[float]] = [[] for _ in range(n_nodes)] self.nbr_h: List[List[torch.Tensor]] = [[] for _ in range(n_nodes)] self.nbr_e: List[List[torch.Tensor]] = [[] for _ in range(n_nodes)] def _write_memory_rows( self, node_ids: torch.Tensor, values: torch.Tensor, ) -> None: """Deterministic last-write-wins update for repeated node ids in a batch.""" for idx in range(len(node_ids)): self.memory[int(node_ids[idx].item())] = values[idx].detach() def _get_neighbor_tensors( self, node_ids: torch.Tensor ): """ Returns padded (h_nbrs, e_nbrs, dt_nbrs, mask) for a batch of nodes. """ B = len(node_ids) K = self.n_neighbors mem_dim = self.memory_dim e_dim = self.edge_dim device = self.device h_out = torch.zeros(B, K, mem_dim, device=device) e_out = torch.zeros(B, K, e_dim, device=device) dt_out = torch.zeros(B, K, device=device) mask = torch.zeros(B, K, dtype=torch.bool, device=device) # Use current timestamp == max in buf (approximate, fine for inference) # We'll pass dt as a separate tensor return h_out, e_out, dt_out, mask def _fill_neighbor_batch( self, node_ids: torch.Tensor, current_times: torch.Tensor, ): """ Fills neighbor tensors for a batch, using the stored per-node buffers. """ B = len(node_ids) K = self.n_neighbors mem_dim = self.memory_dim e_dim = self.edge_dim device = self.device h_out = torch.zeros(B, K, mem_dim, device=device) e_out = torch.zeros(B, K, e_dim, device=device) dt_out = torch.zeros(B, K, device=device) mask = torch.zeros(B, K, dtype=torch.bool, device=device) node_ids_np = node_ids.cpu().numpy() times_np = current_times.cpu().numpy() for b_idx, (nid, t_cur) in enumerate(zip(node_ids_np, times_np)): buf_t = self.nbr_times[nid] buf_h = self.nbr_h[nid] buf_e = self.nbr_e[nid] n_valid = len(buf_t) if n_valid == 0: continue n_use = min(n_valid, K) # Most recent K neighbors for k, i in enumerate(range(n_valid - n_use, n_valid)): h_out[b_idx, k] = buf_h[i] e_out[b_idx, k] = buf_e[i] dt_out[b_idx, k] = max(0.0, float(t_cur) - float(buf_t[i])) mask[b_idx, k] = True return h_out, e_out, dt_out, mask def _update_buffers( self, node_ids_np: np.ndarray, times_np: np.ndarray, h_others: torch.Tensor, # (N, mem_dim) — embedding of the other node edge_feats: torch.Tensor, # (N, edge_dim) ): """Add events to per-node neighbor buffers (detached).""" for i, nid in enumerate(node_ids_np): self.nbr_times[nid].append(float(times_np[i])) self.nbr_h[nid].append(h_others[i].detach().cpu()) self.nbr_e[nid].append(edge_feats[i].detach().cpu()) # Trim if len(self.nbr_times[nid]) > self.n_neighbors: self.nbr_times[nid].pop(0) self.nbr_h[nid].pop(0) self.nbr_e[nid].pop(0) def process_batch( self, u_ids: torch.Tensor, # (B,) v_ids: torch.Tensor, # (B,) times: torch.Tensor, # (B,) normalised edge_feats: torch.Tensor, # (B, edge_dim) compute_grad: bool = True, ) -> tuple[torch.Tensor, torch.Tensor]: """ Process a batch of events, update memory, return (logits_u, logits_v) for training (edge-level fraud prediction used only during training). """ device = self.device module = self.module # Current memory state (detach to avoid BPTT through the buffer) h_u = self.memory[u_ids].clone() # (B, mem_dim) h_v = self.memory[v_ids].clone() # (B, mem_dim) u_np = u_ids.cpu().numpy() v_np = v_ids.cpu().numpy() t_np = times.cpu().numpy() # ---- Attend for u ---- h_nbrs_u, e_nbrs_u, dt_u, mask_u = self._fill_neighbor_batch(u_ids, times) z_u = module.attend(h_u, h_nbrs_u, e_nbrs_u, dt_u, mask_u) h_u_new = module.update(h_u.detach(), z_u) # ---- Attend for v ---- h_nbrs_v, e_nbrs_v, dt_v, mask_v = self._fill_neighbor_batch(v_ids, times) z_v = module.attend(h_v, h_nbrs_v, e_nbrs_v, dt_v, mask_v) h_v_new = module.update(h_v.detach(), z_v) # Write back in a deterministic order when a node appears multiple times. self._write_memory_rows(u_ids, h_u_new) self._write_memory_rows(v_ids, h_v_new) # Update neighbor buffers self._update_buffers(u_np, t_np, h_v_new, edge_feats) self._update_buffers(v_np, t_np, h_u_new, edge_feats) return h_u_new, h_v_new def reset(self): self.memory.zero_() self.nbr_times = [[] for _ in range(self.memory.shape[0])] self.nbr_h = [[] for _ in range(self.memory.shape[0])] self.nbr_e = [[] for _ in range(self.memory.shape[0])] # ------------------------------------------------------------------ # # TGATWrapper (TemporalModel interface) # # ------------------------------------------------------------------ # class TGATWrapper(TemporalModel): """TGAT wrapped behind the unified TemporalModel interface.""" def __init__( self, memory_dim: int = 64, time_dim: int = 8, num_heads: int = 4, n_neighbors: int = 10, device: str = "cpu", ): self.memory_dim = memory_dim self.time_dim = time_dim self.num_heads = num_heads self.n_neighbors = n_neighbors self.device = torch.device(device) self._module: _TGATModule | None = None self._streamer: _TGATStreamer | None = None self._norm_stats: dict | None = None self._n_nodes: int = 0 self._edge_dim: int = 0 @property def name(self) -> str: return "TGAT" # ------------------------------------------------------------------ # def fit(self, df_train: pd.DataFrame, num_epochs: int = 3) -> None: df_train = df_train.sort_values("timestamp").reset_index(drop=True) # Pre-compute edge features edge_feats_np = build_edge_features(df_train) # (N, edge_dim) edge_dim = edge_feats_np.shape[1] self._edge_dim = edge_dim # Normalise ea_mean = edge_feats_np.mean(axis=0) ea_std = edge_feats_np.std(axis=0) + 1e-6 edge_feats_np = (edge_feats_np - ea_mean) / ea_std # Timestamps (normalise to [0,1] then amplify) t_vals = df_train["timestamp"].values.astype(np.float32) t_min, t_max = t_vals.min(), t_vals.max() t_norm = (t_vals - t_min) / (t_max - t_min + 1e-6) self._norm_stats = { "ea_mean": ea_mean, "ea_std": ea_std, "t_min": t_min, "t_max": t_max, } # Node universe all_nodes = np.union1d( df_train["sender_id"].values, df_train["receiver_id"].values ) n_nodes = int(all_nodes.max()) + 1 self._n_nodes = n_nodes # Build module and streamer module = _TGATModule( memory_dim=self.memory_dim, edge_dim=edge_dim, time_dim=self.time_dim, num_heads=self.num_heads, ).to(self.device) self._module = module streamer = _TGATStreamer( module=module, n_nodes=n_nodes, memory_dim=self.memory_dim, edge_dim=edge_dim, n_neighbors=self.n_neighbors, device=self.device, ) self._streamer = streamer # Labels (edge-level) y = torch.tensor(df_train["is_fraud"].values, dtype=torch.float32) u_ids = torch.tensor(df_train["sender_id"].values, dtype=torch.long) v_ids = torch.tensor(df_train["receiver_id"].values, dtype=torch.long) ef_all = torch.tensor(edge_feats_np, dtype=torch.float32) t_all = torch.tensor(t_norm * 5.0, dtype=torch.float32) raw_pw = (y == 0).sum() / ((y == 1).sum() + 1e-6) pos_weight = torch.clamp(raw_pw, max=10.0).to(self.device) loss_fn = nn.BCEWithLogitsLoss(pos_weight=pos_weight) optimiser = torch.optim.Adam(module.parameters(), lr=1e-3) # Edge-level loss: predict fraud for events where u is sender # (proxy training signal; node classifier fine-tuned separately) edge_classifier = nn.Sequential( nn.Linear(self.memory_dim * 2 + edge_dim, 64), nn.ReLU(), nn.Linear(64, 1), ).to(self.device) self._edge_clf = edge_classifier optimiser.add_param_group({"params": edge_classifier.parameters()}) batch_size = 512 N = len(df_train) for epoch in range(num_epochs): # Re-initialise memory each epoch to avoid over-fitting to order streamer.reset() total_loss = 0.0 for i in range(0, N, batch_size): j = min(i + batch_size, N) u_b = u_ids[i:j].to(self.device) v_b = v_ids[i:j].to(self.device) t_b = t_all[i:j].to(self.device) ef_b = ef_all[i:j].to(self.device) y_b = y[i:j].to(self.device) h_u, h_v = streamer.process_batch(u_b, v_b, t_b, ef_b) edge_in = torch.cat([h_u, h_v, ef_b], dim=-1) logits = edge_classifier(edge_in).squeeze(-1) logits = torch.clamp(logits, -10, 10) loss = loss_fn(logits, y_b) optimiser.zero_grad() loss.backward() torch.nn.utils.clip_grad_norm_(module.parameters(), 1.0) optimiser.step() total_loss += loss.item() print(f"[TGAT] Epoch {epoch + 1}/{num_epochs} Loss: {total_loss:.4f}") # Node classifier head (trained separately on node-level labels) self._node_clf = nn.Sequential( nn.Linear(self.memory_dim, 64), nn.ReLU(), nn.Linear(64, 1), ).to(self.device) # ------------------------------------------------------------------ # def predict(self, df_eval: pd.DataFrame, eval_nodes: List[int]) -> np.ndarray: assert self._streamer is not None, "Call fit() first." df_eval = df_eval.sort_values("timestamp").reset_index(drop=True) ns = self._norm_stats ef_np = build_edge_features(df_eval).astype(np.float32) ef_np = (ef_np - ns["ea_mean"]) / ns["ea_std"] t_vals = df_eval["timestamp"].values.astype(np.float32) t_norm = (t_vals - ns["t_min"]) / (ns["t_max"] - ns["t_min"] + 1e-6) u_ids = torch.tensor(df_eval["sender_id"].values, dtype=torch.long) v_ids = torch.tensor(df_eval["receiver_id"].values, dtype=torch.long) ef_t = torch.tensor(ef_np, dtype=torch.float32) t_t = torch.tensor(t_norm * 5.0, dtype=torch.float32) self._module.eval() with torch.no_grad(): batch_size = 512 for i in range(0, len(df_eval), batch_size): j = min(i + batch_size, len(df_eval)) self._streamer.process_batch( u_ids[i:j].to(self.device), v_ids[i:j].to(self.device), t_t[i:j].to(self.device), ef_t[i:j].to(self.device), compute_grad=False, ) # Extract memory for eval nodes (clamp to valid range) eval_t = torch.tensor( [min(n, self._n_nodes - 1) for n in eval_nodes], dtype=torch.long, device=self.device, ) node_emb = self._streamer.memory[eval_t] if not hasattr(self, "_node_clf") or self._node_clf is None: self._node_clf = nn.Sequential( nn.Linear(self.memory_dim, 64), nn.ReLU(), nn.Linear(64, 1) ).to(self.device) with torch.no_grad(): logits = self._node_clf(node_emb).squeeze(-1) probs = torch.sigmoid(logits).cpu().numpy() return probs.astype(np.float32) def extract_prefix_embeddings( self, df_eval: pd.DataFrame, examples: pd.DataFrame, ) -> np.ndarray: assert self._module is not None, "Call fit() first." if examples.empty: return np.zeros((0, self.memory_dim), dtype=np.float32) df_eval = df_eval.sort_values("timestamp").reset_index(drop=True).copy() if "local_event_idx" not in df_eval.columns: df_eval["local_event_idx"] = df_eval.groupby("sender_id").cumcount().astype(np.int32) capture_map: dict[tuple[int, int], list[int]] = {} for ex_idx, row in enumerate(examples.itertuples(index=False)): key = (int(row.sender_id), int(row.eval_local_event_idx)) capture_map.setdefault(key, []).append(ex_idx) max_seen_id = int(max(df_eval["sender_id"].max(), df_eval["receiver_id"].max())) + 1 streamer = _TGATStreamer( module=self._module, n_nodes=max(self._n_nodes, max_seen_id), memory_dim=self.memory_dim, edge_dim=self._edge_dim, n_neighbors=self.n_neighbors, device=self.device, ) ns = self._norm_stats edge_feats_np = build_edge_features(df_eval).astype(np.float32) edge_feats_np = (edge_feats_np - ns["ea_mean"]) / ns["ea_std"] t_vals = df_eval["timestamp"].to_numpy(dtype=np.float32) t_norm = (t_vals - ns["t_min"]) / (ns["t_max"] - ns["t_min"] + 1e-6) * 5.0 out = np.zeros((len(examples), self.memory_dim), dtype=np.float32) self._module.eval() with torch.no_grad(): for idx, row in enumerate(df_eval.itertuples(index=False)): u = torch.tensor([int(row.sender_id)], dtype=torch.long, device=self.device) v = torch.tensor([int(row.receiver_id)], dtype=torch.long, device=self.device) t = torch.tensor([t_norm[idx]], dtype=torch.float32, device=self.device) ef = torch.tensor(edge_feats_np[idx:idx + 1], dtype=torch.float32, device=self.device) streamer.process_batch(u, v, t, ef, compute_grad=False) key = (int(row.sender_id), int(row.local_event_idx)) if key in capture_map: emb = streamer.memory[int(row.sender_id)].detach().cpu().numpy().astype(np.float32) for ex_idx in capture_map[key]: out[ex_idx] = emb return out # ------------------------------------------------------------------ # def reset_memory(self) -> None: if self._streamer is not None: self._streamer.memory.zero_() self._streamer.nbr_times = [[] for _ in range(self._n_nodes)] self._streamer.nbr_h = [[] for _ in range(self._n_nodes)] self._streamer.nbr_e = [[] for _ in range(self._n_nodes)] # ------------------------------------------------------------------ # def train_node_classifier( self, eval_nodes: List[int], y_labels: np.ndarray, num_epochs: int = 150, ) -> None: """Fine-tune node classifier on node-level labels from training window.""" device = self.device eval_t = torch.tensor(eval_nodes, dtype=torch.long, device=device) node_emb = self._streamer.memory[eval_t].detach() y = torch.tensor(y_labels, dtype=torch.float32, device=device) pw = torch.clamp((y == 0).sum() / ((y == 1).sum() + 1e-6), max=10.0) loss_fn = nn.BCEWithLogitsLoss(pos_weight=pw) opt = torch.optim.Adam(self._node_clf.parameters(), lr=1e-3) self._node_clf.train() for _ in range(num_epochs): logits = self._node_clf(node_emb).squeeze(-1) loss = loss_fn(logits, y) opt.zero_grad() loss.backward() opt.step() self._node_clf.eval()