graphids 0.1.0__tar.gz

graphids-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

graphids-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/
+.pytest_cache/
+.coverage
+*.swp
+.DS_Store
+data/
+*.csv
+*.pt
+*.pth

graphids-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay Govindarajan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphids-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: graphids
+Version: 0.1.0
+Summary: Graph-based intrusion detection using GCN, Transformer autoencoder, and contrastive learning
+Project-URL: Homepage, https://github.com/vijaygovindaraja/graphids
+Project-URL: Paper, https://doi.org/10.1038/s41598-025-07956-w
+Author-email: Vijay Govindarajan <vijay.govindarajan91@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Vijay Govindarajan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cloud-security,contrastive-learning,graph-neural-network,intrusion-detection,network-security,transformer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: shap
+Requires-Dist: shap>=0.43; extra == 'shap'
+Description-Content-Type: text/markdown
+
+# GraphIDS
+
+Graph-based intrusion detection using GCN, Transformer autoencoder, and contrastive learning.
+
+Reference implementation of the framework introduced in:
+
+> Govindarajan, V. & Muzamal, J. H. (2025). Advanced cloud intrusion detection
+> framework using graph based features transformers and contrastive learning.
+> *Scientific Reports*, 15, 20511. DOI: [10.1038/s41598-025-07956-w](https://doi.org/10.1038/s41598-025-07956-w)
+
+## Install
+
+```bash
+pip install graphids
+```
+
+## Quick start
+
+```python
+from graphids import GraphIDS
+
+model = GraphIDS(n_features=41, n_classes=5)
+model.train_pipeline(X_train, y_train)
+result = model.evaluate(X_test, y_test)
+print(f"Accuracy: {result.accuracy:.4f}")
+```
+
+## Architecture
+
+Three-stage pipeline:
+
+1. **GCN** — constructs a communication graph from flow data, extracts structural node embeddings via 3-layer graph convolution
+2. **Transformer autoencoder** — refines embeddings through self-attention, identifies discriminative feature dimensions
+3. **Contrastive classifier** — improves class separation for minority attack types (U2R, R2L), outputs multi-class predictions
+
+## Results (from the paper)
+
+| Dataset | Accuracy | Precision | Recall | F1 | FPR |
+|---|---|---|---|---|---|
+| NSL-KDD (5-class) | 99.97% | 99.94% | 99.92% | 99.93% | 0.05% |
+| CIC-IDS (binary) | 99.96% | 99.93% | 99.91% | 99.92% | 0.06% |
+| CIC-IDS (multi) | 99.95% | 99.92% | 99.90% | 99.91% | 0.07% |
+
+## Citation
+
+```bibtex
+@article{govindarajan2025graphids,
+    title   = {Advanced cloud intrusion detection framework using graph based
+               features transformers and contrastive learning},
+    author  = {Govindarajan, Vijay and Muzamal, Junaid Hussain},
+    journal = {Scientific Reports},
+    volume  = {15},
+    pages   = {20511},
+    year    = {2025},
+    doi     = {10.1038/s41598-025-07956-w},
+}
+```
+
+## License
+
+MIT

graphids-0.1.0/README.md

@@ -0,0 +1,61 @@
+# GraphIDS
+
+Graph-based intrusion detection using GCN, Transformer autoencoder, and contrastive learning.
+
+Reference implementation of the framework introduced in:
+
+> Govindarajan, V. & Muzamal, J. H. (2025). Advanced cloud intrusion detection
+> framework using graph based features transformers and contrastive learning.
+> *Scientific Reports*, 15, 20511. DOI: [10.1038/s41598-025-07956-w](https://doi.org/10.1038/s41598-025-07956-w)
+
+## Install
+
+```bash
+pip install graphids
+```
+
+## Quick start
+
+```python
+from graphids import GraphIDS
+
+model = GraphIDS(n_features=41, n_classes=5)
+model.train_pipeline(X_train, y_train)
+result = model.evaluate(X_test, y_test)
+print(f"Accuracy: {result.accuracy:.4f}")
+```
+
+## Architecture
+
+Three-stage pipeline:
+
+1. **GCN** — constructs a communication graph from flow data, extracts structural node embeddings via 3-layer graph convolution
+2. **Transformer autoencoder** — refines embeddings through self-attention, identifies discriminative feature dimensions
+3. **Contrastive classifier** — improves class separation for minority attack types (U2R, R2L), outputs multi-class predictions
+
+## Results (from the paper)
+
+| Dataset | Accuracy | Precision | Recall | F1 | FPR |
+|---|---|---|---|---|---|
+| NSL-KDD (5-class) | 99.97% | 99.94% | 99.92% | 99.93% | 0.05% |
+| CIC-IDS (binary) | 99.96% | 99.93% | 99.91% | 99.92% | 0.06% |
+| CIC-IDS (multi) | 99.95% | 99.92% | 99.90% | 99.91% | 0.07% |
+
+## Citation
+
+```bibtex
+@article{govindarajan2025graphids,
+    title   = {Advanced cloud intrusion detection framework using graph based
+               features transformers and contrastive learning},
+    author  = {Govindarajan, Vijay and Muzamal, Junaid Hussain},
+    journal = {Scientific Reports},
+    volume  = {15},
+    pages   = {20511},
+    year    = {2025},
+    doi     = {10.1038/s41598-025-07956-w},
+}
+```
+
+## License
+
+MIT

graphids-0.1.0/graphids/__init__.py

@@ -0,0 +1,12 @@
+"""Graph-based Intrusion Detection System (GraphIDS).
+
+A modular cloud intrusion detection framework combining GCN feature extraction,
+Transformer-based autoencoding, and contrastive learning. Reference implementation
+of the framework introduced in:
+
+    Govindarajan, V. & Muzamal, J. H. (2025). Advanced cloud intrusion detection
+    framework using graph based features transformers and contrastive learning.
+    Scientific Reports, 15, 20511. DOI: 10.1038/s41598-025-07956-w
+"""
+
+__version__ = "0.1.0"

graphids-0.1.0/graphids/contrastive.py

@@ -0,0 +1,127 @@
+"""Contrastive learning module and classification head.
+
+The contrastive loss improves class separation in the embedding space,
+particularly for minority classes (U2R, R2L) that get ignored when training
+with cross-entropy alone. It works by pulling same-class embeddings together
+and pushing different-class embeddings apart using cosine similarity.
+
+The final classification loss is:
+    L_class = L_CE + beta * L_contrastive
+
+The classifier is a two-layer FC network: 128 neurons with ReLU, then
+softmax for multi-class prediction.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class ContrastiveLoss(nn.Module):
+    """Pairwise contrastive loss using cosine similarity.
+
+    For a pair (i, j):
+        - If same class (y_ij = 1): L = -log(sim(f_i, f_j))
+        - If different class (y_ij = 0): L = -log(1 - sim(f_i, f_j))
+
+    Pairs are sampled within the batch. For efficiency, we compute the
+    full pairwise similarity matrix and mask by label equality.
+
+    Parameters
+    ----------
+    temperature
+        Scaling factor for the similarity scores. Lower values sharpen
+        the distribution. Default 0.5.
+    """
+
+    def __init__(self, temperature: float = 0.5):
+        super().__init__()
+        self.temperature = temperature
+
+    def forward(self, embeddings: torch.Tensor, labels: torch.Tensor) -> torch.Tensor:
+        """Compute the contrastive loss over all pairs in the batch.
+
+        Parameters
+        ----------
+        embeddings
+            Feature embeddings ``(batch, d)``.
+        labels
+            Integer class labels ``(batch,)``.
+        """
+        # Normalized embeddings for cosine similarity
+        normed = F.normalize(embeddings, p=2, dim=1)
+        sim_matrix = (normed @ normed.T) / self.temperature
+
+        # Mask: 1 where labels match, 0 otherwise
+        label_eq = labels.unsqueeze(0) == labels.unsqueeze(1)  # (B, B)
+        # Exclude self-pairs from the diagonal
+        mask_self = ~torch.eye(labels.size(0), dtype=torch.bool, device=labels.device)
+        positive_mask = label_eq & mask_self
+        negative_mask = ~label_eq & mask_self
+
+        # Numerically stable log-sum-exp
+        # For positive pairs: -log(exp(sim_pos) / sum(exp(sim_all)))
+        # This is equivalent to the supervised contrastive loss formulation
+        exp_sim = torch.exp(sim_matrix) * mask_self.float()
+        log_sum_exp = torch.log(exp_sim.sum(dim=1) + 1e-8)
+
+        # Mean of positive log-similarities
+        pos_sim = (sim_matrix * positive_mask.float()).sum(dim=1)
+        n_pos = positive_mask.float().sum(dim=1).clamp(min=1)
+        mean_pos_sim = pos_sim / n_pos
+
+        loss = (-mean_pos_sim + log_sum_exp).mean()
+        return loss
+
+
+class Classifier(nn.Module):
+    """Two-layer FC classifier with contrastive-augmented training.
+
+    Parameters
+    ----------
+    d_in
+        Input embedding dimensionality (should match encoder output).
+    n_classes
+        Number of output classes.
+    hidden_dim
+        Hidden layer size. Paper uses 128.
+    beta
+        Weight of the contrastive loss relative to cross-entropy.
+    """
+
+    def __init__(
+        self,
+        d_in: int,
+        n_classes: int,
+        hidden_dim: int = 128,
+        beta: float = 0.5,
+    ):
+        super().__init__()
+        self.fc1 = nn.Linear(d_in, hidden_dim)
+        self.fc2 = nn.Linear(hidden_dim, n_classes)
+        self.dropout = nn.Dropout(0.2)
+        self.beta = beta
+        self.contrastive_loss = ContrastiveLoss()
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Predict class logits."""
+        h = self.dropout(torch.relu(self.fc1(x)))
+        return self.fc2(h)
+
+    def loss(self, embeddings: torch.Tensor, logits: torch.Tensor, labels: torch.Tensor) -> torch.Tensor:
+        """Combined cross-entropy + beta * contrastive loss.
+
+        Parameters
+        ----------
+        embeddings
+            The refined feature embeddings (used for contrastive loss).
+        logits
+            Output of forward() (used for cross-entropy).
+        labels
+            Ground-truth integer labels.
+        """
+        ce_loss = F.cross_entropy(logits, labels)
+        cl_loss = self.contrastive_loss(embeddings, labels)
+        return ce_loss + self.beta * cl_loss

graphids-0.1.0/graphids/gcn.py

@@ -0,0 +1,93 @@
+"""Three-layer Graph Convolutional Network for structural feature extraction.
+
+Implemented in pure PyTorch — no dependency on torch-geometric. The GCN
+update rule at each layer is:
+
+    H^{l+1} = sigma( A_norm @ H^l @ W^l )
+
+where A_norm is the symmetrically normalized adjacency with self-loops
+(precomputed by ``graph.prepare_graph``), H^l is the node feature matrix
+at layer l, W^l is a learnable weight matrix, and sigma is ReLU.
+
+Three layers means the receptive field covers 2-hop neighborhoods — enough
+to detect patterns like lateral movement (A -> B -> C) without the
+oversmoothing that degrades embeddings at higher layer counts.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class GCNLayer(nn.Module):
+    """Single GCN convolutional layer."""
+
+    def __init__(self, in_features: int, out_features: int, dropout: float = 0.3):
+        super().__init__()
+        self.weight = nn.Parameter(torch.empty(in_features, out_features))
+        nn.init.xavier_uniform_(self.weight)
+        self.norm = nn.LayerNorm(out_features)
+        self.dropout = nn.Dropout(dropout)
+
+    def forward(self, A_norm: torch.Tensor, H: torch.Tensor) -> torch.Tensor:
+        """Forward pass: A_norm @ H @ W, then LayerNorm, ReLU, dropout."""
+        out = A_norm @ H @ self.weight
+        out = self.norm(out)
+        out = torch.relu(out)
+        out = self.dropout(out)
+        return out
+
+
+class GCN(nn.Module):
+    """Three-layer GCN for node embedding extraction.
+
+    Parameters
+    ----------
+    in_features
+        Dimensionality of the input node features (e.g. 41 for NSL-KDD).
+    hidden_dim
+        Number of neurons per GCN layer. Paper uses 64.
+    n_layers
+        Number of GCN layers. Paper uses 3.
+    dropout
+        Dropout rate. Paper uses 0.3.
+    """
+
+    def __init__(
+        self,
+        in_features: int,
+        hidden_dim: int = 64,
+        n_layers: int = 3,
+        dropout: float = 0.3,
+    ):
+        super().__init__()
+        layers = []
+        for i in range(n_layers):
+            d_in = in_features if i == 0 else hidden_dim
+            layers.append(GCNLayer(d_in, hidden_dim, dropout=dropout))
+        self.layers = nn.ModuleList(layers)
+
+    @property
+    def out_dim(self) -> int:
+        return self.layers[-1].weight.size(1)
+
+    def forward(self, A_norm: torch.Tensor, X: torch.Tensor) -> torch.Tensor:
+        """Extract node embeddings.
+
+        Parameters
+        ----------
+        A_norm
+            Normalized adjacency matrix ``(N, N)``.
+        X
+            Node feature matrix ``(N, d_in)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Node embeddings ``(N, hidden_dim)``.
+        """
+        H = X
+        for layer in self.layers:
+            H = layer(A_norm, H)
+        return H

graphids-0.1.0/graphids/graph.py

@@ -0,0 +1,85 @@
+"""Graph construction from tabular network traffic data.
+
+Converts flat flow-level feature matrices into graph representations where
+nodes are network entities (IPs, ports, services) and edges are weighted by
+communication metrics. The adjacency matrix is built from cosine similarity
+between node feature vectors, which means structurally similar nodes are
+connected more strongly than nodes that merely happen to communicate.
+"""
+
+from __future__ import annotations
+
+import torch
+import numpy as np
+from sklearn.metrics.pairwise import cosine_similarity
+
+
+def build_adjacency(X: np.ndarray, threshold: float = 0.0) -> torch.Tensor:
+    """Build a cosine-similarity adjacency matrix from a feature matrix.
+
+    Each row of X is treated as a node. The adjacency weight between nodes
+    i and j is the cosine similarity of their feature vectors, clipped to
+    [0, 1]. A threshold can be applied to sparsify the graph.
+
+    Parameters
+    ----------
+    X
+        Feature matrix with shape ``(n_nodes, n_features)``.
+    threshold
+        Edges with similarity below this value are set to zero.
+
+    Returns
+    -------
+    torch.Tensor
+        Adjacency matrix of shape ``(n_nodes, n_nodes)``.
+    """
+    sim = cosine_similarity(X)
+    sim = np.clip(sim, 0.0, 1.0)
+    if threshold > 0:
+        sim[sim < threshold] = 0.0
+    return torch.tensor(sim, dtype=torch.float32)
+
+
+def add_self_loops(A: torch.Tensor) -> torch.Tensor:
+    """Add self-loops to the adjacency matrix: Ã = A + I."""
+    return A + torch.eye(A.size(0), dtype=A.dtype, device=A.device)
+
+
+def symmetric_norm(A: torch.Tensor) -> torch.Tensor:
+    """Compute the symmetric degree normalization D^{-1/2} A D^{-1/2}.
+
+    This prevents high-degree nodes from dominating neighbor aggregation
+    in the GCN. Nodes with zero degree get a zero row/column.
+    """
+    deg = A.sum(dim=1)
+    # D^{-1/2}, guarding against zero-degree nodes
+    deg_inv_sqrt = torch.zeros_like(deg)
+    nonzero = deg > 0
+    deg_inv_sqrt[nonzero] = 1.0 / torch.sqrt(deg[nonzero])
+    D_inv_sqrt = torch.diag(deg_inv_sqrt)
+    return D_inv_sqrt @ A @ D_inv_sqrt
+
+
+def prepare_graph(X: np.ndarray, threshold: float = 0.0) -> tuple[torch.Tensor, torch.Tensor]:
+    """Full graph preparation: adjacency + normalization.
+
+    Returns the normalized adjacency matrix (ready for GCN forward pass)
+    and the node feature tensor.
+
+    Parameters
+    ----------
+    X
+        Feature matrix ``(n_nodes, n_features)``, already scaled.
+
+    Returns
+    -------
+    A_norm
+        Normalized adjacency ``(n_nodes, n_nodes)`` with self-loops.
+    X_tensor
+        Node features as a float32 tensor ``(n_nodes, n_features)``.
+    """
+    A = build_adjacency(X, threshold=threshold)
+    A_hat = add_self_loops(A)
+    A_norm = symmetric_norm(A_hat)
+    X_tensor = torch.tensor(X, dtype=torch.float32)
+    return A_norm, X_tensor

graphids-0.1.0/graphids/pipeline.py

@@ -0,0 +1,258 @@
+"""End-to-end GraphIDS pipeline: GCN → Transformer AE → Contrastive Classifier.
+
+This module wires the three stages together into a single trainable pipeline.
+Each stage can be trained independently (following the paper's training
+protocol) or jointly fine-tuned.
+
+Training protocol from the paper:
+    1. Build the graph and train the GCN (Adam, lr=0.001, batch=128, 50 epochs)
+    2. Feed GCN embeddings to the Transformer AE and train it
+       (AdamW, lr=0.0001, batch=64, 100 epochs)
+    3. Feed refined embeddings to the classifier with contrastive loss
+       (RMSprop, lr=0.0005, batch=256, 50 epochs)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import torch
+import torch.nn as nn
+from sklearn.metrics import accuracy_score, precision_score, recall_score, f1_score
+from sklearn.preprocessing import MinMaxScaler, LabelEncoder
+
+from .graph import prepare_graph
+from .gcn import GCN
+from .transformer import TransformerAutoencoder
+from .contrastive import Classifier
+
+
+@dataclass
+class EvalResult:
+    """Evaluation metrics from a prediction run."""
+    accuracy: float
+    precision: float
+    recall: float
+    f1: float
+    predictions: np.ndarray
+
+
+class GraphIDS(nn.Module):
+    """Full intrusion detection pipeline.
+
+    Parameters
+    ----------
+    n_features
+        Number of input features per flow (e.g. 41 for NSL-KDD after encoding).
+    n_classes
+        Number of output classes (e.g. 5 for NSL-KDD multi-class).
+    gcn_hidden
+        GCN hidden layer size. Paper uses 64.
+    gcn_layers
+        Number of GCN layers. Paper uses 3.
+    gcn_dropout
+        GCN dropout rate. Paper uses 0.3.
+    ae_heads
+        Number of Transformer attention heads. Paper uses 4.
+    ae_layers
+        Number of Transformer encoder/decoder layers. Paper uses 2.
+    ae_ff
+        Transformer feed-forward dimensionality. Paper uses 128.
+    ae_dropout
+        Transformer dropout rate. Paper uses 0.2.
+    ae_alpha
+        KL regularization weight for the autoencoder. Paper uses 0.001.
+    clf_hidden
+        Classifier hidden layer size. Paper uses 128.
+    beta
+        Contrastive loss weight. Controls how strongly the contrastive
+        term influences classification training.
+    """
+
+    def __init__(
+        self,
+        n_features: int,
+        n_classes: int,
+        gcn_hidden: int = 64,
+        gcn_layers: int = 3,
+        gcn_dropout: float = 0.3,
+        ae_heads: int = 4,
+        ae_layers: int = 2,
+        ae_ff: int = 128,
+        ae_dropout: float = 0.2,
+        ae_alpha: float = 0.001,
+        clf_hidden: int = 128,
+        beta: float = 0.5,
+    ):
+        super().__init__()
+        self.gcn = GCN(
+            in_features=n_features,
+            hidden_dim=gcn_hidden,
+            n_layers=gcn_layers,
+            dropout=gcn_dropout,
+        )
+        self.autoencoder = TransformerAutoencoder(
+            d_model=gcn_hidden,
+            n_heads=ae_heads,
+            n_layers=ae_layers,
+            d_ff=ae_ff,
+            dropout=ae_dropout,
+            alpha=ae_alpha,
+        )
+        self.classifier = Classifier(
+            d_in=gcn_hidden,
+            n_classes=n_classes,
+            hidden_dim=clf_hidden,
+            beta=beta,
+        )
+        self.scaler = MinMaxScaler()
+        self.label_encoder = LabelEncoder()
+
+    def preprocess(self, X: np.ndarray, y: np.ndarray | None = None, fit: bool = False):
+        """Scale features to [0, 1] and encode labels.
+
+        Parameters
+        ----------
+        X : array (n_samples, n_features)
+        y : array (n_samples,), optional
+        fit : bool
+            If True, fit the scaler and label encoder.
+
+        Returns
+        -------
+        X_scaled, y_encoded (or None)
+        """
+        if fit:
+            X_scaled = self.scaler.fit_transform(X)
+        else:
+            X_scaled = self.scaler.transform(X)
+
+        y_enc = None
+        if y is not None:
+            if fit:
+                y_enc = self.label_encoder.fit_transform(y)
+            else:
+                y_enc = self.label_encoder.transform(y)
+
+        return X_scaled, y_enc
+
+    def forward(self, A_norm: torch.Tensor, X: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        """Full forward pass through all three stages.
+
+        Returns
+        -------
+        gcn_out
+            GCN node embeddings.
+        refined
+            Transformer-refined embeddings.
+        logits
+            Classification logits.
+        """
+        gcn_out = self.gcn(A_norm, X)
+        refined, reconstructed = self.autoencoder(gcn_out)
+        logits = self.classifier(refined)
+        return gcn_out, refined, logits
+
+    def train_pipeline(
+        self,
+        X_train: np.ndarray,
+        y_train: np.ndarray,
+        gcn_epochs: int = 50,
+        ae_epochs: int = 100,
+        clf_epochs: int = 50,
+        gcn_lr: float = 0.001,
+        ae_lr: float = 0.0001,
+        clf_lr: float = 0.0005,
+        verbose: bool = True,
+    ) -> None:
+        """Train all three stages sequentially.
+
+        This follows the paper's training protocol: GCN first, then
+        autoencoder on frozen GCN embeddings, then classifier on frozen
+        refined embeddings.
+        """
+        X_scaled, y_enc = self.preprocess(X_train, y_train, fit=True)
+        A_norm, X_tensor = prepare_graph(X_scaled)
+        y_tensor = torch.tensor(y_enc, dtype=torch.long)
+
+        # Stage 1: GCN
+        if verbose:
+            print("Stage 1: Training GCN...")
+        gcn_opt = torch.optim.Adam(self.gcn.parameters(), lr=gcn_lr)
+        # Train GCN with a proxy classification objective
+        proxy_clf = nn.Linear(self.gcn.out_dim, len(self.label_encoder.classes_))
+        proxy_opt = torch.optim.Adam(
+            list(self.gcn.parameters()) + list(proxy_clf.parameters()), lr=gcn_lr
+        )
+        self.gcn.train()
+        for epoch in range(gcn_epochs):
+            proxy_opt.zero_grad()
+            embeddings = self.gcn(A_norm, X_tensor)
+            logits = proxy_clf(embeddings)
+            loss = nn.functional.cross_entropy(logits, y_tensor)
+            loss.backward()
+            proxy_opt.step()
+            if verbose and (epoch + 1) % 10 == 0:
+                print(f"  epoch {epoch+1}/{gcn_epochs}  loss={loss.item():.4f}")
+        del proxy_clf, proxy_opt
+
+        # Stage 2: Transformer autoencoder
+        if verbose:
+            print("Stage 2: Training Transformer autoencoder...")
+        ae_opt = torch.optim.AdamW(self.autoencoder.parameters(), lr=ae_lr)
+        self.gcn.eval()
+        self.autoencoder.train()
+        with torch.no_grad():
+            gcn_embeddings = self.gcn(A_norm, X_tensor)
+        for epoch in range(ae_epochs):
+            ae_opt.zero_grad()
+            encoded, reconstructed = self.autoencoder(gcn_embeddings)
+            loss = self.autoencoder.loss(gcn_embeddings, encoded, reconstructed)
+            loss.backward()
+            ae_opt.step()
+            if verbose and (epoch + 1) % 20 == 0:
+                print(f"  epoch {epoch+1}/{ae_epochs}  loss={loss.item():.4f}")
+
+        # Stage 3: Contrastive classifier
+        if verbose:
+            print("Stage 3: Training contrastive classifier...")
+        clf_opt = torch.optim.RMSprop(self.classifier.parameters(), lr=clf_lr)
+        self.autoencoder.eval()
+        self.classifier.train()
+        with torch.no_grad():
+            encoded, _ = self.autoencoder(gcn_embeddings)
+        for epoch in range(clf_epochs):
+            clf_opt.zero_grad()
+            logits = self.classifier(encoded)
+            loss = self.classifier.loss(encoded, logits, y_tensor)
+            loss.backward()
+            clf_opt.step()
+            if verbose and (epoch + 1) % 10 == 0:
+                acc = (logits.argmax(dim=1) == y_tensor).float().mean().item()
+                print(f"  epoch {epoch+1}/{clf_epochs}  loss={loss.item():.4f}  acc={acc:.4f}")
+
+        if verbose:
+            print("Training complete.")
+
+    @torch.no_grad()
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Predict class labels for new samples."""
+        self.eval()
+        X_scaled, _ = self.preprocess(X)
+        A_norm, X_tensor = prepare_graph(X_scaled)
+        _, refined, logits = self.forward(A_norm, X_tensor)
+        preds = logits.argmax(dim=1).cpu().numpy()
+        return self.label_encoder.inverse_transform(preds)
+
+    @torch.no_grad()
+    def evaluate(self, X: np.ndarray, y: np.ndarray) -> EvalResult:
+        """Predict and compute metrics."""
+        y_pred = self.predict(X)
+        return EvalResult(
+            accuracy=accuracy_score(y, y_pred),
+            precision=precision_score(y, y_pred, average="weighted", zero_division=0),
+            recall=recall_score(y, y_pred, average="weighted", zero_division=0),
+            f1=f1_score(y, y_pred, average="weighted", zero_division=0),
+            predictions=y_pred,
+        )

graphids-0.1.0/graphids/transformer.py

@@ -0,0 +1,126 @@
+"""Transformer-based autoencoder for embedding refinement.
+
+Takes the GCN node embeddings and refines them through a self-attention
+encoder-decoder. The encoder identifies which dimensions of the embedding
+are informative for distinguishing attack types; the decoder ensures the
+representation retains enough information to reconstruct the original
+embeddings (preventing information collapse).
+
+The training loss combines reconstruction error (MSE) and a KL divergence
+regularization term that keeps the latent distribution smooth. This pushes
+the autoencoder toward a compact representation where similar traffic types
+cluster together in the latent space.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class TransformerAutoencoder(nn.Module):
+    """Encoder-decoder Transformer autoencoder.
+
+    Parameters
+    ----------
+    d_model
+        Dimensionality of the input embeddings (should match GCN output dim).
+    n_heads
+        Number of attention heads. Paper uses 4.
+    n_layers
+        Number of self-attention layers in both encoder and decoder.
+        Paper uses 2.
+    d_ff
+        Feed-forward layer dimensionality. Paper uses 128.
+    dropout
+        Dropout rate. Paper uses 0.2.
+    alpha
+        Weight for the KL regularization term. Controls the tradeoff between
+        faithful reconstruction and smooth latent space.
+    """
+
+    def __init__(
+        self,
+        d_model: int = 64,
+        n_heads: int = 4,
+        n_layers: int = 2,
+        d_ff: int = 128,
+        dropout: float = 0.2,
+        alpha: float = 0.001,
+    ):
+        super().__init__()
+        self.alpha = alpha
+        self.d_model = d_model
+
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=d_model,
+            nhead=n_heads,
+            dim_feedforward=d_ff,
+            dropout=dropout,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.encoder = nn.TransformerEncoder(encoder_layer, num_layers=n_layers)
+
+        decoder_layer = nn.TransformerDecoderLayer(
+            d_model=d_model,
+            nhead=n_heads,
+            dim_feedforward=d_ff,
+            dropout=dropout,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.decoder = nn.TransformerDecoder(decoder_layer, num_layers=n_layers)
+
+    def forward(self, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        """Encode and reconstruct.
+
+        Parameters
+        ----------
+        x
+            Input embeddings ``(batch, d_model)`` or ``(batch, seq, d_model)``.
+
+        Returns
+        -------
+        encoded
+            Refined embeddings from the encoder.
+        reconstructed
+            Decoder's reconstruction of the input.
+        """
+        # Add a sequence dimension if input is 2D (treating each sample as
+        # a length-1 sequence). This is the common case when the GCN
+        # produces one embedding per node.
+        squeeze = False
+        if x.dim() == 2:
+            x = x.unsqueeze(1)  # (batch, 1, d_model)
+            squeeze = True
+
+        encoded = self.encoder(x)
+        reconstructed = self.decoder(encoded, encoded)
+
+        if squeeze:
+            encoded = encoded.squeeze(1)
+            reconstructed = reconstructed.squeeze(1)
+
+        return encoded, reconstructed
+
+    def loss(self, x: torch.Tensor, encoded: torch.Tensor, reconstructed: torch.Tensor) -> torch.Tensor:
+        """Combined reconstruction + KL regularization loss.
+
+        L = L_recon + alpha * L_reg
+        L_recon = (1/n) * sum ||x - x_hat||^2
+        L_reg = (1/n) * sum KL(softmax(x) || softmax(x_hat))
+        """
+        # Reconstruction loss (MSE)
+        recon_loss = F.mse_loss(reconstructed, x)
+
+        # KL divergence regularization between input and reconstruction
+        # distributions (applied over the feature dimension via softmax)
+        log_p = F.log_softmax(x, dim=-1)
+        q = F.softmax(reconstructed.detach(), dim=-1)
+        kl_loss = F.kl_div(log_p, q, reduction="batchmean")
+
+        return recon_loss + self.alpha * kl_loss

graphids-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "graphids"
+version = "0.1.0"
+description = "Graph-based intrusion detection using GCN, Transformer autoencoder, and contrastive learning"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Vijay Govindarajan", email = "vijay.govindarajan91@gmail.com" },
+]
+keywords = [
+    "intrusion-detection",
+    "graph-neural-network",
+    "transformer",
+    "contrastive-learning",
+    "cloud-security",
+    "network-security",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+]
+dependencies = [
+    "torch>=2.0",
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "scikit-learn>=1.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+shap = ["shap>=0.43"]
+
+[project.urls]
+Homepage = "https://github.com/vijaygovindaraja/graphids"
+Paper = "https://doi.org/10.1038/s41598-025-07956-w"
+
+[tool.hatch.build.targets.wheel]
+packages = ["graphids"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

graphids-0.1.0/tests/test_graph.py

@@ -0,0 +1,69 @@
+"""Tests for graph construction."""
+
+import numpy as np
+import torch
+import pytest
+
+from graphids.graph import build_adjacency, add_self_loops, symmetric_norm, prepare_graph
+
+
+def test_adjacency_shape():
+    X = np.random.randn(10, 5)
+    A = build_adjacency(X)
+    assert A.shape == (10, 10)
+
+
+def test_adjacency_symmetric():
+    X = np.random.randn(8, 4)
+    A = build_adjacency(X)
+    torch.testing.assert_close(A, A.T)
+
+
+def test_adjacency_non_negative():
+    X = np.random.randn(10, 5)
+    A = build_adjacency(X)
+    assert (A >= 0).all()
+
+
+def test_adjacency_threshold():
+    X = np.random.randn(20, 5)
+    A = build_adjacency(X, threshold=0.5)
+    assert (A[A > 0] >= 0.5).all()
+
+
+def test_self_loops_adds_identity():
+    A = torch.zeros(3, 3)
+    A_hat = add_self_loops(A)
+    torch.testing.assert_close(A_hat, torch.eye(3))
+
+
+def test_symmetric_norm_preserves_shape():
+    A = torch.ones(5, 5)
+    A_norm = symmetric_norm(A)
+    assert A_norm.shape == (5, 5)
+
+
+def test_symmetric_norm_row_sums():
+    """For a uniform adjacency (all ones), the normalized version should
+    have rows summing to 1."""
+    N = 5
+    A = torch.ones(N, N)
+    A_norm = symmetric_norm(A)
+    row_sums = A_norm.sum(dim=1)
+    torch.testing.assert_close(row_sums, torch.ones(N), atol=1e-6, rtol=0)
+
+
+def test_prepare_graph_returns_correct_types():
+    X = np.random.randn(10, 5).astype(np.float32)
+    A_norm, X_tensor = prepare_graph(X)
+    assert isinstance(A_norm, torch.Tensor)
+    assert isinstance(X_tensor, torch.Tensor)
+    assert A_norm.shape == (10, 10)
+    assert X_tensor.shape == (10, 5)
+
+
+def test_identical_rows_have_max_similarity():
+    X = np.ones((3, 4))  # all identical rows
+    A = build_adjacency(X)
+    # Cosine similarity of identical vectors is 1.0
+    assert A.min().item() >= 0.99

graphids-0.1.0/tests/test_model.py

@@ -0,0 +1,133 @@
+"""Tests for the GCN, Transformer autoencoder, and classifier modules."""
+
+import torch
+import pytest
+
+from graphids.gcn import GCN, GCNLayer
+from graphids.transformer import TransformerAutoencoder
+from graphids.contrastive import Classifier, ContrastiveLoss
+
+
+# --------------------------------------------------------------------------- #
+# GCN
+# --------------------------------------------------------------------------- #
+def test_gcn_output_shape():
+    gcn = GCN(in_features=41, hidden_dim=64, n_layers=3)
+    A = torch.eye(10)
+    X = torch.randn(10, 41)
+    out = gcn(A, X)
+    assert out.shape == (10, 64)
+
+
+def test_gcn_single_layer():
+    gcn = GCN(in_features=5, hidden_dim=8, n_layers=1)
+    A = torch.eye(4)
+    X = torch.randn(4, 5)
+    out = gcn(A, X)
+    assert out.shape == (4, 8)
+
+
+def test_gcn_out_dim_property():
+    gcn = GCN(in_features=10, hidden_dim=32)
+    assert gcn.out_dim == 32
+
+
+def test_gcn_gradient_flows():
+    gcn = GCN(in_features=5, hidden_dim=8)
+    A = torch.eye(3)
+    X = torch.randn(3, 5)
+    out = gcn(A, X)
+    loss = out.sum()
+    loss.backward()
+    for p in gcn.parameters():
+        assert p.grad is not None
+
+
+# --------------------------------------------------------------------------- #
+# Transformer autoencoder
+# --------------------------------------------------------------------------- #
+def test_ae_output_shape():
+    ae = TransformerAutoencoder(d_model=64, n_heads=4, n_layers=2, d_ff=128)
+    x = torch.randn(8, 64)
+    encoded, reconstructed = ae(x)
+    assert encoded.shape == (8, 64)
+    assert reconstructed.shape == (8, 64)
+
+
+def test_ae_loss_finite():
+    ae = TransformerAutoencoder(d_model=16, n_heads=2, n_layers=1, d_ff=32)
+    x = torch.randn(5, 16)
+    encoded, reconstructed = ae(x)
+    loss = ae.loss(x, encoded, reconstructed)
+    assert torch.isfinite(loss)
+    assert loss.item() > 0
+
+
+def test_ae_3d_input():
+    ae = TransformerAutoencoder(d_model=16, n_heads=2, n_layers=1, d_ff=32)
+    x = torch.randn(4, 3, 16)  # batch=4, seq=3, d=16
+    encoded, reconstructed = ae(x)
+    assert encoded.shape == (4, 3, 16)
+
+
+# --------------------------------------------------------------------------- #
+# Contrastive loss
+# --------------------------------------------------------------------------- #
+def test_contrastive_loss_finite():
+    cl = ContrastiveLoss()
+    embeddings = torch.randn(16, 32)
+    labels = torch.tensor([0, 0, 1, 1, 2, 2, 0, 1, 2, 0, 1, 2, 0, 1, 2, 0])
+    loss = cl(embeddings, labels)
+    assert torch.isfinite(loss)
+
+
+def test_contrastive_loss_lower_for_good_embeddings():
+    """Embeddings that already cluster by class should produce lower loss
+    than random embeddings."""
+    cl = ContrastiveLoss()
+    labels = torch.tensor([0, 0, 0, 1, 1, 1, 2, 2, 2])
+
+    # Good: each class is a tight cluster far from others
+    good = torch.zeros(9, 8)
+    good[:3, :3] = 5.0
+    good[3:6, 3:6] = 5.0
+    good[6:, 6:] = 5.0
+    good += torch.randn_like(good) * 0.1
+
+    # Bad: random
+    bad = torch.randn(9, 8)
+
+    loss_good = cl(good, labels)
+    loss_bad = cl(bad, labels)
+    assert loss_good < loss_bad
+
+
+# --------------------------------------------------------------------------- #
+# Classifier
+# --------------------------------------------------------------------------- #
+def test_classifier_output_shape():
+    clf = Classifier(d_in=64, n_classes=5, hidden_dim=128)
+    x = torch.randn(10, 64)
+    logits = clf(x)
+    assert logits.shape == (10, 5)
+
+
+def test_classifier_loss_finite():
+    clf = Classifier(d_in=32, n_classes=3, hidden_dim=64)
+    embeddings = torch.randn(8, 32)
+    logits = clf(embeddings)
+    labels = torch.tensor([0, 1, 2, 0, 1, 2, 0, 1])
+    loss = clf.loss(embeddings, logits, labels)
+    assert torch.isfinite(loss)
+    assert loss.item() > 0
+
+
+def test_classifier_gradient_flows():
+    clf = Classifier(d_in=16, n_classes=3)
+    x = torch.randn(6, 16)
+    logits = clf(x)
+    labels = torch.tensor([0, 1, 2, 0, 1, 2])
+    loss = clf.loss(x, logits, labels)
+    loss.backward()
+    for p in clf.parameters():
+        assert p.grad is not None

graphids-0.1.0/tests/test_pipeline.py

@@ -0,0 +1,94 @@
+"""Integration tests for the full GraphIDS pipeline."""
+
+import numpy as np
+import pytest
+from sklearn.datasets import make_classification
+
+from graphids.pipeline import GraphIDS, EvalResult
+
+
+def _make_ids_data(n_samples=200, n_features=20, n_classes=3, random_state=42):
+    X, y = make_classification(
+        n_samples=n_samples,
+        n_features=n_features,
+        n_informative=12,
+        n_redundant=4,
+        n_classes=n_classes,
+        random_state=random_state,
+        flip_y=0.03,
+    )
+    return X, y
+
+
+def test_train_and_predict_shapes():
+    X, y = _make_ids_data(n_samples=100, n_classes=3)
+    model = GraphIDS(n_features=20, n_classes=3)
+    model.train_pipeline(
+        X[:70], y[:70],
+        gcn_epochs=5, ae_epochs=5, clf_epochs=5,
+        verbose=False,
+    )
+    preds = model.predict(X[70:])
+    assert preds.shape == (30,)
+
+
+def test_evaluate_returns_result():
+    X, y = _make_ids_data(n_samples=100, n_classes=2)
+    model = GraphIDS(n_features=20, n_classes=2)
+    model.train_pipeline(
+        X[:70], y[:70],
+        gcn_epochs=5, ae_epochs=5, clf_epochs=5,
+        verbose=False,
+    )
+    result = model.evaluate(X[70:], y[70:])
+    assert isinstance(result, EvalResult)
+    assert 0 <= result.accuracy <= 1
+    assert 0 <= result.f1 <= 1
+    assert result.predictions.shape == (30,)
+
+
+def test_accuracy_above_chance():
+    # Binary classification with a well-separated dataset gives the
+    # 3-stage pipeline enough signal to learn in a short training run.
+    X, y = _make_ids_data(n_samples=400, n_features=20, n_classes=2, random_state=0)
+    model = GraphIDS(n_features=20, n_classes=2)
+    model.train_pipeline(
+        X[:300], y[:300],
+        gcn_epochs=40, ae_epochs=40, clf_epochs=40,
+        verbose=False,
+    )
+    result = model.evaluate(X[300:], y[300:])
+    # Binary chance = 0.50. On synthetic data the graph is nearly fully
+    # connected (uniform cosine similarity), limiting GCN's ability to
+    # extract structural features. Real IDS data has natural clusters that
+    # produce a much sparser and more informative graph. The real validation
+    # is on NSL-KDD, not synthetic data — this test just confirms the
+    # pipeline doesn't crash and learns *something*.
+    assert result.accuracy > 0.50, f"accuracy {result.accuracy:.2f} not above chance"
+
+
+def test_predict_returns_known_labels():
+    X, y = _make_ids_data(n_samples=100, n_classes=2)
+    model = GraphIDS(n_features=20, n_classes=2)
+    model.train_pipeline(
+        X[:70], y[:70],
+        gcn_epochs=5, ae_epochs=5, clf_epochs=5,
+        verbose=False,
+    )
+    preds = model.predict(X[70:])
+    assert set(preds).issubset(set(y))
+
+
+def test_pipeline_with_string_labels():
+    X, y = _make_ids_data(n_samples=100, n_classes=3)
+    label_map = {0: "Normal", 1: "DoS", 2: "Probe"}
+    y_str = np.array([label_map[yi] for yi in y])
+
+    model = GraphIDS(n_features=20, n_classes=3)
+    model.train_pipeline(
+        X[:70], y_str[:70],
+        gcn_epochs=5, ae_epochs=5, clf_epochs=5,
+        verbose=False,
+    )
+    preds = model.predict(X[70:])
+    assert all(p in ["Normal", "DoS", "Probe"] for p in preds)